Merge pull request #1720 from Alexandre887/master

Добавлено описание метода `Promise.any` в статью "Promise API"

Author: Alexandre887

1-js/11-async/05-promise-api/article.md

@@ -1,6 +1,6 @@
 # Promise API
 
-В классе `Promise` есть 5 статических методов. Давайте познакомимся с ними.
+В классе `Promise` есть 6 статических методов. Давайте познакомимся с ними.
 
 ## Promise.all
 
@@ -205,7 +205,7 @@ if(!Promise.allSettled) {
 
 ## Promise.race
 
-Метод очень похож на `Promise.all`, но ждёт только первый выполненный промис, из которого берёт результат (или ошибку).
+Метод очень похож на `Promise.all`, но ждёт только первый *выполненный* промис, из которого берёт результат (или ошибку).
 
 Синтаксис:
 
@@ -225,6 +225,43 @@ Promise.race([
 
 Быстрее всех выполнился первый промис, он и дал результат. После этого остальные промисы игнорируются.
 
+## Promise.any
+
+Метод очень похож на `Promise.race`, но ждёт только первый *успешно выполненный* промис, из которого берёт результат. Если ни один из переданных промисов не завершится успешно, тогда возвращённый объект Promise будет отклонён с помощью [`AggregateError`](mdn:js/AggregateError) – специального объекта ошибки, который хранит все ошибки промисов в свойстве `errors`.
+
+Синтаксис:
+
+```js
+let promise = Promise.any(iterable);
+```
+
+Например, здесь, результатом будет `1`:
+
+```js run
+Promise.any([
+  new Promise((resolve, reject) => setTimeout(() => reject(new Error("Ошибка!")), 1000)),
+  new Promise((resolve, reject) => setTimeout(() => resolve(1), 2000)),
+  new Promise((resolve, reject) => setTimeout(() => resolve(3), 3000))
+]).then(alert); // 1
+```
+
+Первый промис в этом примере был самым быстрым, но он был отклонён, поэтому результатом стал второй. После того, как первый успешно выполненный промис "выиграет гонку", все дальнейшие результаты будут проигнорированы.
+
+Вот пример, в котором все промисы отклоняются:
+
+```js run
+Promise.any([
+  new Promise((resolve, reject) => setTimeout(() => reject(new Error("Ошибка!")), 1000)),
+  new Promise((resolve, reject) => setTimeout(() => reject(new Error("Ещё одна ошибка!")), 2000))
+]).catch(error => {
+  console.log(error.constructor.name); // AggregateError
+  console.log(error.errors[0]); // Error: Ошибка!
+  console.log(error.errors[1]); // Error: Ещё одна ошибка!
+});
+```
+
+Как вы можете видеть, объекты ошибок для отклонённых промисов доступны в свойстве `errors` объекта `AggregateError`.
+
 ## Promise.resolve/reject
 
 Методы `Promise.resolve` и `Promise.reject` редко используются в современном коде, так как синтаксис `async/await` (мы рассмотрим его [чуть позже](info:async-await)) делает их, в общем-то, не нужными.
@@ -286,8 +323,9 @@ let promise = new Promise((resolve, reject) => reject(error));
 2. `Promise.allSettled(promises)` (добавлен недавно) -- ждёт, пока все промисы завершатся и возвращает их результаты в виде массива с объектами, у каждого объекта два свойства:
     - `state`: `"fulfilled"`, если выполнен успешно или `"rejected"`, если ошибка,
     - `value` - результат, если успешно или `reason` - ошибка, если нет.
-3. `Promise.race(promises)` -- ожидает первый выполненный промис, который становится его результатом, остальные игнорируются.
-4. `Promise.resolve(value)` -- возвращает успешно выполнившийся промис с результатом `value`.
-5. `Promise.reject(error)` -- возвращает промис с ошибкой `error`.
+3. `Promise.race(promises)` -- ожидает первый *выполненный* промис, который становится его результатом, остальные игнорируются.
+4. `Promise.any(promises)` (добавлен недавно) -- ожидает первый *успешно выполненный* промис, который становится его результатом, остальные игнорируются. Если все переданные промисы отклонены, [`AggregateError`](mdn:js/AggregateError) становится ошибкой `Promise.any`.
+5. `Promise.resolve(value)` -- возвращает успешно выполнившийся промис с результатом `value`.
+6. `Promise.reject(error)` -- возвращает промис с ошибкой `error`.
 
 Из всех перечисленных методов, самый часто используемый - это, пожалуй, `Promise.all`.