Promise in TypeScript: Promise<T>, Promise.all e allSettled

In TypeScript una promise ha il tipo Promise<T>, dove T è il tipo del valore con cui si risolve. Una funzione che restituisce una promise lo dichiara nel suo tipo di ritorno, e il valore che ottieni da then o await ha tipo 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
});

I meccanismi delle promise (stati, coda dei microtask, concatenazione) sono JavaScript puro, trattati in Promise in JavaScript. Questa pagina riguarda i tipi.

Tipizzare new Promise e resolve

Quando new Promise è il valore di ritorno di una funzione con un tipo di ritorno dichiarato, T viene da lì. Da solo, TypeScript non inferisce T dalle chiamate a resolve, e ottieni Promise<unknown>. Passa l'argomento di tipo in modo esplicito:

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

Due dettagli. resolve è tipizzato a partire da T, quindi resolve("42") in una Promise<number> è un errore di compilazione. E resolve() senza argomenti è permesso solo quando T include void: in una Promise<number> è l'errore TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

Il lato reject non è tipizzato. Non esiste Promise<T, E>: una promise può essere rifiutata con qualsiasi valore.

then, catch e finally

Ogni then restituisce una nuova promise tipizzata in base a ciò che restituisce la sua callback. Se la callback restituisce una promise, TypeScript la scarta, quindi non ottieni mai 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"));

Il parametro della callback di catch ha tipo any nella libreria standard, non unknown. Niente ti impedisce di scrivere e.message su un valore che potrebbe essere una stringa. Annotalo come unknown, come sopra, e restringilo prima di usarlo. Un try/catch attorno ad await fa di meglio: con strict, la sua variabile catch è già unknown (vedi gestione degli errori).

Promise.all restituisce una tupla

Dato un array letterale di promise di tipi diversi, Promise.all restituisce una promise di una tupla, in cui ogni posizione mantiene il proprio tipo:

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

Si possono mescolare anche valori che non sono promise, e passano invariati. Promise.all viene rifiutata appena un input viene rifiutato, e gli altri risultati vanno persi. Promise.race si risolve o viene rifiutata con il primo che si conclude ed è tipizzata come l'unione degli input; Promise.any si risolve con il primo successo e viene rifiutata con un AggregateError solo se tutti gli input falliscono.

Promise.allSettled e il suo tipo di risultato

Promise.allSettled aspetta ogni input e non viene mai rifiutata. Ogni risultato è un PromiseSettledResult<T>, un'unione che restringi con il campo 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 esiste solo dopo il controllo su status, perché la variante rifiutata non ha value. reason è any, per lo stesso motivo di catch. Il filter usa un type predicate così che l'array filtrato sia tipizzato come risultati riusciti.

Avvolgere un'API a callback in una promise

Le API più vecchie comunicano i risultati tramite una callback, spesso nello stile di Node (err, result) => void. Avvolgile una volta in una funzione che restituisce una promise tipizzata, e il resto del codice può usare 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();

In Node, util.promisify lo fa per le funzioni che seguono la convenzione (err, result), e molti moduli integrati hanno già versioni con promise (node:fs/promises, node:timers/promises).

Errori comuni

• Restituire T dove la firma dice Promise<T>, o il contrario. Una funzione non async dichiarata Promise<User> deve restituire una promise; una funzione async ne restituisce una automaticamente.
• Dimenticare di gestire una promise. Una chiamata come save(user); senza await, then o catch compila senza problemi, e un rifiuto diventa un rifiuto non gestito (che per impostazione predefinita termina un processo Node). La regola di typescript-eslint no-floating-promises intercetta questi casi.
• Fidarsi del tipo di .catch((e) => ...). Il suo e è any. Annotalo come unknown.
• Usare new Promise attorno a qualcosa che restituisce già una promise. Restituisci o fai await della promise esistente.