Promise в TypeScript: Promise<T>, Promise.all и allSettled

В TypeScript у промиса тип Promise<T>, где T это тип значения, которым он разрешается. Функция, которая возвращает промис, объявляет это в типе возврата, а значение, полученное из 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
});

Механика промисов (состояния, очередь микрозадач, цепочки) это обычный JavaScript, описанный в разделе промисы в JavaScript. Эта страница о типах.

Типизация new Promise и resolve

Когда new Promise это возвращаемое значение функции с объявленным типом возврата, T берётся оттуда. Сам по себе TypeScript не выводит T из вызовов resolve, и вы получаете 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();

Две детали. resolve типизирован по T, поэтому resolve("42") в Promise<number> это ошибка компиляции. А 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> нет: промис может отклониться с любым значением.

then, catch и finally

Каждый then возвращает новый промис, типизированный тем, что возвращает его колбэк. Если колбэк возвращает промис, 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 в стандартной библиотеке типизирован как any, а не unknown. Ничто не мешает написать e.message для значения, которое может оказаться строкой. Аннотируйте его как unknown, как выше, и сужайте перед использованием. try/catch вокруг await справляется лучше: при strict его переменная catch уже имеет тип unknown (см. обработку ошибок).

Promise.all возвращает кортеж

Для литерала массива из промисов разных типов Promise.all возвращает промис кортежа, где каждая позиция сохраняет свой тип:

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.all отклоняется, как только отклоняется один вход, и остальные результаты теряются. Promise.race разрешается или отклоняется с первым завершившимся и типизирован как объединение входов; Promise.any разрешается первым успехом и отклоняется с AggregateError, только если провалились все входы.

Promise.allSettled и тип его результата

Promise.allSettled ждёт каждый вход и никогда не отклоняется. Каждый результат это 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();

r.value существует только после проверки status, потому что у отклонённого варианта нет value. reason имеет тип any по той же причине, что и в catch. filter использует предикат типа, чтобы отфильтрованный массив был типизирован как выполненные результаты.

Обёртка API на колбэках в промис

Старые API сообщают результаты через колбэк, часто в стиле Node (err, result) => void. Оберните их один раз в функцию, которая возвращает типизированный промис, и остальной код сможет использовать 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 это делает util.promisify для функций, следующих соглашению (err, result), а у многих встроенных модулей уже есть версии на промисах (node:fs/promises, node:timers/promises).

Частые ошибки

• Возвращать T там, где сигнатура говорит Promise<T>, или наоборот. Не-async функция, объявленная как Promise<User>, должна возвращать промис; функция async возвращает его автоматически.
• Забыть обработать промис. Вызов вроде save(user); без await, then или catch прекрасно компилируется, а отклонение становится необработанным (по умолчанию это завершает процесс Node). Такие места ловит правило typescript-eslint no-floating-promises.
• Доверять типу .catch((e) => ...). Его e имеет тип any. Аннотируйте его как unknown.
• Оборачивать в new Promise то, что уже возвращает промис. Просто верните существующий промис или дождитесь его через await.