The Promise.race(iterable)
method returns a promise that resolves or rejects as soon as one of the promises in the iterable resolves or rejects, with the value or reason from that promise.
Syntax
Promise.race(iterable);
Parameters
Return value
A pending Promise
that resolves or rejects asynchronically (as soon as the stack is empty) as soon as one of the promises in the given iterable resolves or rejects, adopting that first promise's value as its value.
Description
The race
function returns a Promise
that is settled the same way (and takes the same value) as the first promise that settles amongst the promises of the iterable passed as argument.
If the iterable passed is empty, the promise returned will be forever pending.
If the iterable contains one or more non-promise value and/or an already resolved/rejected promise, then Promise.race
will resolve to the first of these values found in the iterable.
Examples
Asynchronicity of Promise.race
This following example demonstrates the asynchronicity of Promise.race:
// we are passing as argument an array of promises that are already resolved, // to trigger Promise.race as soon as possible var resolvedPromisesArray = [Promise.resolve(33), Promise.resolve(44)]; var p = Promise.race(resolvedPromisesArray); // immediately logging the value of p console.log(p); // using setTimeout we can execute code after the stack is empty setTimeout(function(){ console.log('the stack is now empty'); console.log(p); }); // logs, in order: // Promise { <state>: "pending" } // the stack is now empty // Promise { <state>: "fulfilled", <value>: 33 }
An empty iterable causes the returned promise to be forever pending:
var foreverPendingPromise = Promise.race([]); console.log(foreverPendingPromise); setTimeout(function(){ console.log('the stack is now empty'); console.log(foreverPendingPromise); }); // logs, in order: // Promise { <state>: "pending" } // the stack is now empty // Promise { <state>: "pending" }
If the iterable contains one or more non-promise value and/or an already resolved/rejected promise, then Promise.race
will resolve to the first of these values found in the array:
var foreverPendingPromise = Promise.race([]); var alreadyResolvedProm = Promise.resolve(666); var arr = [foreverPendingPromise, alreadyResolvedProm, "non-Promise value"]; var arr2 = [foreverPendingPromise, "non-Promise value", Promise.resolve(666)]; var p = Promise.race(arr); var p2 = Promise.race(arr2); console.log(p); console.log(p2); setTimeout(function(){ console.log('the stack is now empty'); console.log(p); console.log(p2); }); // logs, in order: // Promise { <state>: "pending" } // Promise { <state>: "pending" } // the stack is now empty // Promise { <state>: "fulfilled", <value>: 666 } // Promise { <state>: "fulfilled", <value>: "non-Promise value" }
Using Promise.race
– examples with setTimeout
var p1 = new Promise(function(resolve, reject) { setTimeout(resolve, 500, 'one'); }); var p2 = new Promise(function(resolve, reject) { setTimeout(resolve, 100, 'two'); }); Promise.race([p1, p2]).then(function(value) { console.log(value); // "two" // Both resolve, but p2 is faster }); var p3 = new Promise(function(resolve, reject) { setTimeout(resolve, 100, 'three'); }); var p4 = new Promise(function(resolve, reject) { setTimeout(reject, 500, 'four'); }); Promise.race([p3, p4]).then(function(value) { console.log(value); // "three" // p3 is faster, so it resolves }, function(reason) { // Not called }); var p5 = new Promise(function(resolve, reject) { setTimeout(resolve, 500, 'five'); }); var p6 = new Promise(function(resolve, reject) { setTimeout(reject, 100, 'six'); }); Promise.race([p5, p6]).then(function(value) { // Not called }, function(reason) { console.log(reason); // "six" // p6 is faster, so it rejects });
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Promise.race' in that specification. |
Standard | Initial definition in an ECMA standard. |
ECMAScript Latest Draft (ECMA-262) The definition of 'Promise.race' in that specification. |
Draft |
Browser compatibility
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Feature | Chrome | Firefox | Edge | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic Support | 32.0 | 29.0 | (Yes) | (No) | 19 | 7.1 |
Feature | Android | Chrome for Android | Edge mobile | Firefox for Android | IE mobile | Opera Android | iOS Safari |
---|---|---|---|---|---|---|---|
Basic Support | 4.4.4 | 32.0 | (Yes) | 29 | (No) | (Yes) | 8.0 |