Promise.any() in Javascript

Promise.any(promises) is a helper function that runs promises in parallel and resolves to the value of the first successfully resolved promise from promises list.

Let’s see how Promise.any() works.

1. Promise.any()

Promise.any() is useful to perform independent async operations in a parallel and race manner, to get the value of any first fulfilled promise.

The function accepts an array (or generally an iterable) of promises as an argument:

const anyPromise = Promise.any(promises);        

When any first promise from the input promises is fulfilled, right away the anyPromise resolves to the value of that promise.

You can extract the value of the first promise using a then-able syntax:

anyPromise.then(firstValue => 

 firstValue; // The value of the first fulfilled promise

});
        

or using an async/await syntax:

const firstValue = await anyPromise

firstValue; // The value of the first fulfilled promise;
        

The promise returned by Promise.any()fulfills with any first fulfilled promise. Even if some promises get rejected, these rejections are ignored.

However, if all promises in the input array are rejected or if the input array is empty, then Promise.any() rejects with an aggregate error containing all the rejection reasons of the input promises.

2. Fruits and vegetables

Before diving into Promise.any(), let’s define 2 simple helper functions.

First, resolveTimeout(value, delay) — returns a promise that fulfills with value after passing delay time:

function resolveTimeout(value, delay) {

  return new Promise(

    resolve => setTimeout(() => resolve(value), delay)

  );

}
        

Second, rejectTimeout(reason, delay) — returns a promise that rejects with reason after passing delay time:

function rejectTimeout(reason, delay){

  return new Promise(

    (r, reject) => setTimeout(() => reject(reason), delay)

  );

}
        

Let’s use these helper functions to experiment on Promise.any().

2.1 All promises fulfilled

Let’s try to access the first resolved list from the local grocery store:

const promise = Promise.any([
  
  resolveTimeout(['potatoes', 'tomatoes'], 1000),
  resolveTimeout(['oranges', 'apples'], 2000)

]);

  
// wait...
const list = await promise;
  
// after 1 second
console.log(list); // logs ['potatoes', 'tomatoes']
        

Promise.any([...]) returns a promise that resolves in 1 second to the list of vegetables ['potatoes', 'tomatoes']. All because vegetables promise has fulfilled first.

The second promise, with the list of fruits, resolves in 2 seconds, but its value is ignored.

2.2 One promise rejected

Imagine there are no more vegetables at the grocery. In such a case, let’s reject the vegetables’ promise.

How would Promise.any() would work in such a case?

const promise = Promise.any([

  rejectTimeout(new Error("Out of vegetables!"), 1000),
  resolveTimeout(["oranges", "apples"], 2000)

]);

// wait...
const list = await promise;

// after 2 seconds
console.log(list); // logs ['oranges', 'apples']
        

This case is a little trickier.

First, the vegetables promise gets rejected after 1 second. However, Promise.any() does skip this rejection and still waits to see the status of fruits’ promise.

Finally, after one more second, the fruits promise resolves to a list of fruits ['oranges', 'apples']. Right away the promise returned by Promise.any([...]) also resolves to this value.

2.3 All promises rejected

What if the grocery is out of both vegetables and fruits? In such a case both promises reject:

const promise = Promise.any([
 
 rejectTimeout(new Error('Out of vegetables!'), 1000),
 rejectTimeout(new Error('Out of fruits!'), 2000)

]);

try {
  // wait...
  const list = await promise;
} catch (aggregateError) {
  console.log(aggregateError); // logs AggregateError
  console.log(aggregateError.errors); 
  // logs [Error('Out of vegetables!'), Error('Out of fruits!')]
}
        

All input promises are rejected. Thus the promise returned by Promise.any([...]) also gets rejected with a special kind of error — AggregateError — that contains the rejection reasons of input promises.

The aggregate error provides a special property errors: which is an array containing the errors of the input promises that had been rejected.

3. Conclusion

Promise.any() is useful to perform independent async operations in parallel in a race manner, to get the value of any first successfully resolved promise.

If all input promises of Promise.any() are rejected, then the promise returned by the helper function also rejects with an aggregate error, which contains the rejection reasons of the input promises inside a special property: aggregateError.errors.

Note that Promise.any([]) rejects also if the input array is empty.

Cheers!