TypeScriptのasync/await: 型、エラー処理、並列実行

TypeScriptの async 関数は常に Promise を返します。本体が string を返すなら、型は Promise<string> です。その中では、await が Promise<T> を T に展開します。

type Order = { id: number; total: number };

function fetchOrder(id: number): Promise<Order> {
    return new Promise((resolve) => setTimeout(() => resolve({ id, total: 42 }), 20));
}

async function orderSummary(id: number): Promise<string> {
    const order = await fetchOrder(id); // order: Order, not Promise<Order>
    return `Order #${order.id}: $${order.total.toFixed(2)}`;
}

async function main() {
    const text = await orderSummary(7);
    console.log(text); // Order #7: $42.00
}
main();

実行時の動き（await が何を一時停止するか、イベントループ）はJavaScriptのもので、JavaScriptのasync/await で説明しています。TypeScriptが担当するのは、入る型と出る型です。

async 関数の戻り値の型

本体は普通の値を返しますが、async 関数の宣言された戻り値の型は Promise<...> でなければなりません。省略すればTypeScriptが推論します。

async function count(): Promise<number> {
    return 3; // a number, wrapped in a promise automatically
}

async function log(message: string): Promise<void> {
    console.log(message); // returns nothing: Promise<void>
}

const double = async (n: number) => n * 2; // inferred: (n: number) => Promise<number>

class Repo {
    async findName(id: number): Promise<string | undefined> {
        return id === 1 ? "Ada" : undefined;
    }
}

async function main() {
    await log("start");
    console.log(await count(), await double(21)); // 3 42
    console.log(await new Repo().findName(2));   // undefined
}
main();

async function count(): number と書くとエラー TS1064（The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?）です。ユーティリティ型 Awaited<T> は展開した型を返します。Awaited<ReturnType<typeof count>> は number です。

await を忘れる

await を忘れると、T ではなく Promise<T> を持つことになります。型が合わなくなるので、TypeScriptはたいていこれを捕まえます:

async function isAdmin(id: number): Promise<boolean> {
    return id === 1;
}

async function main() {
    const ok = isAdmin(2); // forgot await: ok is Promise<boolean>

    // @ts-expect-error: This condition will always return true since this 'Promise<boolean>' is always defined.
    if (ok) console.log("access granted (wrong!)");

    if (await isAdmin(2)) console.log("never printed");
    else console.log("access denied"); // correct
}
main();

if (ok) のバグは現実のものです。Promise オブジェクトは常に truthy なので、アクセスを許可してしまいました。TypeScriptはこれを TS2801 として報告します。Promise を boolean 型の変数に代入したり、Promise にないプロパティを読んだりしても、コンパイルエラーになります。結果を無視する呼び出し（save(user);）は捕まえられません。それには typescript-eslint のルール no-floating-promises を使います。

try/catch によるエラー処理

reject された Promise を await すると例外が投げられるので、普通の try/catch が使えます。strict のもとでは catch の変数は unknown なので、.message を読む前に絞り込みます:

async function loadConfig(name: string): Promise<{ port: number }> {
    if (name !== "prod") throw new Error(`no config named "${name}"`);
    return { port: 443 };
}

async function main() {
    try {
        const cfg = await loadConfig("dev");
        console.log(cfg.port);
    } catch (e) {
        // e: unknown
        if (e instanceof Error) console.log("failed:", e.message);
        else console.log("failed with", e);
    } finally {
        console.log("cleanup runs either way");
    }
}
main();
// failed: no config named "dev"
// cleanup runs either way

async 関数の中の throw は、呼び出し箇所で例外を投げるのではなく、その関数の Promise を reject します。独自のエラークラスや、例外を投げずに結果を返す方法など、ほかのパターンは エラー処理 のページにあります。

トップレベルの await

関数の外の await が使えるのは ES モジュールだけです。CommonJS としてコンパイルされるファイル（このページの例や、"type": "module" のない Node のプロジェクト）では拒否されます:

// This does not compile: top-level await in a CommonJS file.
const data = await Promise.resolve([1, 2, 3]);
console.log(data);

index.ts(2,14): error TS1309: The current file is a CommonJS module and cannot use 'await' at the top level.

このページのすべての例と同じように、コードを async な main 関数で囲んで呼び出しましょう。ES モジュールのプロジェクト（package.json に "type": "module" があり、module が node16 か nodenext、またはバンドラー向けの module: "esnext"）では、トップレベルの await が使えます。

逐次実行と並列実行

await はそれぞれ、Promise を待ってから次の行を始めます。互いに独立した呼び出しなら、先にすべてを開始し、Promise.all でまとめて await しましょう:

const wait = (ms: number, label: string) =>
    new Promise<string>((resolve) => setTimeout(() => {
        console.log(`  finished ${label}`);
        resolve(label);
    }, ms));

async function main() {
    console.log("sequential:");
    const a = await wait(60, "a");
    const b = await wait(20, "b"); // starts only after a is done
    console.log(" ", [a, b]);

    console.log("parallel:");
    const [c, d] = await Promise.all([wait(60, "c"), wait(20, "d")]);
    console.log(" ", [c, d]); // results keep input order
}
main();

逐次実行の前半では、b はまだ始まっていないので a より先に終わることはありません。並列実行の後半では d が先に終わり、全体の時間は合計ではなく、いちばん長い呼び出しとほぼ同じになります。それでも Promise.all は結果を入力の順序で、タプルとして型付けして返します。

forEach の落とし穴

forEach は async のコールバックが返す Promise を無視するので、処理を待つものは何もありません:

const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

async function main() {
    const ids = [1, 2, 3];

    ids.forEach(async (id) => {
        await sleep(10);
        console.log("forEach saved", id);
    });
    console.log("after forEach (runs first!)");
    await sleep(50); // only so the output above appears in order

    for (const id of ids) {
        await sleep(10);
        console.log("for...of saved", id);
    }
    console.log("after for...of (really after)");

    await Promise.all(ids.map(async (id) => {
        await sleep(10);
        console.log("map saved", id);
    }));
    console.log("after Promise.all (really after)");
}
main();

await を使った for...of は要素を1つずつ処理し、map と組み合わせた Promise.all は並列に実行してすべてを待ちます。forEach はそのどちらでもなく、TypeScriptも警告しません。void を返すと型付けされたコールバックは、Promise を返すコールバックも受け付けるからです。

for await による非同期の反復

for await...of は、非同期ジェネレーターのような非同期イテラブルをループし、各値を await します:

async function* pages(total: number): AsyncGenerator<string[]> {
    for (let page = 1; page <= total; page++) {
        await new Promise((r) => setTimeout(r, 10));
        yield [`item ${page}a`, `item ${page}b`];
    }
}

async function main() {
    for await (const batch of pages(3)) {
        console.log(batch.join(", ")); // batch: string[]
    }
}
main();

要素の型は、ジェネレーターの AsyncGenerator<T> の型注釈から、または省略した場合は推論から決まります。