Async/await w TypeScript: typy, błędy i wywołania równoległe

Funkcja async w TypeScript zawsze zwraca obietnicę: jeśli jej ciało zwraca string, jej typ to Promise<string>. Wewnątrz niej await rozpakowuje Promise<T> do 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();

Zachowanie w czasie działania (co wstrzymuje await, pętla zdarzeń) należy do JavaScriptu i opisuje je strona async/await w JavaScript. Rola TypeScriptu to typy na wejściu i wyjściu.

Typy zwracane funkcji async

Zadeklarowany typ zwracany funkcji async musi być Promise<...>, choć ciało zwraca zwykłą wartość. Jeśli go pominiesz, TypeScript go wywnioskuje.

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

Zapis async function count(): number to błąd TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). Typ pomocniczy Awaited<T> daje typ po rozpakowaniu: Awaited<ReturnType<typeof count>> to number.

Zapomniane await

Brakujące await zostawia cię z Promise<T> zamiast T. TypeScript wyłapuje większość takich przypadków, bo typy przestają pasować:

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

Błąd z if (ok) jest prawdziwy: obiekt obietnicy zawsze jest prawdziwy logicznie, więc dostęp został przyznany. TypeScript zgłasza to jako TS2801. Przypisanie obietnicy do zmiennej boolean albo odczyt właściwości, której obietnica nie ma, też by się nie skompilowały. Wywołanie, którego wynik ignorujesz (save(user);), nie zostaje wyłapane; zajmuje się tym reguła no-floating-promises z typescript-eslint.

Obsługa błędów przez try/catch

Odrzucona obietnica sprawia, że await rzuca wyjątek, więc zwykłe try/catch działa. Przy strict zmienna w catch ma typ unknown i trzeba ją zawęzić, zanim odczytasz .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

throw wewnątrz funkcji async odrzuca jej obietnicę zamiast rzucać wyjątek w miejscu wywołania. Więcej wzorców, w tym własne klasy błędów i zwracanie wyników zamiast rzucania wyjątków, znajdziesz na stronie o obsłudze błędów.

await na najwyższym poziomie

await poza jakąkolwiek funkcją działa tylko w module ES. Plik kompilowany jako CommonJS (tak jest w tych przykładach i w projektach Node bez "type": "module") go odrzuca:

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

Opakuj kod w asynchroniczną funkcję main i wywołaj ją, tak jak robi każdy przykład na tej stronie. W projekcie z modułami ES ("type": "module" w package.json z module ustawionym na node16 albo nodenext, albo module: "esnext" dla bundlera) await na najwyższym poziomie jest dozwolone.

Po kolei a równolegle

Każde await czeka na swoją obietnicę, zanim zacznie się następna linia. Dla niezależnych wywołań najpierw uruchom je wszystkie, a potem poczekaj na nie razem przez 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();

W części sekwencyjnej b nie może skończyć się przed a, bo jeszcze się nie zaczęło. W części równoległej d kończy się pierwsze, a łączny czas to mniej więcej czas najdłuższego wywołania, a nie suma. Promise.all i tak zwraca wyniki w kolejności wejścia, otypowane jako krotka.

Pułapka z forEach

forEach ignoruje obietnicę zwracaną przez asynchroniczną funkcję zwrotną, więc nic nie czeka na zakończenie pracy:

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 z await przetwarza elementy pojedynczo; Promise.all z map uruchamia je równolegle i czeka na wszystkie. forEach nie robi żadnej z tych rzeczy, a TypeScript nie ostrzega, bo funkcja zwrotna otypowana jako zwracająca void akceptuje funkcję, która zwraca obietnicę.

Asynchroniczna iteracja z for await

for await...of przechodzi po asynchronicznym obiekcie iterowalnym, na przykład po asynchronicznym generatorze, czekając na każdą wartość:

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

Typ elementu pochodzi z adnotacji AsyncGenerator<T> generatora albo z wnioskowania, gdy ją pominiesz.