W3cubDocs

/JavaScript

Promise.any()

Promise.any() takes an iterable of Promise objects. It returns a single promise that fulfills as soon as any of the promises in the iterable fulfills, with the value of the fulfilled promise. If no promises in the iterable fulfill (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.

Try it

Syntax

Promise.any(iterable)

Parameters

iterable

An iterable object, such as an Array.

Return value

  • An already rejected Promise if the iterable passed is empty.
  • An asynchronously fulfilled Promise if the iterable passed contains no promises.
  • A pending Promise in all other cases. This returned promise is then fulfilled/rejected asynchronously (as soon as the stack is empty) when any of the promises in the given iterable fulfills, or if all the promises have rejected.

Description

This method is useful for returning the first promise that fulfills. It short-circuits after a promise fulfills, 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 fulfill but we do not care which one does. Note another difference: This method rejects upon receiving an empty iterable, since, truthfully, the iterable contains no items that fulfill.

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 fulfills.

Fulfillment

The returned promise is fulfilled with the first fulfilled value (or non-promise value) in the iterable passed as the argument, whether or not the other promises have rejected.

  • If a nonempty iterable is passed, and any of the promises fulfill, or are not promises, then the promise returned by this method 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.

  • If an empty iterable is passed, then the promise returned by this method is rejected synchronously. The rejected reason is an AggregateError object whose errors property is an empty array.

Examples

First to fulfill

Promise.any() fulfills with the first promise to fulfill, even if a promise rejects first. This is in contrast to Promise.race(), which fulfills 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 fulfills first
});
// expected output: "Done quick"

Rejections with AggregateError

Promise.any() rejects with an AggregateError if no promise fulfills.

const failure = new Promise((resolve, reject) => {
  reject("Always fails");
});

Promise.any([failure]).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();
    }
  });
}

const coffee = fetchAndDecode("coffee.jpg");
const tea = fetchAndDecode("tea.jpg");

Promise.any([coffee, tea])
  .then((value) => {
    const objectURL = URL.createObjectURL(value);
    const image = document.createElement("img");
    image.src = objectURL;
    document.body.appendChild(image);
  })
  .catch((e) => {
    console.error(e);
  });

Specifications

Browser compatibility

Desktop Mobile Server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet Deno Node.js
any
85
85
79
No
71
14
85
85
79
60
14
14.0
1.2
15.0.0

See also

© 2005–2022 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any