TypeScript async await: Typen, Fehler und parallele Aufrufe

Eine async-Funktion in TypeScript gibt immer ein Promise zurück: Gibt ihr Rumpf einen string zurück, ist ihr Typ Promise<string>. Darin packt await ein Promise<T> zu einem T aus.

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

Das Laufzeitverhalten (was await pausiert, die Event Loop) ist JavaScript und wird unter async/await in JavaScript behandelt. Der Teil von TypeScript sind die Typen, die hinein und herausgehen.

Rückgabetypen von async-Funktionen

Der deklarierte Rückgabetyp einer async-Funktion muss Promise<...> sein, auch wenn der Rumpf den einfachen Wert zurückgibt. Lässt du ihn weg, leitet TypeScript ihn ab.

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

async function count(): number zu schreiben ist der Fehler TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). Der Utility Type Awaited<T> liefert den ausgepackten Typ: Awaited<ReturnType<typeof count>> ist number.

await vergessen

Ein fehlendes await lässt dich mit einem Promise<T> statt einem T zurück. TypeScript findet die meisten dieser Fälle, weil die Typen nicht mehr passen:

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

Der Bug mit if (ok) ist echt: Ein Promise-Objekt ist immer truthy, also wurde der Zugriff gewährt. TypeScript meldet ihn als TS2801. Das Promise einer boolean-Variablen zuzuweisen oder eine Eigenschaft zu lesen, die das Promise nicht hat, würde ebenfalls nicht kompilieren. Ein Aufruf, dessen Ergebnis du ignorierst (save(user);), wird nicht gefunden; das deckt die Regel no-floating-promises von typescript-eslint ab.

Fehlerbehandlung mit try/catch

Ein abgelehntes Promise lässt await werfen, also funktioniert ein gewöhnliches try/catch. Unter strict ist die Variable in catch unknown, und du engst sie ein, bevor du .message liest:

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

throw in einer async-Funktion lehnt ihr Promise ab, statt an der Aufrufstelle zu werfen. Weitere Muster, darunter eigene Fehlerklassen und Ergebnisse zurückgeben statt zu werfen, stehen auf der Seite zur Fehlerbehandlung.

Top-Level await

await außerhalb jeder Funktion funktioniert nur in einem ES-Modul. Eine als CommonJS kompilierte Datei (der Fall bei diesen Beispielen und bei Node-Projekten ohne "type": "module") lehnt es ab:

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

Packe den Code in eine async-Funktion main und rufe sie auf, wie es jedes Beispiel auf dieser Seite tut. In einem Projekt mit ES-Modulen ("type": "module" in package.json mit module auf node16 oder nodenext, oder module: "esnext" für einen Bundler) ist Top-Level await erlaubt.

Sequenziell vs parallel

Jedes await wartet auf sein Promise, bevor die nächste Zeile beginnt. Bei unabhängigen Aufrufen startest du sie zuerst alle und wartest dann gemeinsam mit 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();

In der sequenziellen Hälfte kann b nicht vor a fertig werden, weil es noch nicht gestartet ist. In der parallelen Hälfte wird d zuerst fertig, und die Gesamtzeit entspricht ungefähr dem längsten Aufruf statt der Summe. Promise.all liefert die Ergebnisse trotzdem in der Reihenfolge der Eingaben, als Tupel typisiert.

Die forEach-Falle

forEach ignoriert das Promise, das ein async-Callback zurückgibt, also wartet nichts auf die Arbeit:

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 mit await verarbeitet die Elemente einzeln nacheinander; Promise.all mit map führt sie parallel aus und wartet auf alle. forEach tut keins von beiden, und TypeScript warnt nicht, weil ein Callback, der als Rückgabe void typisiert ist, einen akzeptiert, der ein Promise zurückgibt.

Asynchrone Iteration mit for await

for await...of durchläuft ein asynchrones Iterable, etwa einen async Generator, und wartet auf jeden Wert:

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

Der Elementtyp kommt aus der Annotation AsyncGenerator<T> des Generators oder aus der Inferenz, wenn du sie weglässt.