JavaScript метод Promise.race()

Определение и применение

JavaScript метод .race() объекта Promise возвращает объект Promise, который имеет состояние rejected (выполнение отклонено), или fulfilled (успешное выполнение). Результат выполнения зависит от того, с каким результатом завершается выполнение первого завершившегося из переданных объектов Promise.

Метод сразу возвращает ожидающее обещание; его успешное выполнение или отклонение происходит асинхронно.

Метод возвращает новое обещание. Обработчики вызываются асинхронно через очередь микрозадач, даже если результат уже известен.

Побеждает первое завершение: успешное или с ошибкой. Обычные значения и thenable также участвуют. Promise.race([]) остаётся ожидающим навсегда. Результат завершается асинхронно; остальные операции не отменяются.

Поддержка браузерами

Спецификация: ecma262

✓Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры

ВсеКомпьютерыМобильные

Совместимостьjavascript.builtins.Promise.race

Возможность	Компьютеры					Мобильные
	ChromeChrome	EdgeEdge	FirefoxFirefox	OperaOpera	SafariSafari	Chrome AndroidChromeAndroid	Firefox for AndroidFirefoxAndroid	Opera AndroidOperaAndroid	Safari on iOSSafariiOS	Samsung BrowserSamsungAndroid	WebView AndroidWebViewAndroid	WebView on iOSWebViewiOS
race	✓32	✓12	✓29	✓19	✓8	✓32	✓29	✓19	✓8	✓2.0	✓4.4.3	✓8

✓поддерживается◐с ограниченияминет поддержки?нет данных≤31 — не позднее версии 31

JavaScript синтаксис

Promise.race(iterable);

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

ECMAScript: Promise.race()

Значения параметров

Примеры, попробуйте сами

Базовое использование метода

В примере «Первое успешное завершение» показан результат вызова метода.

<p>Результат выполнения выводится в консоль под примером.</p>

const promise = new Promise(function (resolve, reject) {
    setTimeout(resolve, 200, 'promise1') // изменяем состояние объекта на fulfilled (успешное выполнение) через 200 мс
})

const promise2 = new Promise(function (resolve, reject) {
    setTimeout(resolve, 100, 'promise2') // изменяем состояние объекта на fulfilled (успешное выполнение) через 100 мс
})

Promise.race([promise, promise2]) // ожидаем выполнение первого из переданных в массиве обещаний
    .then((val) => console.log(val)) // обработчик для успешного выполнения

// promise2

body {
  margin: 16px;
  font:
    16px/1.5 system-ui,
    sans-serif;
  overflow-wrap: anywhere;
}
img,
input,
select,
textarea,
button {
  max-width: 100%;
}

В этом примере мы инициализировали две переменные, которые содержат объект Promise, который изменяет состояние объекта на fulfilled (успешное выполнение) через 200 мс в первом случае, и через 100 мс во втором.

С использованием метода .race() объекта Promise мы принимаем массив, который содержит ссылку на два обещания, результат выполнения этого метода зависит от того с каким результатом завершится выполнение первого из переданных обещаний, в нашем случае это второе обещание (promise2), которое выполнится на 100 мс раньше другого с указанным значением.

С использованием метода then() мы добавили обработчик, вызываемый когда объект Promise имеет состояние fulfilled (успешное выполнение) и выводим в консоль полученное значение.

Далее мы с Вами рассмотрим пример в котором обещание будет отклонено:

В примере «Первое завершение с ошибкой» показан результат вызова метода.

<p>Результат выполнения выводится в консоль под примером.</p>

const promise = new Promise(function (resolve, reject) {
    setTimeout(resolve, 200, 'promise1') // изменяем состояние объекта на fulfilled (успешное выполнение) через 200 мс
})

const promise2 = new Promise(function (resolve, reject) {
    setTimeout(reject, 100, new Error('Обещание отклонено')) // изменяем состояние объекта на rejected (выполнение отклонено) через 100 мс
})

Promise.race([promise, promise2]) // ожидаем выполнение первого из переданных в массиве обещаний
    .then(
        (val) => console.log(val), // обработчик для успешного выполнения
        (err) => console.log(err.message),
    ) // обработчик для случая, когда выполнение отклонено

// Обещание отклонено

body {
  margin: 16px;
  font:
    16px/1.5 system-ui,
    sans-serif;
  overflow-wrap: anywhere;
}
img,
input,
select,
textarea,
button {
  max-width: 100%;
}

По аналогии с предыдущим примером мы инициализировали две переменные, которые содержат объект Promise, который изменяет состояние объекта на fulfilled (успешное выполнение) через 200 мс в первой переменной. Обратите внимание, что с помощью метода reject() мы изменяем значение объекта Promise на rejected (выполнение отклонено) через 100 мс во второй переменной.

С использованием метода .race() объекта Promise мы принимаем массив, который содержит ссылку на два обещания, результат выполнения этого метода зависит от того с каким результатом завершится выполнение первого из переданных обещаний, в нашем случае это второе обещание (promise2), которое будет отклонено на 100 мс раньше другого с указанной ошибкой. В результате чего возвращается объект Promise, который имеет состояние rejected (выполнение отклонено).

С использованием метода then() мы добавили обработчики, вызываемые когда объект Promise имеет состояние fulfilled (успешное выполнение), или rejected (выполнение отклонено). В нашем случае срабатывает обработчик для отклоненного выполнения, и выводит информацию об ошибке в консоль.

Нюансы использования метода

В примере «Обычные значения и пустая гонка» показан результат вызова метода.

<!doctype html>
<html lang="ru">
  <head>
    <meta charset="UTF-8" />
    <title>Обычные значения и пустая гонка</title>
  </head>
  <body>
    <p>Результат выполнения выводится в консоль.</p>
  </body>
</html>

Promise.race(['Тест', 'Тест2']).then((val) => console.log(val)) // обработчик для успешного выполнения

// Тест

Promise.race([Promise.resolve(1), Promise.resolve(2)]).then((val) => console.log(val)) // обработчик для успешного выполнения

// 1

Promise.race([]) // обещание будет вечно в состоянии ожидания

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

Если переданный объект пуст, то возвращенное обещание будет вечно в состоянии ожидания (pending). Учитывайте эти нюансы при использовании метода .race() в своей работе.