チュートリアル：SuperRepo で開発する

SuperRepo は、コンポーネントの編集、プレビュー、デプロイを足並みをそろえて行えるため、フルスタックアプリケーションの構築に活用すると最大の価値を発揮します。

このチュートリアルでは、デフォルトの SuperRepo テンプレートに含まれるタスク管理アプリケーションを使用します。既存のオブジェクトタイプをインポートし、テンプレートのリンクタイプを探索する方法を学びます。また、関数ベースのアクションをフロントエンドに接続し、タスクを完了としてマークします。同じ開発ワークフローは、あらゆる分野のフルスタックアプリケーションに適用できます。

チュートリアルに沿って進めるには、リポジトリ作成フローを使用して SuperRepo を作成してください。このチュートリアルではオブジェクトを作成、編集するため、デフォルトの SEED_ONLY プレビューモードを維持してから、ローカルプレビューを開始します。テンプレートには、タスク、ワーカー、および以下に示す関数がすでに定義されています。アプリケーション内のチュートリアルでは、これらの定義を拡張し、フロントエンドに接続する手順を説明しています。

まず、SuperRepo リポジトリの構造を確認します。ルートには常に、プロジェクトのコンポーネントを定義する foundry.yml ファイルがあります。たとえば、ほかの設定に加えて、次のような内容が含まれている場合があります。

Copied!
1
2
3
4
5
6
7
components:
  - type: ONTOLOGY
    path: ./ontology
  - type: TYPESCRIPT_FUNCTIONS
    path: ./functions/typescript-functions
  - type: APP
    path: ./app

このファイルでコンポーネントを追加、複製、削除することで、プロジェクトの構成を変更できます。再構成のワークフローについては、高度なワークフローで詳しく説明しています。

以降のセクションでは、3つのレイヤーにわたって作業します。

1. オントロジーのタイプのインポートと定義を探索し、シードデータ内のタスクの割り当てを更新します。
2. TypeScript 関数と、その関数ベースのアクションの記述方法を理解します。
3. アクションをアプリケーションのフロントエンドに接続します。

既存のオブジェクトタイプをインポートする

Palantir プラットフォーム内のフルスタックアプリケーションのドメインモデルは、オントロジーで定義されます。SuperRepo では、foundry import ontology コマンドを実行するか、Visual Studio Code 用 Palantir 拡張機能のインポートサイドバーを使用して、既存のオントロジーのタイプをプロジェクトにインポートできます。

次に、ウィザードに従ってインポートするタイプを選択します。

最後に、プロジェクトにインポートボタンを選択すると、選択したタイプが Foundry プロジェクトにインポートされ、リポジトリ内でインポートをコードとして定義するために実行する必要がある foundry import ontology コマンドが表示されます。

オントロジーを拡張する

ontology/src/ontology.mts ファイルには、Ontology-as-code の定義が格納されます。Ontology-as-code では、TypeScript API ↗ を使用してオントロジーを拡張できます。たとえば、テンプレートでは TutorialWorker と TutorialTask の間のリンクタイプが定義されています。各ワーカーには多数のタスクを割り当てることができ、各タスクには1人の担当者を設定できます。次の定義は、テンプレートにすでに含まれています。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
export const assignedTasks: LinkType = defineLink({
  apiName: "assignedTasks",
  one: {
    object: TutorialWorker,
    metadata: { apiName: "assignedTasks" },
  },
  toMany: {
    object: TutorialTask,
    metadata: { apiName: "assignee" },
  },
  manyForeignKeyProperty: "assigneeId",
  editsEnabled: true,
});

ontology.mts ファイルが変更されるたびに、ローカルのオントロジー SDK パッケージが再生成されます。pnpm run dev（Windows では pnpm run dev:windows）で表示されるステータス表示で再ビルドの進行状況を確認し、Tab キーと矢印キーを使用して ontology:dev の出力を確認できます。

関数を追加する

SuperRepo は現在、TypeScript v2 関数をサポートしています。テンプレートでは、関数を使用してタスクを完了としてマークし、同じタスクが2回完了されることを防ぎます。

functions/typescript-functions/src/functions 内の completeTask.ts を開きます。このファイルに含まれる関数は、オントロジー SDK クライアントとタスクを引数として受け取り、タスクのステータスを更新する編集を返します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import { task } from "@ontology/sdk";
import { Client, Osdk } from "@osdk/client";
import { createEditBatch, Edits, UserFacingError } from "@osdk/functions";

export const COMPLETE = "Complete";

type OntologyEdit = Edits.Object<task>;

function completeTask(
  client: Client,
  taskToComplete: Osdk.Instance<task>,
): OntologyEdit[] {
  if (taskToComplete.status === COMPLETE) {
    throw new UserFacingError(
      `${taskToComplete.title ?? taskToComplete.$primaryKey} is already complete`,
    );
  }

  const batch = createEditBatch<OntologyEdit>(client);
  batch.update(taskToComplete, { status: COMPLETE });
  return batch.getEdits();
}

export const config = {
  apiName: "completeTask",
};

export default completeTask;

オントロジー SDK は、ontology.mts で使用されている定数名 TutorialTask と TutorialWorker ではなく、オブジェクトタイプの apiName の値に基づいて task と worker をエクスポートします。

Visual Studio Code 用 Palantir 拡張機能の関数サポート機能を使用すると、この関数をすぐにプレビューできます。

この TypeScript v2 関数はオントロジーの編集を返しますが、変更を反映するには、これらの編集をオントロジーに適用する必要があります。オントロジーの内容を変更できるのはアクションのみです。タスクのステータスを更新するには、completeTask を関数ベースのアクションとして公開します。

テンプレートでは、リンクタイプを定義するのと同じ ontology.mts ファイル内で、次のように defineFunctionBackedAction 関数を呼び出して、この関数をすでに公開しています。

Copied!
1
2
3
4
export const completeTaskAction: ActionType = defineFunctionBackedAction({
  functionApiName: "completeTask",
  apiName: "complete-task-action",
});

これにより、React アプリケーション内から、生成されたオントロジー SDK を通じて completeTaskAction を呼び出せます。

フロントエンドを通じてアクションを公開する

前のセクションでは、オブジェクトタイプのインポート、リンクタイプの作成、TypeScript v2 の関数ベースのアクションの定義について説明しました。Foundry CLI のプレビュープロセスにより、これらはすべて、ローカルで生成されたオントロジー SDK ライブラリを通じて公開されます。このライブラリは、オントロジー SDK の React アプリケーションから利用できます。

@osdk/react ライブラリ ↗ を使用すると、以下に示すように、新しく追加された項目に数行でアクセスできます。

Copied!
1
2
3
4
5
6
7
8
import { task, completeTaskAction } from "@ontology/sdk";
import {
  useOsdkAction,
  useOsdkObjects,
} from "@osdk/react";

const { data: tasks } = useOsdkObjects(task, { pageSize: 50 });
const completeAction = useOsdkAction(completeTaskAction);

これらのフックは、app/src/tutorial/Demo.tsx の Demo コンポーネント内ですでに呼び出されています。完了としてマークボタンを有効にするには、getCompleteHandler 内のハンドラーを囲むコメント記号を削除し、return null を削除します。

Copied!
1
2
3
4
5
6
7
function getCompleteHandler():
  | ((taskToComplete: Osdk.Instance<task>) => Promise<void>)
  | null {
  return async (taskToComplete) => {
    await completeAction.applyAction({ taskToComplete });
  };
}

実行中のプレビューアプリケーションで、チュートリアルのナビゲーションから独自のロジックを追加を選択します。ライブプレビューで、未完了のタスクの完了としてマークを選択します。そのステータスが完了に変わります。各ワーカーに割り当てられたタスクを表示するには、チュートリアルのナビゲーションでオブジェクトの関係を定義を選択します。この表示では、useLinks(item, "assignedTasks", { pageSize: 50 }) を使用して、上で定義したリンクをたどります。

結論

リポジトリや IDE を離れることなく、タスクの割り当てを更新し、関数とその関数ベースのアクションを探索し、オントロジー SDK を通じてフロントエンドと統合しました。

SuperRepo が登場する以前は、この機能を実装するために、4個のアプリケーションを行き来し、CI チェックを待ち、オントロジー SDK を何度も再公開する必要がありました。SuperRepo は、そのような手間をなくすために設計されています。

次のステップ

• 複数の製品の宣言、プレビュー用シードデータの定義、プラットフォーム API プロキシの設定については、高度なワークフローを確認してください。
• エンロールメントに製品をインストールするには、初回デプロイの準備を進めてください。