Promise API Reference
JavaScript Promise methods for asynchronous programming — combining, racing, resolving, and handling async values.
Promise
Represents the eventual result of an asynchronous operation. Core async primitive in JavaScript (ES6+).
Promise.all(iterable)Wait for all promises to fulfill. Rejects immediately if any promise rejects (fast-fail). Returns an array of results in input order.
Returns: Promise<Array>
Promise.allSettled(iterable)Wait for all promises to settle (fulfill or reject). Never rejects — returns an array of { status, value } or { status, reason } objects. Useful when you want all results regardless of failures.
Returns: Promise<Array<{ status: 'fulfilled', value } | { status: 'rejected', reason }>>
Promise.any(iterable)Resolve with the first fulfilled promise. Rejects only if ALL promises reject (AggregateError). Useful for 'first successful response' patterns (e.g., racing CDNs).
Returns: Promise<value>
Promise.race(iterable)Resolve or reject with the first promise to settle (fulfill OR reject). Useful for implementing timeouts. Unlike any(), a rejection also wins the race.
Returns: Promise<value>
Promise.resolve(value)Create a promise that resolves immediately with the given value. If value is already a promise, it is returned as-is. Useful for converting non-promise values to promises or ensuring consistent async return types.
Returns: Promise<value>
Promise.reject(reason)Create a promise that rejects immediately with the given reason. Mostly used for testing or for explicit error signaling in promise chains.
Returns: Promise<never>
Promise.try(executor)ES2025. Wrap a synchronous or asynchronous function call as a promise. Combines try/catch semantics with promise chaining — eliminates the dual try/catch + .catch() pattern. Falls back gracefully if not available.
Returns: Promise<value>
promise.then(onFulfilled, onRejected?)Register fulfillment and (optionally) rejection handlers. Returns a new promise, enabling chaining. If a handler returns a value, the new promise resolves with it; if it returns a promise, the new promise adopts its state.
Returns: Promise<result>
promise.catch(onRejected)Register a rejection handler. Returns a new promise. If onRejected returns a value (or doesn't throw), the new promise RESOLVES (recovery), so catch can be used to recover from errors mid-chain.
Returns: Promise<result>
promise.finally(onFinally)Register a handler that runs regardless of fulfillment or rejection. The returned promise mirrors the original's state. onFinally cannot inspect the value or reason, and any value it returns is ignored. Useful for cleanup.
Returns: Promise<value>