What does Promise.race() do?

JavaScriptJunior~2 min read

What `Promise.race()` does

Promise.race(iterable) takes an array (or any iterable) of promises and returns a new promise that:

is fulfilled or is rejected, as soon as the first of the passed promises settles, regardless of whether it succeeded or failed.

In other words, it's a "race" of promises: whichever finishes first determines the result.

Syntax

javascript

Promise.race(iterable)

Returns:

a new Promise that:

settles with the value of the first promise that resolved (resolve),
or fails with an error, if the first one to settle was a reject.

Example 1 - whoever is faster wins

javascript

const fast = new Promise(resolve => setTimeout(() => resolve('Fast'), 1000));
const slow = new Promise(resolve => setTimeout(() => resolve('Slow'), 3000));

Promise.race([fast, slow]).then(console.log);

Result after 1 second:

javascript

Fast

The second promise (slow) keeps running in the background, but the result is already decided - fast won the "race".

Example 2 - if the first promise fails

javascript

const ok = new Promise(resolve => setTimeout(() => resolve('All good'), 2000));
const fail = new Promise((_, reject) => setTimeout(() => reject('Error!'), 1000));

Promise.race([ok, fail])
  .then(console.log)
  .catch(console.error);

Result after 1 second:

javascript

Error!

Even though ok will later resolve successfully, the outcome of the whole race is already decided by the error.

How this works under the hood

All promises start running practically at the same time.
As soon as one of them settles (resolve or reject):

that promise's result becomes the result of the whole race;
Promise.race() moves to the fulfilled or rejected state;
the remaining promises are ignored (but not canceled).

The rest keep running in the background, but their result doesn't affect anything.

Example 3 - with a "timeout"

A common practice: using Promise.race() to set a time limit

javascript

function timeout(ms) {
  return new Promise((_, reject) =>
    setTimeout(() => reject(`Timed out (${ms}ms)`), ms)
  );
}

const fetchData = new Promise(resolve =>
  setTimeout(() => resolve('Response received'), 3000)
);

Promise.race([fetchData, timeout(2000)])
  .then(console.log)
  .catch(console.error);

Output after 2 seconds:

javascript

Timed out (2000ms)

This is one of the most common scenarios for Promise.race(), limiting "hanging" operations (for example, requests).

Example 4 - all promises are instant

javascript

Promise.race([
  Promise.resolve('First'),
  Promise.resolve('Second'),
  Promise.resolve('Third')
]).then(console.log);

Output:

javascript

First

Even if all of them resolve instantly, the first in iteration order wins.

If you pass non-promises

Promise.race() automatically "wraps" plain values in Promise.resolve():

javascript

Promise.race([42, Promise.resolve('OK')]).then(console.log); // 42

Difference from other methods

Method	What it does	Settles when	On error
`Promise.all()`	Waits for all promises	All settle successfully	Fails on the first `reject`
`Promise.allSettled()`	Waits for all, regardless of outcome	All settle	Never fails
`Promise.race()`	Takes the first to settle	The first `resolve` or `reject`	Depends on the first promise
`Promise.any()`	Takes the first success (`resolve`)	The first `fulfilled`	Fails if all are `rejected`

A simple analogy

Imagine a race.

You have several couriers - whoever delivers the package first, that's the result you accept. The rest are still on the way, but you no longer care, you already got what you needed.

SUMMARY

Feature	`Promise.race()`
Accepts	An array (or other iterable) of promises
Settles when	The first promise resolves or rejects
Returns	The result (or error) of the first promise to settle
The remaining promises	Are ignored (but not canceled)
Common use	Time limits (`timeout`), competing requests

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.