Async await en TypeScript : types, erreurs et appels parallèles

En TypeScript, une fonction async renvoie toujours une promesse : si son corps renvoie une string, son type est Promise<string>. À l'intérieur, await déballe une Promise<T> en 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();

Le comportement à l'exécution (ce que await met en pause, la boucle d'événements) relève du JavaScript, présenté dans async/await en JavaScript. La part de TypeScript, ce sont les types en entrée et en sortie.

Types de retour des fonctions async

Le type de retour déclaré d'une fonction async doit être Promise<...>, même si le corps renvoie la valeur brute. TypeScript le déduit si vous l'omettez.

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

Écrire async function count(): number provoque l'erreur TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). Le type utilitaire Awaited<T> donne le type déballé : Awaited<ReturnType<typeof count>> vaut number.

Oublier await

Un await manquant vous laisse avec une Promise<T> au lieu d'un T. TypeScript détecte la plupart de ces oublis, car les types ne correspondent plus :

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

Le bug du if (ok) est réel : un objet promesse est toujours truthy, donc l'accès était accordé. TypeScript le signale avec TS2801. Affecter la promesse à une variable boolean, ou lire une propriété que la promesse n'a pas, échouerait aussi à la compilation. Un appel dont vous ignorez le résultat (save(user);) n'est pas détecté ; la règle typescript-eslint no-floating-promises couvre ce cas.

Gérer les erreurs avec try/catch

Une promesse rejetée fait lever une exception à await, donc un try/catch ordinaire fonctionne. Sous strict, la variable du catch est unknown, et vous restreignez son type avant de lire .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 dans une fonction async rejette sa promesse au lieu de lever l'exception à l'endroit de l'appel. D'autres techniques, dont les classes d'erreur personnalisées et le renvoi de résultats plutôt que les exceptions, sont sur la page gestion des erreurs.

await de premier niveau

Un await en dehors de toute fonction ne fonctionne que dans un module ES. Un fichier compilé en CommonJS (le cas de ces exemples, et des projets Node sans "type": "module") le refuse :

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

Placez le code dans une fonction main async et appelez-la, comme le font tous les exemples de cette page. Dans un projet en modules ES ("type": "module" dans package.json avec module réglé sur node16 ou nodenext, ou module: "esnext" pour un bundler), le await de premier niveau est autorisé.

Séquentiel ou parallèle

Chaque await attend sa promesse avant que la ligne suivante ne commence. Pour des appels indépendants, lancez-les tous d'abord et attendez-les ensemble avec 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();

Dans la partie séquentielle, b ne peut pas finir avant a, puisqu'il n'a pas encore démarré. Dans la partie parallèle, d finit en premier, et la durée totale correspond à peu près à l'appel le plus long plutôt qu'à la somme. Promise.all renvoie quand même les résultats dans l'ordre des entrées, typés comme un tuple.

Le piège de forEach

forEach ignore la promesse que renvoie un callback async, donc rien n'attend la fin du travail :

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 avec await traite les éléments un par un ; Promise.all avec map les exécute en parallèle et attend qu'ils soient tous terminés. forEach ne fait ni l'un ni l'autre, et TypeScript ne prévient pas, car un callback typé pour renvoyer void accepte un callback qui renvoie une promesse.

Itération asynchrone avec for await

for await...of parcourt un itérable asynchrone, comme un générateur async, en attendant chaque valeur :

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

Le type des éléments vient de l'annotation AsyncGenerator<T> du générateur, ou de l'inférence si vous l'omettez.