Async/await в TypeScript: типы, ошибки и параллельные вызовы

Функция async в TypeScript всегда возвращает промис: если её тело возвращает 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, описанный в разделе async/await в JavaScript. Часть TypeScript это типы на входе и выходе.

Типы возврата асинхронных функций

Объявленный тип возврата функции 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 оставляет у вас Promise<T> вместо 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) настоящая: объект промиса всегда истинен, поэтому доступ был предоставлен. TypeScript сообщает о ней как TS2801. Присваивание промиса переменной boolean или чтение свойства, которого у промиса нет, тоже не скомпилировалось бы. Вызов, результат которого игнорируется (save(user);), не ловится; для этого есть правило typescript-eslint no-floating-promises.

Обработка ошибок через try/catch

Отклонённый промис заставляет 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

throw внутри функции async отклоняет её промис, а не выбрасывает ошибку в месте вызова. Больше приёмов, включая собственные классы ошибок и возврат результатов вместо выбрасывания, есть на странице обработка ошибок.

await верхнего уровня

await вне любой функции работает только в модуле ES. Файл, скомпилированный как CommonJS (так обстоит дело с этими примерами и с проектами Node без "type": "module"), его отвергает:

// 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 ("type": "module" в package.json с module, равным node16 или nodenext, или module: "esnext" для бандлера) await верхнего уровня разрешён.

По очереди и параллельно

Каждый await ждёт свой промис, прежде чем начнётся следующая строка. Для независимых вызовов сначала запустите их все, а затем дождитесь вместе через Promise.all:

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-колбэк, поэтому работу никто не ждёт:

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();

for...of с await обрабатывает элементы по одному; Promise.all с map запускает их параллельно и ждёт все. forEach не делает ни того, ни другого, и TypeScript не предупреждает, потому что колбэк с типом возврата void принимает и тот, что возвращает промис.

Асинхронная итерация через for await

for await...of перебирает асинхронный итерируемый объект, например асинхронный генератор, дожидаясь каждого значения:

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> или выводится, если её не указать.