エラータイプ

TypeScript 関数では、出力タイプに加えて、エラータイプも宣言できます。これは、特にクエリでエラーを伝播して処理する場合に役立ちます。

エラータイプを定義する

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

複数の FunctionsError 型を和集合にして、関数で発生しうるエラーを定義できます。たとえば、従業員のチームメイトを取得する関数に対して、次のエラータイプを定義できます。

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

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
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> {
    ...
}

デフォルトでは、FunctionsResult 型には、TypeScript 関数のランタイム基盤が返す可能性のある以下のエラーが含まれています。

• FunctionsTypeScriptExecutorService:CpuTimeoutError： 関数が CPU 時間の上限を超えた場合に返されます。
• FunctionsTypeScriptExecutorService:WallTimeoutError： 関数が経過時間の上限を超えた場合に返されます。
• FunctionsTypeScriptExecutorService:OutOfMemoryError： 関数がメモリーの上限を超えた場合に返されます。
• FunctionsTypeScriptExecutorService:RuntimeError： 関数でその他の実行時エラーが発生した場合に返されます。

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

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

• FunctionsResult.ok： 1個の出力値を引数として受け取ります。
• 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
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();
    if (employees.length === 0) {
        return FunctionsResult.err("EmployeeNotFoundForId", employeeId);
    }

    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 を使って何らかの処理を行います
        ...
    }

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