JavaScript

JavaScript Promise.race() Method

Promise.race() method is a built-in method of JavaScript which takes an iterable of promises as an argument and returns the first promise which is resolved or rejected. The Promise.race() method will either return the fulfilment value or the reason for rejection. Iterables are objects which can be looped through such as Arrays, Strings and Maps.

What are Promises anyway?

Asynchronous code can be dealt with promises. They take a function known as the executor as a parameter. When a promise is created, the executor automatically runs asynchronously and returns a value in case it is fulfilled else it returns the reason for rejection:

let example_promise = newPromise((resolve, reject) => {
  resolve("Promise has been resolved");
});

example_promise.then( r =>console.log(r));

Asynchronous nature of promises:

let example_promise = newPromise((resolve, reject) => {
  resolve("Promise has been resolved");
});

example_promise.then( r =>console.log(r));
console.log("1,2,3...");

How to use Promise.race() Method?

Pass an iterable of promises to the Promise.race() method and get its return value in variable:

let prom1 = newPromise((resolve, reject) => {
  setTimeout(() => resolve("Promise has been resolved"), 500);
});

let prom2 = newPromise((resolve, reject) => {
  setTimeout(() => reject("Promise could not be resolved"), 250);
});

let temp = Promise.race([prom1, prom2]);

temp.catch(reason =>console.log(reason));

In this example we had two promises. The first promise was resolved after 500ms and the second promise was rejected just after 250 seconds. As the second promise was the first one to be either resolved or rejected it was returned by the Promise.race() method.

If the argument passed to the Promise.race() method is an empty iterable then the method will return a forever pending promise:

let temp = Promise.race([]);

console.log(temp);

If the argument iterable has any non-promise values or promises which have already been fulfilled or rejected then the method will settle for the first value in the array:

let p1 = newPromise((resolve, reject) => {
  resolve("P1 has been resolved");
});

let p2 = newPromise((resolve, reject) => {
  resolve("P2 has been resolved");
});

let temp = Promise.race([p1,p2]);
temp.then(value =>console.log(value));

Promise.race() method check for both resolved and rejected promises. This method also has another alternative which is the Promise.any() method which can be used to just check for the fulfilled promises.

Conclusion

Promise.race() method is used to get the first promise that is either fulfilled or rejected from an iterable of promises. The promise which is fulfilled or rejected the earliest is the return value of Promise.race(). The write-up provided in-depth insight into the Promise.race() method.

About the author

Shehroz Azam

A Javascript Developer & Linux enthusiast with 4 years of industrial experience and proven know-how to combine creative and usability viewpoints resulting in world-class web applications. I have experience working with Vue, React & Node.js & currently working on article writing and video creation.