JavaScriptAsyncIntermediate

Promise.race()

Resolves/rejects as soon as the first promise settles.

Review the syntaxStudy the examplesOpen the coding app
Promise.race([promise1, promise2, ...])
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Resolves/rejects as soon as the first promise settles.

Promise.race() accepts an iterable of promise objects and returns a single Promise. This returned promise settles (either fulfilling or rejecting) as soon as any of the promises in the iterable settles, with the value or reason from that promise. It is an ES6 feature, so IE is not supported. A significant performance consideration is that while Promise.race() settles as soon as the first promise finishes, it does not cancel the remaining 'losing' promises; those operations continue to execute in the background until they complete. An important edge case occurs when passing an empty iterable: the returned promise will remain pending forever because there is no settle event to trigger it. Additionally, if the iterable contains non-promise values or already settled promises, the first one encountered will typically win the race immediately.

Quick reference

Syntax

Promise.race([promise1, promise2, ...])

Inputs

Parameters

iterableIterable<Promise> · Promises (or values) to race.

See it in practice

Examples

1

Basic Race Between Timers

var promise1 = new Promise(function(resolve) {
  setTimeout(resolve, 500, 'slow');
});
var promise2 = new Promise(function(resolve) {
  setTimeout(resolve, 100, 'fast');
});

Promise.race([promise1, promise2]).then(function(value) {
  console.log(value);
});
Output:
"fast"

Since promise2 resolves after 100ms and promise1 after 500ms, promise2 wins the race.

2

Implementing a Network Timeout

var request = new Promise(function(resolve) {
  setTimeout(resolve, 5000, 'Sensitive Data');
});
var timeout = new Promise(function(resolve, reject) {
  setTimeout(reject, 2000, new Error('Request timed out'));
});

Promise.race([request, timeout])
  .then(function(data) {
    console.log(data);
  })
  .catch(function(err) {
    console.log(err.message);
  });
Output:
"Request timed out"

This pattern uses Promise.race() to reject the operation if the data request takes longer than the specified timeout period.

3

Racing with Non-Promise Values

var p1 = new Promise(function(resolve) { setTimeout(resolve, 100, 'one'); });
var p2 = 'two';

Promise.race([p1, p2]).then(function(value) {
  console.log(value);
});
Output:
"two"

Non-promise values in the iterable are treated as already resolved promises and will win the race against any pending asynchronous promise.

Debug faster

Common Errors

1

LogicError

Cause: Passing an empty array to Promise.race().

Fix: Ensure the input iterable is not empty, or provide a fallback promise, as an empty race remains pending forever.

Promise.race([]).then(function() { console.log('This will never run'); });
2

LogicError

Cause: Assuming only fulfillment wins the race.

Fix: Handle potential rejections, because if the fastest promise rejects, the entire race rejects immediately even if other promises would have fulfilled later.

var p1 = Promise.reject('Immediate Fail');
var p2 = new Promise(function(res) { setTimeout(res, 100, 'Late Success'); });
Promise.race([p1, p2]).catch(function(err) { console.log(err); });

Runtime support

Compatibility

Node.js, BrowserAll modern browsersES6 (2015)

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Resolves/rejects as soon as the first promise settles.

iterable: Promises (or values) to race.

LogicError: Ensure the input iterable is not empty, or provide a fallback promise, as an empty race remains pending forever. LogicError: Handle potential rejections, because if the fastest promise rejects, the entire race rejects immediately even if other promises would have fulfilled later.