Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Promise.race — first settlement

Promise.race(iterable) returns a promise that adopts the fulfillment value or rejection reason from the first settlement processed. It does not wait for the first success and does not cancel the remaining operations.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

Promise.race(iterable)

Promise.race(iterable) is a static method accepting a synchronous iterable, such as an array. Each element is processed through Promise.resolve: it may be a promise, an object with a then method, or an ordinary value.

The result adopts the first fulfillment or rejection processed. A rejection can therefore beat a success. If the inputs are all ordinary non-thenable values or already-settled native promises that Promise.resolve returns unchanged, iteration order decides the winner. But Promise.resolve can wrap an already-settled native promise from another ECMAScript realm in a new promise, adding asynchronous steps to adopt its state. An ordinary value or an already-settled promise from the same realm can then win even if it appears later in the iteration. Result handlers still run asynchronously.

Promise.race([]) remains pending forever. An error while obtaining the iterator or iterating rejects the result. The method does not cancel losing operations: stopping them requires a separate mechanism.

In the example, pending never settles. The other two promises are returned unchanged by Promise.resolve, and the rejected one precedes the fulfilled one, so the result is rejected: failed. The sync line appears earlier because the handler passed to then does not run on the current call stack.

Examples

const pending = new Promise(() => {});
const result = Promise.race([
  pending,
  Promise.reject("failed"),
  Promise.resolve("ready")
]);

result.then(
  value => console.log("fulfilled: " + value),
  reason => console.log("rejected: " + reason)
);
console.log("sync");

Result

sync
rejected: failed

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources