Promise.any()
takes an iterable of Promise
objects and, as soon as one of the promises in the iterable fulfils, returns a single promise that resolves with the value from that promise. If no promises in the iterable fulfil (if all of the given promises are rejected), then the returned promise is rejected with an AggregateError
, a new subclass of Error
that groups together individual errors. Essentially, this method is the opposite of Promise.all()
.
Warning! The Promise.any()
method is experimental and not fully supported by all browsers and platforms. It is currently in stage 4 of the TC39 process.
Syntax
Promise.any(iterable);
Parameters
Return value
- An already resolved
Promise
if the iterable passed is empty. - An asynchronously resolved
Promise
if the iterable passed contains no promises. - A pending
Promise
in all other cases. This returned promise is then resolved/rejected asynchronously (as soon as the stack is empty) when any of the promises in the given iterable resolve, or if all the promises have rejected.
Description
This method is useful for returning the first promise that fulfils. It short-circuits after a promise fulfils, so it does not wait for the other promises to complete once it finds one. Unlike Promise.all()
, which returns an array of fulfillment values, we only get one fulfillment value (assuming at least one promise fulfills). This can be beneficial if we need only one promise to fulfil but we do not care which one does. Also, unlike Promise.race()
, which returns the first settled value (either fulfillment or rejection), this method returns the first fulfilled value. This method will ignore all rejected promises up until the first promise that fulfils.
Fulfilment
If any of the passed-in promises fulfil, the returned promise asynchronously fulfils with the value of the promise that fulfilled, whether or not the other promises have fulfilled or rejected.
- If an empty iterable is passed, then this method returns (synchronously) an already resolved promise.
- If any of the passed-in promises fulfill or are not promises, the promise returned by
Promise.any
is fulfilled asynchronously.
Rejection
If all of the passed-in promises reject, Promise.any
asynchronously rejects with an AggregateError
object, which extends Error
, and contains an errors
property with an array of rejection values.
Examples
First to fulfil
Promise.any()
resolves with the first promise to fulfil, even if a promise rejects first. This is in contrast to Promise.race()
, which resolves or rejects with the first promise to settle.
const pErr = new Promise((resolve, reject) => { reject("Always fails"); }); const pSlow = new Promise((resolve, reject) => { setTimeout(resolve, 500, "Done eventually"); }); const pFast = new Promise((resolve, reject) => { setTimeout(resolve, 100, "Done quick"); }); Promise.any([pErr, pSlow, pFast]).then((value) => { console.log(value); // pFast fulfils first }) // expected output: "Done quick"
Rejections with AggregateError
Promise.any()
rejects with an AggregateError
if no promise fulfils.
const pErr = new Promise((resolve, reject) => { reject('Always fails'); }); Promise.any([pErr]).catch((err) => { console.log(err); }) // expected output: "AggregateError: No Promise in Promise.any was resolved"
Displaying the first image loaded
In this example, we have a function that fetches an image and returns a blob. We use Promise.any()
to fetch a couple of images and display the first one available (i.e. whose promise has resolved).
function fetchAndDecode(url) { return fetch(url).then(response => { if(!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } else { return response.blob(); } }) } let coffee = fetchAndDecode('coffee.jpg'); let tea = fetchAndDecode('tea.jpg'); Promise.any([coffee, tea]).then(value => { let objectURL = URL.createObjectURL(value); let image = document.createElement('img'); image.src = objectURL; document.body.appendChild(image); }) .catch(e => { console.log(e.message); });
Specifications
Specification |
---|
Promise.any |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
any | Chrome Full support 85 | Edge No support No | Firefox Full support 79 | IE No support No | Opera No support No | Safari Full support 14 | WebView Android Full support 85 | Chrome Android Full support 85 | Firefox Android No support No | Opera Android No support No | Safari iOS Full support 14 | Samsung Internet Android No support No | nodejs No support No |
Legend
- Full support
- Full support
- No support
- No support