Async await en TypeScript: tipos, errores y llamadas en paralelo

Una función async en TypeScript siempre devuelve una promesa: si su cuerpo devuelve un string, su tipo es Promise<string>. Dentro de ella, await desenvuelve una Promise<T> en un 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();

El comportamiento en tiempo de ejecución (qué pausa await, el event loop) es JavaScript, y se explica en async/await en JavaScript. Lo que aporta TypeScript son los tipos de entrada y de salida.

Tipos de retorno de las funciones async

El tipo de retorno declarado de una función async debe ser Promise<...>, aunque el cuerpo devuelva el valor directamente. TypeScript lo infiere si lo omites.

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

Escribir async function count(): number es el 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>'?). El utility type Awaited<T> da el tipo desenvuelto: Awaited<ReturnType<typeof count>> es number.

Olvidar el await

Un await que falta te deja con una Promise<T> en lugar de un T. TypeScript detecta la mayoría de estos casos porque los tipos dejan de encajar:

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

El bug del if (ok) es real: un objeto promesa siempre es truthy, así que concedió el acceso. TypeScript lo informa como TS2801. Asignar la promesa a una variable boolean, o leer una propiedad que la promesa no tiene, tampoco compilaría. Una llamada cuyo resultado ignoras (save(user);) no se detecta; de eso se encarga la regla no-floating-promises de typescript-eslint.

Manejo de errores con try/catch

Una promesa rechazada hace que await lance un error, así que el try/catch normal funciona. Con strict, la variable de catch es unknown, y la estrechas antes de leer .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

Un throw dentro de una función async rechaza su promesa en lugar de lanzar el error en el sitio de la llamada. Hay más patrones, incluidas las clases de error propias y devolver resultados en lugar de lanzar errores, en la página de manejo de errores.

await de nivel superior

await fuera de cualquier función solo funciona en un ES module. Un archivo compilado como CommonJS (el caso de estos ejemplos, y el de los proyectos Node sin "type": "module") lo rechaza:

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

Envuelve el código en una función main async y llámala, como hacen todos los ejemplos de esta página. En un proyecto ES module ("type": "module" en package.json con module en node16 o nodenext, o module: "esnext" para un bundler), el await de nivel superior está permitido.

Secuencial frente a paralelo

Cada await espera a su promesa antes de que empiece la línea siguiente. Para llamadas independientes, inícialas todas primero y espéralas juntas con 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();

En la mitad secuencial, b no puede terminar antes que a porque todavía no ha empezado. En la mitad paralela, d termina primero, y el tiempo total es aproximadamente el de la llamada más larga, no la suma. Promise.all sigue devolviendo los resultados en el orden de entrada, tipados como una tupla.

La trampa de forEach

forEach ignora la promesa que devuelve un callback async, así que nada espera a que termine el trabajo:

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 con await procesa los elementos de uno en uno; Promise.all con map los ejecuta en paralelo y espera a todos. forEach no hace ninguna de las dos cosas, y TypeScript no avisa, porque un callback tipado para devolver void acepta uno que devuelve una promesa.

Iteración asíncrona con for await

for await...of recorre un iterable asíncrono, como un generador async, esperando cada valor:

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

El tipo de los elementos sale de la anotación AsyncGenerator<T> del generador, o de la inferencia si la omites.