Promise en TypeScript: Promise<T>, Promise.all y allSettled

En TypeScript una promesa tiene el tipo Promise<T>, donde T es el tipo del valor con el que se resuelve. Una función que devuelve una promesa lo declara en su tipo de retorno, y el valor que obtienes de then o de await tiene tipo 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
});

La mecánica de las promesas (estados, la cola de microtareas, el encadenamiento) es JavaScript normal, y se explica en promesas en JavaScript. Esta página trata de los tipos.

Tipar new Promise y resolve

Cuando new Promise es el valor de retorno de una función con un tipo de retorno declarado, T sale de ahí. Por sí solo, TypeScript no infiere T a partir de las llamadas a resolve, y obtienes Promise<unknown>. Pasa el argumento de tipo de forma explícita:

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

Dos detalles. resolve se tipa a partir de T, así que resolve("42") en una Promise<number> es un error de compilación. Y resolve() sin argumento solo se permite cuando T incluye void: en una Promise<number> es el error TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

El lado de reject no tiene tipo. No existe Promise<T, E>: una promesa puede rechazarse con cualquier valor.

then, catch y finally

Cada then devuelve una promesa nueva tipada según lo que devuelve su callback. Si el callback devuelve una promesa, TypeScript la desenvuelve, así que nunca obtienes 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"));

El parámetro del callback de catch tiene tipo any en la librería estándar, no unknown. Nada te impide escribir e.message sobre un valor que podría ser un string. Anótalo como unknown, como arriba, y estréchalo antes de usarlo. Un try/catch alrededor de await lo hace mejor: con strict, su variable de catch ya es unknown (consulta manejo de errores).

Promise.all devuelve una tupla

Dado un array literal de promesas de distintos tipos, Promise.all devuelve una promesa de una tupla, en la que cada posición conserva su propio tipo:

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

Se pueden mezclar valores que no son promesas, que pasan sin cambios. Promise.all se rechaza en cuanto se rechaza una entrada, y los demás resultados se pierden. Promise.race se resuelve o se rechaza con la primera que termine y su tipo es la unión de las entradas; Promise.any se resuelve con el primer éxito y se rechaza con un AggregateError solo si fallan todas las entradas.

Promise.allSettled y su tipo de resultado

Promise.allSettled espera a todas las entradas y nunca se rechaza. Cada resultado es un PromiseSettledResult<T>, una unión que estrechas con el campo status:

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 solo existe tras la comprobación de status, porque la variante rechazada no tiene value. reason es any, por la misma razón que en catch. El filter usa un predicado de tipo para que el array filtrado tenga el tipo de los resultados cumplidos.

Envolver una API de callbacks en una promesa

Las APIs antiguas informan de los resultados mediante un callback, a menudo al estilo de Node (err, result) => void. Envuélvelas una vez en una función que devuelva una promesa tipada, y el resto del código podrá usar await:

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

En Node, util.promisify hace esto con las funciones que siguen la convención (err, result), y muchos módulos integrados ya tienen versiones con promesas (node:fs/promises, node:timers/promises).

Errores habituales

• Devolver T donde la firma dice Promise<T>, o al revés. Una función no async declarada Promise<User> debe devolver una promesa; una función async la devuelve automáticamente.
• Olvidar manejar una promesa. Una llamada como save(user); sin await, then ni catch compila sin problema, y un rechazo se convierte en un rechazo no manejado (que por defecto termina un proceso de Node). La regla no-floating-promises de typescript-eslint los detecta.
• Fiarse del tipo de .catch((e) => ...). Su e es any. Anótalo como unknown.
• Usar new Promise alrededor de algo que ya devuelve una promesa. Basta con devolver la promesa existente o hacer await sobre ella.