TypeScript Promise: Promise<T>, Promise.all and allSettled

In TypeScript a promise has the type Promise<T>, where T is the type of the value it resolves with. A function that returns a promise declares it in its return type, and the value you get from then or await has type 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
});

The promise mechanics (states, the microtask queue, chaining) are plain JavaScript, covered in JavaScript promises. This page is about the types.

Typing new Promise and resolve

When new Promise is the return value of a function with a declared return type, T comes from that. On its own, TypeScript does not infer T from the resolve calls, and you get Promise<unknown>. Pass the type argument explicitly:

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

Two details. resolve is typed from T, so resolve("42") in a Promise<number> is a compile error. And resolve() with no argument is only allowed when T includes void: in a Promise<number> it is error TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

The reject side is not typed. There is no Promise<T, E>: a promise can reject with any value.

then, catch and finally

Each then returns a new promise typed by what its callback returns. If the callback returns a promise, TypeScript unwraps it, so you never get 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"));

The catch callback's parameter is typed any in the standard library, not unknown. Nothing stops you from writing e.message on a value that might be a string. Annotate it as unknown, as above, and narrow before use. try/catch around await does better: under strict, its catch variable is already unknown (see error handling).

Promise.all Returns a Tuple

Given an array literal of different promise types, Promise.all returns a promise of a tuple, with each position keeping its own type:

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

Non-promise values can be mixed in and pass through unchanged. Promise.all rejects as soon as one input rejects, and the other results are lost. Promise.race resolves or rejects with the first to settle and is typed as the union of the inputs; Promise.any resolves with the first success and rejects with an AggregateError only if every input fails.

Promise.allSettled and Its Result Type

Promise.allSettled waits for every input and never rejects. Each result is a PromiseSettledResult<T>, a union you narrow with the status field:

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 only exists after the status check, because the rejected variant has no value. reason is any, for the same reason as in catch. The filter uses a type predicate so that the filtered array is typed as fulfilled results.

Wrapping a Callback API in a Promise

Older APIs report results through a callback, often in the Node style (err, result) => void. Wrap them once in a function that returns a typed promise, and the rest of the code can use 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();

In Node, util.promisify does this for functions that follow the (err, result) convention, and many built-in modules already have promise versions (node:fs/promises, node:timers/promises).

Common Mistakes

• Returning T where the signature says Promise<T>, or the reverse. A non-async function declared Promise<User> must return a promise; an async function returns one automatically.
• Forgetting to handle a promise. A call like save(user); without await, then or catch compiles fine, and a rejection becomes an unhandled rejection (which ends a Node process by default). The typescript-eslint rule no-floating-promises catches these.
• Trusting the type of .catch((e) => ...). Its e is any. Annotate it as unknown.
• Using new Promise around something that already returns a promise. Just return or await the existing promise.