Async await em TypeScript: tipos, erros e chamadas paralelas

Uma função async em TypeScript sempre retorna uma promise: se o corpo dela retorna uma string, o tipo é Promise<string>. Dentro dela, await desembrulha uma Promise<T> em um 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();

O comportamento em tempo de execução (o que o await pausa, o event loop) é JavaScript, coberto em async/await em JavaScript. A parte do TypeScript são os tipos que entram e saem.

Tipos de retorno de funções async

O tipo de retorno declarado de uma função async precisa ser Promise<...>, mesmo que o corpo retorne o valor simples. O TypeScript o infere se você não o escrever.

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

Escrever async function count(): number dá o erro TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). O utility type Awaited<T> dá o tipo desembrulhado: Awaited<ReturnType<typeof count>> é number.

Esquecendo o await

Um await que falta deixa você com uma Promise<T> em vez de um T. O TypeScript pega a maioria desses casos porque os tipos deixam de encaixar:

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

O bug do if (ok) é real: um objeto promise é sempre truthy, então o acesso foi concedido. O TypeScript o reporta como TS2801. Atribuir a promise a uma variável boolean, ou ler uma propriedade que a promise não tem, também não compilaria. Uma chamada cujo resultado você ignora (save(user);) não é pega; a regra no-floating-promises do typescript-eslint cobre esse caso.

Tratamento de erros com try/catch

Uma promise rejeitada faz o await lançar um erro, então o try/catch comum funciona. Com strict, a variável do catch é unknown, e você a estreita antes de ler .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

Um throw dentro de uma função async rejeita a promise dela em vez de lançar o erro no ponto da chamada. Mais padrões, incluindo classes de erro personalizadas e retornar resultados em vez de lançar erros, estão na página de tratamento de erros.

Top-level await

await fora de qualquer função só funciona em um módulo ES. Um arquivo compilado como CommonJS (o caso destes exemplos, e de projetos Node sem "type": "module") o rejeita:

// 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.

Envolva o código em uma função main async e chame-a, como todos os exemplos desta página fazem. Em um projeto com módulos ES ("type": "module" no package.json com module definido como node16 ou nodenext, ou module: "esnext" para um bundler), o await no nível superior é permitido.

Sequencial vs paralelo

Cada await espera a sua promise antes de a próxima linha começar. Para chamadas independentes, inicie todas primeiro e aguarde-as juntas com 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();

Na metade sequencial, b não consegue terminar antes de a porque ainda não começou. Na metade paralela, d termina primeiro, e o tempo total é mais ou menos o da chamada mais longa, não a soma. Promise.all ainda retorna os resultados na ordem de entrada, tipados como uma tupla.

A armadilha do forEach

forEach ignora a promise que um callback async retorna, então nada espera o trabalho:

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 com await processa os itens um de cada vez; Promise.all com map os executa em paralelo e espera todos. forEach não faz nenhum dos dois, e o TypeScript não avisa, porque um callback tipado para retornar void aceita um que retorna uma promise.

Iteração assíncrona com for await

for await...of percorre um iterável assíncrono, como um async generator, aguardando cada valor:

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

O tipo do elemento vem da anotação AsyncGenerator<T> do generator, ou da inferência quando você não a escreve.