TypeScriptのPromise: Promise<T>、Promise.all、allSettled

TypeScriptでは、Promise の型は Promise<T> で、T は解決される値の型です。Promise を返す関数は戻り値の型でそれを宣言し、then や await で得られる値は T 型になります。

type User = { id: number; name: string };

function fetchUser(id: number): Promise<User> {
    return new Promise((resolve) => {
        setTimeout(() => resolve({ id, name: "Ada" }), 50);
    });
}

fetchUser(1).then((user) => {
    // user is User here
    console.log(user.name.toUpperCase()); // ADA
});

Promise の仕組み（状態、マイクロタスクキュー、チェーン）は普通のJavaScriptで、JavaScriptのPromise で説明しています。このページは型についてです。

new Promise と resolve の型付け

new Promise が戻り値の型を宣言した関数の戻り値なら、T はそこから決まります。それ以外では、TypeScriptは resolve の呼び出しから T を推論せず、Promise<unknown> になります。型引数を明示的に渡しましょう:

const untyped = new Promise((resolve) => resolve(42));
// untyped is Promise<unknown>

const typed = new Promise<number>((resolve, reject) => {
    const n = 42;
    if (n < 0) reject(new Error("negative"));
    else resolve(n);
});

// A promise that resolves with no value is Promise<void>.
const done = new Promise<void>((resolve) => setTimeout(resolve, 10));

async function main() {
    const n = await typed;
    console.log(n.toFixed(1)); // 42.0
    await done;
    console.log("done");
    const u = await untyped;
    // @ts-expect-error: 'u' is of type 'unknown'.
    console.log(u.toFixed(1)); // 42.0 at runtime, but the compiler cannot know that
}
main();

細かい点が2つあります。resolve は T から型付けされるので、Promise<number> の中の resolve("42") はコンパイルエラーです。そして引数なしの resolve() が許可されるのは T が void を含むときだけで、Promise<number> ではエラー TS2794（Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?）になります。

reject の側は型付けされていません。Promise<T, E> というものはなく、Promise はどんな値でも reject できます。

then、catch、finally

then はそれぞれ、コールバックが返す値で型付けされた新しい Promise を返します。コールバックが Promise を返せばTypeScriptがそれを展開するので、Promise<Promise<T>> になることはありません。

const price = Promise.resolve("19.99");

const withTax = price
    .then((s) => Number(s))                     // Promise<number>
    .then((n) => Promise.resolve(n * 1.2))      // still Promise<number>
    .then((n) => n.toFixed(2));                 // Promise<string>

withTax
    .then((s) => console.log(s)) // 23.99
    .catch((e: unknown) => {
        console.log(e instanceof Error ? e.message : String(e));
    })
    .finally(() => console.log("finished"));

標準ライブラリでは、catch のコールバックの引数は unknown ではなく any です。文字列かもしれない値に e.message と書いても止められません。上の例のように unknown と型注釈を付け、使う前に絞り込みましょう。await を try/catch で囲む方法のほうが優れています。strict のもとでは、その catch の変数は最初から unknown です（エラー処理 を参照）。

Promise.all はタプルを返す

型の違う Promise の配列リテラルを渡すと、Promise.all はタプルの Promise を返し、各位置がそれぞれの型を保ちます:

const getUser = () => Promise.resolve({ name: "Ada" });
const getCount = () => Promise.resolve(3);
const getTags = () => Promise.resolve(["admin", "dev"]);

async function main() {
    const [user, count, tags] = await Promise.all([getUser(), getCount(), getTags()]);
    // user: { name: string }, count: number, tags: string[]
    console.log(user.name, count + 1, tags.join("/")); // Ada 4 admin/dev

    // Same element type: the result is an array.
    const ids = [1, 2, 3];
    const doubled = await Promise.all(ids.map((id) => Promise.resolve(id * 2)));
    console.log(doubled); // [ 2, 4, 6 ]
}
main();

Promise ではない値を混ぜることもでき、それはそのまま通ります。Promise.all は入力が1つ reject するとすぐに reject し、ほかの結果は失われます。Promise.race は最初に確定したもので解決または reject し、型は入力のユニオン型です。Promise.any は最初に成功したもので解決し、すべての入力が失敗した場合にだけ AggregateError で reject します。

Promise.allSettled とその結果の型

Promise.allSettled はすべての入力を待ち、reject することはありません。各結果は PromiseSettledResult<T> で、status フィールドで絞り込むユニオン型です:

function load(id: number): Promise<string> {
    return id % 2 === 0
        ? Promise.resolve(`item ${id}`)
        : Promise.reject(new Error(`item ${id} not found`));
}

async function main() {
    const results = await Promise.allSettled([load(1), load(2), load(4)]);

    for (const r of results) {
        if (r.status === "fulfilled") {
            console.log("ok:", r.value); // value: string
        } else {
            // reason: any, so narrow it like a caught error
            console.log("failed:", r.reason instanceof Error ? r.reason.message : r.reason);
        }
    }

    const values = results
        .filter((r): r is PromiseFulfilledResult<string> => r.status === "fulfilled")
        .map((r) => r.value);
    console.log(values); // [ 'item 2', 'item 4' ]
}
main();

reject された側には value がないので、r.value は status のチェックのあとでしか存在しません。reason は catch と同じ理由で any です。filter では、絞り込んだ配列が fulfilled の結果として型付けされるように型述語を使っています。

コールバックのAPIを Promise でラップする

古いAPIは結果をコールバックで返し、多くは Node スタイルの (err, result) => void です。型付きの Promise を返す関数で一度ラップすれば、残りのコードで await が使えます:

type Callback<T> = (err: Error | null, result?: T) => void;

// An old-style API.
function lookupPort(service: string, cb: Callback<number>): void {
    setTimeout(() => {
        if (service === "http") cb(null, 80);
        else cb(new Error(`unknown service ${service}`));
    }, 10);
}

function lookupPortAsync(service: string): Promise<number> {
    return new Promise((resolve, reject) => {
        lookupPort(service, (err, port) => {
            if (err) reject(err);
            else resolve(port!); // present whenever err is null
        });
    });
}

async function main() {
    console.log(await lookupPortAsync("http")); // 80
    try {
        await lookupPortAsync("gopher");
    } catch (e) {
        if (e instanceof Error) console.log(e.message); // unknown service gopher
    }
}
main();

Node では、(err, result) の規約に従う関数なら util.promisify がこれを行ってくれますし、多くの組み込みモジュールにはすでに Promise 版があります（node:fs/promises、node:timers/promises）。

よくある間違い

• シグネチャが Promise<T> なのに T を返す、またはその逆。 Promise<User> と宣言した async ではない関数は Promise を返さなければなりません。async 関数は自動的に Promise を返します。
• Promise の処理を忘れる。 await、then、catch のない save(user); のような呼び出しは問題なくコンパイルでき、reject は未処理の reject になります（Node ではデフォルトでプロセスが終了します）。typescript-eslint のルール no-floating-promises でこれを捕まえられます。
• .catch((e) => ...) の型を信用する。 その e は any です。unknown と型注釈を付けましょう。
• すでに Promise を返すものを new Promise で囲む。 既存の Promise をそのまま返すか await しましょう。