combinator
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.race(iterable)Parameters
| Parameter | Purpose |
|---|---|
| iterable | Iterable of promises or values |
| first settlement wins | Adopts the state of whichever settles first — success OR failure |
| empty input | Returns a promise that stays pending forever |
Examples
const timeout = new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), 5000));
const data = await Promise.race([fetch('/slow'), timeout]);Classic timeout pattern — whichever finishes first wins.
const first = await Promise.race([
Promise.reject(new Error('early fail')),
Promise.resolve('too late')
]);
// throws 'early fail'A quick rejection wins the race just like a quick fulfillment.
const winner = await Promise.race([
fetchFromMirror('us'),
fetchFromMirror('eu'),
fetchFromMirror('ap')
]);Return the fastest mirror; slower ones still complete in background.
Gotcha
A single rejection wins the race — use Promise.any if you want the first success. Losers are not cancelled and can still trigger side effects.
Related
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.
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 }.
← All JS Promise reference · async/await vs promises vs callbacks