エラータイプ

TypeScript関数に出力タイプを宣言することに加えて、エラータイプを宣言することもできます。これは、クエリのコンテキストでエラーを伝播および処理するのに特に有用です。

エラータイプを定義する

@foundry/functions-apiからエクスポートされるFunctionsErrorタイプを使用してエラータイプを定義できます。これは2個のタイプパラメーターを取ります。1つは文字列の名前、もう1つは省略可能なタイプで、デフォルトは空のオブジェクトです。関数の有効な出力タイプはすべてエラータイプとして使用できます。オブジェクトやオブジェクトセットも含まれます。

複数のFunctionsErrorタイプを結合して、関数の可能なエラーのセットを定義できます。たとえば、従業員のチームメイトを取得する関数のために以下のエラータイプを定義できます。

Copied!
1
2
3
4
5
6
7
8
9
import { FunctionsError } from "@foundry/functions-api";
import { Employee } from "@foundry/ontology-api";

// GetTeammatesError型は、以下の2つのエラー型のいずれかを表します。
// - EmployeeNotFoundForId: 指定されたIDに対応する従業員が見つからない場合のエラー。
// - MultipleEmployeesFoundForId: 指定されたIDに複数の従業員が見つかった場合のエラー。
type GetTeammatesError =
    | FunctionsError<"EmployeeNotFoundForId", string>
    | FunctionsError<"MultipleEmployeesFoundForId", { employees: Employee[], employeeId: string }>

関数でエラータイプを宣言する

TypeScript関数でエラータイプを宣言するには、@foundry/functions-apiからエクスポートされたFunctionsResultタイプを使用できます。これは 2 個の型パラメーターを取ります。出力タイプとエラータイプです。

前のセクションのGetTeammatesErrorの例を使用して、関数でエラータイプを次のように宣言できます:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { Function, FunctionsError, FunctionsResult } from "@foundry/functions-api";
import { Employee } from "@foundry/ontology-api";

type GetTeammatesError =
    // EmployeeNotFoundForId: 指定したIDの従業員が見つからない場合のエラー
    | FunctionsError<"EmployeeNotFoundForId", string>
    // MultipleEmployeesFoundForId: 指定したIDに対して複数の従業員が見つかった場合のエラー
    | FunctionsError<"MultipleEmployeesFoundForId", { employees: Employee[], employeeId: string }>

@Function()
public getTeammates(employeeId: string): FunctionsResult<Employee[], GetTeammatesError> {
    // 指定された従業員IDに基づいてチームメイトを取得する関数
    ...
}

デフォルトでは、FunctionsResult 型に TypeScript 関数のランタイムインフラストラクチャから返されるいくつかのエラーが含まれています。

• FunctionsTypeScriptExecutorService:CpuTimeoutError: 関数が CPU 時間の制限を超えた場合に返されます。
• FunctionsTypeScriptExecutorService:WallTimeoutError: 関数がウォール時間の制限を超えた場合に返されます。
• FunctionsTypeScriptExecutorService:OutOfMemoryError: 関数がメモリの制限を超えた場合に返されます。
• FunctionsTypeScriptExecutorService:RuntimeError: 関数が他のランタイムエラーに遭遇した場合に返されます。

関数で出力とエラーを返す

出力とエラーを返すには、@foundry/functions-api からエクスポートされる FunctionsResult.ok および FunctionsResult.err メソッドを使用できます。

• FunctionsResult.ok: 単一の出力値を引数として取ります。
• FunctionsResult.err: エラー名と値を引数として取ります。

前のセクションの getTeammates の例を使用して、出力とエラーを次のように返すことができます。

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
import { Function, FunctionsError, FunctionsResult } from "@foundry/functions-api";
import { Employee } from "@foundry/ontology-api";

type GetTeammatesError =
    | FunctionsError<"EmployeeNotFoundForId", string>
    | FunctionsError<"MultipleEmployeesFoundForId", { employees: Employee[], employeeId: string }>

@Function()
public getTeammates(employeeId: string): FunctionsResult<Employee[], GetTeammatesError> {
    const employees = await Objects.search().employee([employeeId]).allAsync();
    // 社員IDに対応する社員が見つからなかった場合のエラーハンドリング
    if (employees.length === 0) {
        return FunctionsResult.err("EmployeeNotFoundForId", employeeId);
    }

    // 複数の社員が同じIDで見つかった場合のエラーハンドリング
    if (employees.length > 1) {
        return FunctionsResult.err("MultipleEmployeesFoundForId", { employees, employeeId });
    }

    const employee = employees[0];
    const teammates = await employee.teammates.allAsync();
    // チームメイトのリストを返す
    return FunctionsResult.ok(teammates);
}

クエリからのエラーを処理する

エラータイプの関数が別のリポジトリからクエリとして呼び出された場合、Resultタイプのレスポンスを返します。これは、okまたはerrの結果となる可能性があります。

@foundry/functions-apiからエクスポートされるisOkまたはisErrタイプガードを使用して、2 つの可能な結果を区別できます。たとえば、前のセクションのgetTeammatesの例を、クエリとして公開したと仮定し、以下のようにレスポンスを処理します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { Function, isOk } from "@foundry/function-api";
import { getTeammates } from "@foundry/ontology-api/queries";

@Function()
public async myFunction(employeeId: string): Promise<string> {
    const result = await getTeammates({ employeeId });

    if (isOk(result)) {
        const teammates = result.value;
        // "teammates"を使って何か処理を行う
        ...
    }

    // エラー名によってcase分岐し、"value"フィールドを使ってエラーの値を取得することができます
    switch (result.error.name) {
        case "EmployeeNotFoundForId": ...
        case "MultipleEmployeesFoundForId": ...
        case "FunctionsTypescriptExecutorService:OutOfMemoryError": ...
        ...
    }
}