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

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

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

チュートリアルに沿って進めるには、リポジトリ作成フローを使用して SuperRepo を作成し、ローカルプレビューを起動してください。テンプレートには、タスク、ワーカー、および以下に示す関数がすでに定義されています。アプリケーション内のチュートリアルでは、これらの定義を拡張してフロントエンドに接続する手順を案内します。

まず、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 が定義されており、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 プロキシの設定については、高度なワークフローを確認してください。
• エンロールメントに製品をインストールするには、初回のデプロイの準備を進めます。