Promise.any()

Статический метод Promise.any() принимает итерируемый объект промисов в качестве входных данных и возвращает один Promise. Этот возвращаемый промис разрешается при первом разрешении любого из входных промисов, с этим первым значением разрешения. Он отклоняется, когда все входные промисы отклоняются (включая случай, когда передается пустой итерируемый объект), с AggregateError, содержащим массив причин отклонения.

Попробуйте

const promise1 = Promise.reject(new Error("error"));
const promise2 = new Promise((resolve) => setTimeout(resolve, 100, "quick"));
const promise3 = new Promise((resolve) => setTimeout(resolve, 500, "slow"));

const promises = [promise1, promise2, promise3];

Promise.any(promises).then((value) => console.log(value));

// Expected output: "quick"

Синтаксис

Promise.any(iterable)

Параметры

iterable

Итерируемый объект (например, Array) промисов. Эти значения ожидаются, поэтому другие thenables также разрешаются, а не-thenables возвращаются как есть.

Возвращаемое значение

Promise, который:

• Уже отклонен, если переданный iterable пуст.
• Асинхронно разрешен, когда любой из промисов в заданном iterable разрешается. Значением разрешения является значение разрешения первого разрешенного промиса.
• Асинхронно отклонен, когда все промисы в заданном iterable отклоняются. Причиной отклонения является AggregateError, содержащий массив причин отклонения в своем свойстве errors. Ошибки находятся в порядке переданых промисов, независимо от порядка завершения. Если переданный iterable не пуст, но не содержит ожидающих промисов, возвращаемый промис все равно асинхронно (вместо синхронно) отклоняется.

Описание

Метод Promise.any() является одним из методов параллельного выполнения промисов. Этот метод полезен для возврата первого разрешенного промиса. Он прекращает работу после разрешения промиса, поэтому не ожидает завершения других промисов, как только найдет один.

В отличие от Promise.all(), который возвращает *массив* значений разрешения, мы получаем только одно значение разрешения (при условии, что хотя бы один промис разрешен). Это может быть полезно, если нам нужен только один разрешенный промис, но нам не важно, какой именно. Обратите внимание на еще одно отличие: этот метод отклоняется при получении *пустого итерируемого объекта*, поскольку, по сути, итерируемый объект не содержит элементов, которые разрешаются. Вы можете сравнить Promise.any() и Promise.all() с Array.prototype.some() и Array.prototype.every().

Также, в отличие от Promise.race(), который возвращает первое *установленное* значение (либо разрешение, либо отклонение), этот метод возвращает первое *разрешенное* значение. Этот метод игнорирует все отклоненные промисы до первого разрешенного промиса.

Как и другие комбинаторы промисов, Promise.any() немедленно помечает все промисы как "обработанные" при вызове (путем вызова их методов .then()). Последующие отклонения после первого разрешения будут проигнорированы и не вызовут никаких событий unhandledrejection.

Разрешение возвращаемого промиса не отменяет остальные операции и не отписывает обработчики, прикрепленные к их промисам. Повторная передача долгоживущего ожидающего промиса в Promise.any() может накапливать обработчики для этого промиса, даже если каждый раз разрешается другой входной промис.

Примеры

Использование Promise.any()

Promise.any() разрешается первым разрешенным промисом, даже если какой-то промис отклонился раньше. Это отличается от Promise.race(), который разрешается или отклоняется первым установленным промисом.

const pErr = new Promise((resolve, reject) => {
  reject(new Error("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
});
// Logs:
// Done quick

Отклонения с AggregateError

Promise.any() отклоняется с AggregateError, если ни один промис не разрешился.

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

Promise.any([failure]).catch((err) => {
  console.log(err);
});
// AggregateError: No Promise in Promise.any was resolved

Отображение первой загруженной картинки

В этом примере у нас есть функция, которая загружает изображение и возвращает blob. Мы используем Promise.any() для загрузки нескольких изображений и отображения первого доступного (т.е. чей промис разрешился).

async function fetchAndDecode(url, description) {
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`HTTP error! status: ${res.status}`);
  }
  const data = await res.blob();
  return [data, description];
}

const coffee = fetchAndDecode("coffee.jpg", "Coffee");
const tea = fetchAndDecode("tea.jpg", "Tea");

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

Спецификации

Совместимость с браузерами

См. также

• Polyfill для Promise.any в core-js
• Polyfill Promise.any от es-shims
• Promise
• Promise.all()
• Promise.allSettled()
• Promise.race()