TypeScript Async Await: Types, Errors and Parallel Calls

An async function in TypeScript always returns a promise: if its body returns a string, its type is Promise<string>. Inside it, await unwraps a Promise<T> into a 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();

The runtime behavior (what await pauses, the event loop) is JavaScript, covered in JavaScript async/await. TypeScript's part is the types in and out.

Return Types of Async Functions

The declared return type of an async function must be Promise<...>, even though the body returns the plain value. TypeScript infers it if you leave it off.

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

Writing async function count(): number is error TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). The utility type Awaited<T> gives the unwrapped type: Awaited<ReturnType<typeof count>> is number.

Forgetting await

A missing await leaves you holding a Promise<T> instead of a T. TypeScript catches most of these because the types no longer fit:

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

The if (ok) bug is real: a promise object is always truthy, so it granted access. TypeScript reports it as TS2801. Assigning the promise to a boolean variable, or reading a property the promise does not have, would also fail to compile. A call whose result you ignore (save(user);) is not caught; the typescript-eslint rule no-floating-promises covers that.

Error Handling with try/catch

A rejected promise makes await throw, so ordinary try/catch works. Under strict, the variable in catch is unknown, and you narrow it before reading .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 inside an async function rejects its promise rather than throwing at the call site. More patterns, including custom error classes and returning results instead of throwing, are on the error handling page.

Top-Level await

await outside any function only works in an ES module. A file compiled as CommonJS (the case for these examples, and for Node projects without "type": "module") rejects it:

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

Wrap the code in an async main function and call it, as every example on this page does. In an ES module project ("type": "module" in package.json with module set to node16 or nodenext, or module: "esnext" for a bundler), top-level await is allowed.

Sequential vs Parallel

Each await waits for its promise before the next line starts. For independent calls, start them all first and await them together with 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 the sequential half, b cannot finish before a because it has not started. In the parallel half, d finishes first, and the total time is about the longest call rather than the sum. Promise.all still returns results in input order, typed as a tuple.

The forEach Pitfall

forEach ignores the promise an async callback returns, so nothing waits for the work:

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 with await processes items one at a time; Promise.all with map runs them in parallel and waits for all. forEach does neither, and TypeScript does not warn, because a callback typed to return void accepts one that returns a promise.

Async Iteration with for await

for await...of loops over an async iterable, such as an async generator, awaiting each value:

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

The element type comes from the generator's AsyncGenerator<T> annotation, or from inference when you leave it off.