Promise.any()

Promise.any() приймає ітерабельний об'єкт з об'єктами Promise та, як тільки один з промісів виконується, вертає єдиний проміс, який вирішується зі значенням цього проміса. Якщо жодний проміс не виконався (якщо усі надані проміси були відхилені), тоді повернений проміс буде відхилено з об'єктом, який досі є предметом обговорення: або масив причин відхилення, або AggregateError, новий підклас Error, який поєднує окремі помилки. Найголовніше, цей метод є протилежністю методу Promise.all().

Застереження! Метод Promise.any() є експериментальним та не повністю підтримується усіма переглядачами. Він наразі на стадії TC39 Candidate stage (стадія 3).

Синтаксис

Promise.any(iterable);

Параметри

iterable
Ітерабельний об'єкт, такий як Array.

Значення, що повертається

  • Вже вирішений проміс, якщо переданий ітерабельний об'єкт є порожнім.
  • Асинхронно вирішений проміс, якщо переданий ітерабельний об'єкт не містить промісів.
  • Проміс у стані очікування у всіх інших випадках. Цей повернений проміс далі вирішується/відхиляється асинхронно (як тільки стек стане порожнім), коли будь-який з промісів у переданому ітерабельному об'єкті буде вирішено, або якщо усі проміси буде відхилено.

Опис

Цей метод корисний для повернення першого проміса, який виконується. Він завершується після виконання проміса, тому не очікує на завершення інших промісів, як тільки його знаходить. На відміну від Promise.all(), який вертає масив вирішених значень, ми отримуємо лише одне вирішене значення (за умови, що принаймні один проміс вирішується). Це може бути вигідно, якщо нам потрібно, щоб лише один проміс було вирішено, і нам байдуже, який саме. Також, на відміну від Promise.race(), який вертає перше встановлене значення, цей метод вертає перше вирішене значення. Цей метод ігноруватиме усі відхилені проміси до першого вирішеного проміса.

Виконання

Якщо будь-який з переданих промісів виконається, повернений проміс асинхронно виконується зі значенням виконаного проміса, незалежно від того, чи були інші проміси виконані чи відхилені.

  • Якщо був переданий порожній ітерабельний об'єкт, тоді цей метод вертає (синхронно) вже вирішений проміс.
  • Якщо будь-який з переданих промісів виконується, або передано не проміси, проміс, повернений Promise.any виконується асинхронно.

Відхилення

Якщо усі передані проміси було відхилено, Promise.any асинхронно відхиляється з одним з двох варіантів (щодо яких ще не дійшли згоди): 

  • масив, що містить усі причини відхилень ітерабельного об'єкта, переданого в якості аргумента, або
  • об'єкт AggregateError, що розширює Error та містить вказівник на масив винятків.

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

Специфікація
ESNext Promise.any Proposal

Сумісність з веб-переглядачами

No compatibility data found. Please contribute data for "javascript.builtins.Promise.any" (depth: 1) to the MDN compatibility data repository.

Див. також