Promise en TypeScript : Promise<T>, Promise.all et allSettled

En TypeScript, une promesse a le type Promise<T>, où T est le type de la valeur avec laquelle elle se résout. Une fonction qui renvoie une promesse le déclare dans son type de retour, et la valeur obtenue avec then ou await a le type 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
});

Le fonctionnement des promesses (états, file des microtâches, chaînage) relève du JavaScript pur, présenté dans les promesses JavaScript. Cette page porte sur les types.

Typer new Promise et resolve

Quand new Promise est la valeur renvoyée par une fonction dont le type de retour est déclaré, T vient de ce type. Seul, TypeScript ne déduit pas T des appels à resolve, et vous obtenez Promise<unknown>. Passez l'argument de type explicitement :

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

Deux détails. resolve est typé à partir de T, donc resolve("42") dans une Promise<number> est une erreur de compilation. Et resolve() sans argument n'est autorisé que si T inclut void : dans une Promise<number>, c'est l'erreur TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

Le côté reject n'est pas typé. Il n'existe pas de Promise<T, E> : une promesse peut rejeter avec n'importe quelle valeur.

then, catch et finally

Chaque then renvoie une nouvelle promesse typée d'après ce que renvoie son callback. Si le callback renvoie une promesse, TypeScript la déballe, donc vous n'obtenez jamais de 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"));

Le paramètre du callback de catch est typé any dans la bibliothèque standard, pas unknown. Rien ne vous empêche d'écrire e.message sur une valeur qui pourrait être une chaîne. Annotez-le en unknown, comme ci-dessus, et restreignez son type avant de l'utiliser. Un try/catch autour de await fait mieux : sous strict, sa variable de capture est déjà unknown (voir la gestion des erreurs).

Promise.all renvoie un tuple

Avec un littéral de tableau de promesses de types différents, Promise.all renvoie une promesse de tuple, où chaque position garde son propre type :

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

On peut y mêler des valeurs qui ne sont pas des promesses : elles passent telles quelles. Promise.all rejette dès qu'une entrée rejette, et les autres résultats sont perdus. Promise.race se résout ou rejette avec la première promesse terminée et a pour type l'union des entrées ; Promise.any se résout avec le premier succès et ne rejette avec une AggregateError que si toutes les entrées échouent.

Promise.allSettled et son type de résultat

Promise.allSettled attend chaque entrée et ne rejette jamais. Chaque résultat est un PromiseSettledResult<T>, une union que vous restreignez avec le champ 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 n'existe qu'après le test de status, car la variante rejetée n'a pas de value. reason est any, pour la même raison que dans catch. Le filter utilise un prédicat de type pour que le tableau filtré soit typé comme des résultats réussis.

Encapsuler une API à callbacks dans une promesse

Les API plus anciennes renvoient leurs résultats via un callback, souvent dans le style Node (err, result) => void. Encapsulez-les une fois dans une fonction qui renvoie une promesse typée, et le reste du code peut utiliser 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();

Dans Node, util.promisify fait cela pour les fonctions qui suivent la convention (err, result), et beaucoup de modules intégrés ont déjà une version à promesses (node:fs/promises, node:timers/promises).

Erreurs courantes

• Renvoyer T là où la signature annonce Promise<T>, ou l'inverse. Une fonction non async déclarée Promise<User> doit renvoyer une promesse ; une fonction async en renvoie une automatiquement.
• Oublier de gérer une promesse. Un appel comme save(user); sans await, then ni catch compile sans problème, et un rejet devient un rejet non géré (qui arrête un processus Node par défaut). La règle typescript-eslint no-floating-promises détecte ces cas.
• Faire confiance au type de .catch((e) => ...). Son e est any. Annotez-le en unknown.
• Entourer de new Promise quelque chose qui renvoie déjà une promesse. Renvoyez ou attendez simplement la promesse existante avec await.