Promise

Promise<T> · async / await

The placeholder for a value that isn't ready yet. Promise<T> carries one future value of type T, settles exactly once, and composes with then — or, more often now, with await. Three instance methods below, one tag, and the static combinators that run promises together.

Usage

Await what you have, combine what runs together, build with new Promise only at the boundary with callback APIs.

const user = await fetchUser(id);       // await unwraps — prefer it over .then chains
const both = await Promise.all([        // run together, results in order
  fetchUser(id),
  fetchPosts(id),
]);
const guest = await fetchUser(id).catch(() => fallback);  // recover to a value
const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

How it works

A promise is an object in one of three states: pending, fulfilled, or rejected. The executor runs synchronously during construction; calling resolve delivers a value and reject delivers a reason, and the first call wins — later ones are ignored. Once settled, a promise never changes.

then, catch, and finally each return a new promise, so chains compose instead of nesting. await pauses the function until the promise settles, unwraps the value recursively (like Awaited<T>), and throws on rejection — which is why try/catch replaces .catch in modern code. Every async function returns a promise, even when you return a plain value.

Promise is generic over its fulfilled type, while rejections stay untyped (reason: any) — narrow them yourself. To run work together, all waits for everything in order, allSettled reports each outcome, any takes the first success, and race takes the first settlement of any kind. Promises never cancel: pair them with an AbortSignal when you need out.

Instance API

Everything on Promise.prototype, grouped by job. T is the fulfilled type.

4 methods

then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>: Attaches fulfillment and rejection handlers. Returns a new promise, so chains compose instead of nesting.
catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>: Handles rejection. Equivalent to then(undefined, onrejected); errors from earlier steps land here.
finally(onfinally?: (() => void) | undefined | null): Promise<T>: Runs cleanup regardless of outcome. Passes the original result through untouched.

[Symbol.toStringTag]: string: Property. Always "Promise" — what Object.prototype.toString reports.

Static API

Called on Promise itself. For building promises and running them together.

new <T>(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void): Promise<T>: Constructor. Runs the executor immediately; call resolve or reject to settle. The wrapper for callback APIs.
Promise.resolve<T>(value: T | PromiseLike<T>): Promise<Awaited<T>>: Wraps a value or thenable in a fulfilled promise. The await-free way to lift a value.
Promise.reject<T = never>(reason?: any): Promise<T>: Builds an already-rejected promise. Useful for tests and as a failing default.
Promise.withResolvers<T>(): PromiseWithResolvers<T>: ES2024. Returns { promise, resolve, reject } without an executor closure. Settle from the outside.
Promise.try<T, U extends unknown[]>(callbackfn: (...args: U) => T | PromiseLike<T>, ...args: U): Promise<Awaited<T>>: ES2025. Runs the callback now; sync throws become rejections. Start any chain here.
Promise.all<T extends readonly unknown[] | []>(values: T): Promise<{ -readonly [P in keyof T]: Awaited<T[P]> }>: Waits for every input, results in order. Rejects on the first failure.
Promise.allSettled<T extends readonly unknown[] | []>(values: T): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>: Waits for all, never rejects. Each entry is { status: "fulfilled", value } or { status: "rejected", reason }.
Promise.any<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>: First fulfillment wins. Rejects with an AggregateError only if everything fails.
Promise.race<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>: First settlement wins, fulfillment or rejection. For cancellation, reach for AbortSignal instead.