TypeScript Promise: Promise<T>, Promise.all und allSettled

In TypeScript hat ein Promise den Typ Promise<T>, wobei T der Typ des Werts ist, mit dem es aufgelöst wird. Eine Funktion, die ein Promise zurückgibt, deklariert das in ihrem Rückgabetyp, und der Wert aus then oder await hat den Typ 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
});

Die Mechanik von Promises (Zustände, die Microtask-Queue, Verkettung) ist reines JavaScript und wird unter Promises in JavaScript behandelt. Auf dieser Seite geht es um die Typen.

new Promise und resolve typisieren

Ist new Promise der Rückgabewert einer Funktion mit deklariertem Rückgabetyp, kommt T von dort. Für sich allein leitet TypeScript T nicht aus den Aufrufen von resolve ab, und du bekommst Promise<unknown>. Übergib das Typargument ausdrücklich:

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

Zwei Details. resolve wird aus T typisiert, also ist resolve("42") in einem Promise<number> ein Compilerfehler. Und resolve() ohne Argument ist nur erlaubt, wenn T void enthält: In einem Promise<number> ist es der Fehler TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

Die Seite von reject ist nicht typisiert. Es gibt kein Promise<T, E>: Ein Promise kann mit jedem Wert abgelehnt werden.

then, catch und finally

Jedes then gibt ein neues Promise zurück, das nach dem Rückgabewert seines Callbacks typisiert ist. Gibt der Callback ein Promise zurück, packt TypeScript es aus, du bekommst also nie 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"));

Der Parameter des catch-Callbacks ist in der Standardbibliothek als any typisiert, nicht als unknown. Nichts hält dich davon ab, e.message auf einen Wert zu schreiben, der ein String sein könnte. Annotiere ihn als unknown, wie oben, und enge ihn vor der Verwendung ein. try/catch um await ist besser: Unter strict ist seine catch-Variable bereits unknown (siehe Fehlerbehandlung).

Promise.all gibt ein Tupel zurück

Bei einem Array-Literal aus Promises unterschiedlichen Typs gibt Promise.all ein Promise eines Tupels zurück, in dem jede Position ihren eigenen Typ behält:

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

Werte, die keine Promises sind, lassen sich untermischen und gehen unverändert durch. Promise.all wird abgelehnt, sobald eine Eingabe abgelehnt wird, und die übrigen Ergebnisse gehen verloren. Promise.race wird mit der ersten abgeschlossenen Eingabe aufgelöst oder abgelehnt und ist als Union der Eingaben typisiert; Promise.any wird mit dem ersten Erfolg aufgelöst und nur dann mit einem AggregateError abgelehnt, wenn jede Eingabe scheitert.

Promise.allSettled und sein Ergebnistyp

Promise.allSettled wartet auf jede Eingabe und wird nie abgelehnt. Jedes Ergebnis ist ein PromiseSettledResult<T>, eine Union, die du über das Feld status einengst:

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 existiert erst nach der Prüfung von status, weil die abgelehnte Variante kein value hat. reason ist any, aus demselben Grund wie bei catch. Das filter verwendet ein Type Predicate, damit das gefilterte Array als Liste erfüllter Ergebnisse typisiert ist.

Eine Callback-API in ein Promise verpacken

Ältere APIs melden Ergebnisse über einen Callback, oft im Node-Stil (err, result) => void. Verpacke sie einmal in eine Funktion, die ein typisiertes Promise zurückgibt, dann kann der restliche Code await verwenden:

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 erledigt util.promisify das für Funktionen, die der Konvention (err, result) folgen, und viele eingebaute Module haben bereits Promise-Versionen (node:fs/promises, node:timers/promises).

Häufige Fehler

• T zurückgeben, wo die Signatur Promise<T> sagt, oder umgekehrt. Eine nicht asynchrone Funktion, die als Promise<User> deklariert ist, muss ein Promise zurückgeben; eine async-Funktion gibt automatisch eines zurück.
• Ein Promise nicht behandeln. Ein Aufruf wie save(user); ohne await, then oder catch kompiliert problemlos, und eine Ablehnung wird zu einer Unhandled Rejection (die einen Node-Prozess standardmäßig beendet). Die Regel no-floating-promises von typescript-eslint findet so etwas.
• Dem Typ von .catch((e) => ...) vertrauen. Sein e ist any. Annotiere es als unknown.
• new Promise um etwas legen, das bereits ein Promise zurückgibt. Gib das vorhandene Promise einfach zurück oder nutze await.