JavaScript Promises & async/await
Every combinator (Promise.all, allSettled, race,
any), instance methods, and the async/await sugar on top — with the fail-fast
gotcha, unhandled rejection handling, and Promise.withResolvers (ES2024).
Combinators (all / race / any)
Promise.all
Waits for all promises in an iterable to fulfill and resolves with an array of their values in original order. Rejects immediately with the reason of the first promise that rejects (fail-fast).
Promise.allSettled
Waits for every promise to settle (fulfill or reject) and always resolves with an array of result descriptors. Each entry is either { status: 'fulfilled', value } or { status: 'rejected', reason }.
Promise.race
Settles as soon as the first promise in the iterable settles, adopting its state (fulfilled or rejected). The remaining promises keep running but their outcomes are ignored.
Promise.any
Resolves with the value of the first promise to fulfill, ignoring any rejections until a success occurs. If every promise rejects, it rejects with an AggregateError whose .errors array contains each reason.
Instance Methods (.then / .catch)
.then()
Registers callbacks for the fulfillment (and optionally rejection) of a promise and returns a new promise chained to the callback's return value. Returning a value fulfills the next promise; throwing or returning a rejected promise rejects it.
.catch()
Attaches a rejection handler to a promise chain, equivalent to .then(undefined, onRejected). Returns a new promise that fulfills with the handler's return value, letting you recover from errors.
.finally()
Runs a callback after the promise settles regardless of outcome, without changing the resolved value or rejection reason. Ideal for cleanup like hiding spinners or closing connections.
async / await
async function
Declares a function that always returns a promise, letting you use await inside it to pause on other promises. A returned value fulfills the promise; a thrown error rejects it.
await
Pauses execution of the surrounding async function until the awaited promise settles, then resumes with its resolved value. If the promise rejects, await throws the reason, letting you use try/catch.
Top-level await
Allows using await outside of any async function at the top level of an ECMAScript module. The module's evaluation waits for the awaited promise, blocking importers until it settles.
Error Handling
try / catch with await
Since await throws when the awaited promise rejects, standard try/catch is the idiomatic way to handle async errors inside an async function. A finally block runs on both success and failure paths.
unhandledrejection event
Fires when a promise rejects and has no rejection handler attached by the end of the current microtask cycle. Provides a last-chance hook to log or report the error before the runtime warns or exits.
Creation
new Promise
Constructs a promise from an executor function that receives resolve and reject callbacks. Use it to adapt callback-based or event-based APIs into promises.
Promise.resolve
Returns a promise fulfilled with the given value, or — if the value is already a promise or thenable — the same/adopted promise. Handy for normalizing 'might be a promise' inputs.
Promise.reject
Returns a promise that is already rejected with the given reason. Useful for early-exit paths in functions that must always return a promise.
Promise.withResolvers
Creates a promise and exposes its resolve and reject callbacks alongside it, avoiding the need to capture them from a new Promise executor. Added in ES2024 for the 'deferred' pattern.