Promise.any()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

Метод Promise.any() принимает итерируемый объект содержащий объекты промисов Promise. Как только один из промисов (Promise) выполнится успешно (fulfill), метод возвратит единственный объект Promise со значением выполненного промиса. Если ни один из промисов не завершится успешно (если все промисы завершатся с ошибкой, т.е. rejected), тогда возвращённый объект Promise будет отклонён (rejected) с одним из значений: массив содержащий причины ошибки (отклонения), или AggregateError — подкласс Error, который объединяет выброшенные ошибки вместе. По существу, метод Promise.any() является противоположностью для Promise.all().

Синтаксис

Promise.any(iterable);

Параметры

iterable

Итерируемый(iterable) объект, например Array.

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

  • Исполненный Promise, если переданный итерируемый объект пуст.
  • Исполненный асинхронно Promise, если переданный итерируемый объект не содержит промисов.
  • Во всех других случаях Promise со статусом ожидания(pending). Возвращённый промис будет исполнен(resolved/rejected) асинхронно (как только стэк вызовов окажется пустым), когда один (любой) промис из переданного итерируемого объекта исполнится, либо все промисы будут отклонены.

Описание

Метод полезен, когда нужно вернуть первый исполненный промис. После того как один из промисов будет исполнен, метод не будет дожидаться исполнения остальных. В отличие от Promise.all(), который содержит массив(Array) значений исполненных промисов, Promise.any() содержит только одно значение (при условии, что хотя бы один из промисов исполнен успешно). Такой подход может быть выгодным, когда нужно, чтобы выполнился только один промис, неважно какой. Также, в отличие от Promise.race(), который возвращает промис, содержащий значение первого завершённого(resolved или rejected), этот метод возвращает промис содержащее значение первого успешно выполненного(resolved) промиса. Метод будет игнорировать исполнение промисов с ошибкой(rejection) вплоть до первого исполненного успешно (fulfilment).

Успешное исполнение(Fulfilment)

Если один из промисов исполнится успешно, возвращённый промис асинхронно исполнится успешно со значением выполненного промиса, независимо от завершения остальных промисов.

  • Если передан пустой итерируемый объект, тогда метод возвращает (синхронно) выполненный промис.
  • Если один из переданных промисов исполнится успешно, или в переданном итерируемом объекте не содержится промисов, промис возвращённый из метода Promise.any асинхронно исполнится успешно.

Исполнение с ошибкой(Rejection)

Если все переданные промисы будут отклонены (rejected), Promise.any асинхронно будет отклонено в одном из двух вариантов (которые ещё не были согласованы): либо

  • Массив(Array) содержащий причины отклонения всех промисов переданных в итерируемом объекте, либо
  • Объект AggregateError, расширяющий Error, который содержит указатель на массив(Array) исключений.

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

Specification
ECMAScript Language Specification
# sec-promise.any

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

BCD tables only load in the browser

Смотрите также