Async/await in TypeScript: tipi, errori e chiamate in parallelo

Una funzione async in TypeScript restituisce sempre una promise: se il suo corpo restituisce una string, il suo tipo è Promise<string>. Al suo interno, await scarta una Promise<T> e ne ricava un 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();

Il comportamento a runtime (cosa mette in pausa await, l'event loop) è JavaScript, trattato in async/await in JavaScript. La parte di TypeScript sono i tipi in entrata e in uscita.

Tipi di ritorno delle funzioni async

Il tipo di ritorno dichiarato di una funzione async deve essere Promise<...>, anche se il corpo restituisce il valore semplice. Se lo ometti, TypeScript lo deduce.

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

Scrivere async function count(): number è l'errore TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). Il tipo di utilità Awaited<T> dà il tipo scartato: Awaited<ReturnType<typeof count>> è number.

Dimenticare await

Un await mancante ti lascia in mano una Promise<T> invece di un T. TypeScript ne intercetta la maggior parte perché i tipi non combaciano più:

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

Il bug di if (ok) è reale: un oggetto promise è sempre truthy, quindi ha concesso l'accesso. TypeScript lo segnala come TS2801. Anche assegnare la promise a una variabile boolean, o leggere una proprietà che la promise non ha, non compilerebbe. Una chiamata di cui ignori il risultato (save(user);) non viene intercettata; se ne occupa la regola di typescript-eslint no-floating-promises.

Gestione degli errori con try/catch

Una promise rifiutata fa lanciare un errore ad await, quindi il normale try/catch funziona. Con strict, la variabile nel catch è unknown, e la restringi prima di leggere .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

Un throw dentro una funzione async rifiuta la sua promise invece di lanciare l'errore nel punto della chiamata. Altri pattern, tra cui classi di errore personalizzate e restituire risultati invece di lanciare, sono nella pagina sulla gestione degli errori.

await top-level

await fuori da qualsiasi funzione funziona solo in un modulo ES. Un file compilato come CommonJS (il caso di questi esempi, e dei progetti Node senza "type": "module") lo rifiuta:

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

Avvolgi il codice in una funzione main async e chiamala, come fa ogni esempio di questa pagina. In un progetto con moduli ES ("type": "module" in package.json con module impostato a node16 o nodenext, oppure module: "esnext" per un bundler), l'await top-level è consentito.

Sequenziale vs parallelo

Ogni await aspetta la sua promise prima che parta la riga successiva. Per chiamate indipendenti, avviale tutte prima e attendile insieme con 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();

Nella metà sequenziale, b non può finire prima di a perché non è ancora partita. Nella metà parallela, d finisce per prima, e il tempo totale è circa quello della chiamata più lunga invece della somma. Promise.all restituisce comunque i risultati nell'ordine di input, tipizzati come tupla.

La trappola di forEach

forEach ignora la promise restituita da una callback async, quindi nessuno aspetta il lavoro:

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 con await elabora gli elementi uno alla volta; Promise.all con map li esegue in parallelo e li attende tutti. forEach non fa né l'una né l'altra cosa, e TypeScript non avvisa, perché una callback tipizzata per restituire void ne accetta una che restituisce una promise.

Iterazione asincrona con for await

for await...of scorre un iterabile asincrono, come un generatore async, attendendo ogni valore:

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

Il tipo dell'elemento viene dall'annotazione AsyncGenerator<T> del generatore, o dall'inferenza se la ometti.