Promise em TypeScript: Promise<T>, Promise.all e allSettled

No TypeScript, uma promise tem o tipo Promise<T>, em que T é o tipo do valor com que ela resolve. Uma função que retorna uma promise declara isso no tipo de retorno, e o valor que você recebe de then ou de await tem o 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
});

A mecânica das promises (estados, a fila de microtasks, o encadeamento) é JavaScript puro, coberta em promises em JavaScript. Esta página trata dos tipos.

Tipando new Promise e resolve

Quando new Promise é o valor de retorno de uma função com tipo de retorno declarado, o T vem dali. Sozinho, o TypeScript não infere T a partir das chamadas de resolve, e você recebe Promise<unknown>. Passe o argumento de tipo explicitamente:

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

Dois detalhes. resolve é tipado a partir de T, então resolve("42") em uma Promise<number> é erro de compilação. E resolve() sem argumento só é permitido quando T inclui void: em uma Promise<number> ele dá o erro TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

O lado do reject não é tipado. Não existe Promise<T, E>: uma promise pode rejeitar com qualquer valor.

then, catch e finally

Cada then retorna uma nova promise tipada pelo que o seu callback retorna. Se o callback retornar uma promise, o TypeScript a desembrulha, então você nunca recebe 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"));

O parâmetro do callback de catch é tipado como any na biblioteca padrão, não como unknown. Nada impede você de escrever e.message em um valor que pode ser uma string. Anote-o como unknown, como acima, e estreite antes de usar. try/catch em volta de await se sai melhor: com strict, a variável do catch já é unknown (veja tratamento de erros).

Promise.all retorna uma tupla

Dado um array literal de promises de tipos diferentes, Promise.all retorna uma promise de uma tupla, com cada posição mantendo o seu próprio 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();

Valores que não são promises podem ser misturados e passam sem mudança. Promise.all rejeita assim que uma entrada rejeita, e os outros resultados se perdem. Promise.race resolve ou rejeita com a primeira a terminar e é tipada como a union das entradas; Promise.any resolve com o primeiro sucesso e rejeita com um AggregateError só se todas as entradas falharem.

Promise.allSettled e o tipo do resultado

Promise.allSettled espera todas as entradas e nunca rejeita. Cada resultado é um PromiseSettledResult<T>, uma union que você estreita com o 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 só existe depois da verificação de status, porque a variante rejeitada não tem value. reason é any, pelo mesmo motivo que no catch. O filter usa um type predicate para que o array filtrado seja tipado como resultados cumpridos.

Envolvendo uma API de callback em uma promise

APIs mais antigas informam resultados por meio de um callback, muitas vezes no estilo do Node, (err, result) => void. Envolva-as uma vez em uma função que retorna uma promise tipada, e o resto do código pode 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();

No Node, util.promisify faz isso para funções que seguem a convenção (err, result), e muitos módulos embutidos já têm versões com promises (node:fs/promises, node:timers/promises).

Erros comuns

• Retornar T onde a assinatura diz Promise<T>, ou o contrário. Uma função que não é async declarada como Promise<User> precisa retornar uma promise; uma função async retorna uma automaticamente.
• Esquecer de tratar uma promise. Uma chamada como save(user); sem await, then ou catch compila sem problemas, e uma rejeição vira uma unhandled rejection (que, por padrão, encerra um processo Node). A regra no-floating-promises do typescript-eslint pega esses casos.
• Confiar no tipo de .catch((e) => ...). O e dele é any. Anote-o como unknown.
• Usar new Promise em volta de algo que já retorna uma promise. Basta retornar a promise existente ou fazer await nela.