Promise.all, allSettled, race and any
Four static methods run several promises together, and they differ in two questions: does one failure end the whole thing, and which value is the answer. all, allSettled, race and any answer those four combinations, and every one of them takes an array of promises or plain values and returns a single promise.
The programs below use one helper, a promise that resolves after a short fixed delay, because that is what makes the order of the results visible. Each block prints values and the order they arrive in, never a duration, so the output is the same on every machine.
A delay that keeps the order
The helper is two lines: a promise whose executor sets a timer and resolves with the value. Calling it with delays of thirty, ten and twenty milliseconds makes the three results arrive out of order, which is exactly what the next section has to keep straight.
The file delay.mjs:
const delay = (value, ms) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), ms);
});
console.log('the calls are written in the order a, b, c');
const values = await Promise.all([delay('a', 30), delay('b', 10), delay('c', 20)]);
console.log('the results keep the order of the calls:', values.join(','));
node delay.mjs
the calls are written in the order a, b, c
the results keep the order of the calls: a,b,c
The three timers started together and b finished first, yet the array came back as a, b, c. The order of the results is the order of the calls and not the order of the finishes, which is the property that lets a program zip the results with the inputs it asked about.
Promise.all
Promise.all fulfils when every promise has fulfilled, with an array of values in the order of the calls, and rejects as soon as one of them rejects. The others keep running, but their results are dropped: the combined promise has already settled.
The file all.mjs:
const delay = (value, ms) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), ms);
});
const values = await Promise.all([delay('a', 10), delay('b', 20)]);
console.log('both values:', values.join(','));
try {
await Promise.all([
delay('a', 10),
Promise.reject(new Error('the second call failed')),
delay('c', 30),
]);
} catch (error) {
console.log('all rejects as soon as one rejects:', error.message);
}
console.log('the other two delays were still running');
node all.mjs
both values: a,b
all rejects as soon as one rejects: the second call failed
the other two delays were still running
The failure was reported at once, without waiting for the thirty millisecond call, and the program went on while that call was still pending. Nothing cancels the promises that were left: they run to their end, their values are dropped, and a failure among them is not reported either, because the combined promise had already settled. That silence is the reason the next section exists.
Promise.allSettled
Promise.allSettled waits for every promise and never rejects. Each result is an object with a status of fulfilled or rejected, and the field that goes with it: value or reason.
The file allSettled.mjs:
const delay = (value, ms) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), ms);
});
const results = await Promise.allSettled([
delay('the answer', 10),
Promise.reject(new Error('the second call failed')),
]);
console.log('the statuses:', results.map((result) => result.status).join(','));
console.log('the first value:', results[0].value);
console.log('the second reason:', results[1].reason.message);
node allSettled.mjs
the statuses: fulfilled,rejected
the first value: the answer
the second reason: the second call failed
One call succeeded and one failed, and the program has both facts in one array, in the order of the calls. This is the combinator for a report over many items: the failures are data rather than an exception, and a loop over the results decides what to print for each.
race and any
Promise.race settles with the first promise that settles, whether it fulfilled or rejected. Promise.any waits for the first one that fulfils and rejects only when every promise has rejected, with an AggregateError that holds all the reasons.
The file race.mjs:
const delay = (value, ms) =>
new Promise((resolve) => {
setTimeout(() => resolve(value), ms);
});
const winner = await Promise.race([delay('slow', 30), delay('fast', 10)]);
console.log('the race takes the first to finish:', winner);
const first = await Promise.any([Promise.reject(new Error('no')), delay('later value', 20)]);
console.log('any takes the first to succeed:', first);
try {
await Promise.any([Promise.reject(new Error('one')), Promise.reject(new Error('two'))]);
} catch (error) {
console.log('any of rejections:', error.name);
console.log('the messages:', error.errors.map((item) => item.message).join(','));
}
node race.mjs
the race takes the first to finish: fast
any takes the first to succeed: later value
any of rejections: AggregateError
the messages: one,two
The rejected promise did not stop any: it skipped it and took the value that arrived later. Two patterns follow from the two methods: race against a timer is how a timeout is written, and any over several sources is how a program takes the first answer that works. The next lesson writes the same code with await and try, which reads like ordinary statements.
Exercises
- Add a fourth delay of five milliseconds to the first program and move it to the front of the array. Where does its value appear?
- Change the delays in the first program so that all three finish in the order of the calls. Is the result the same?
- Give all a promise that rejects after a delay of ten milliseconds. Which message does the catch print first?
- Print the whole result object of allSettled with JSON.stringify. Which fields appear for a failure?
- Race a slow delay against a rejection. Which one wins, and what does the catch receive?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does Promise.all return when every promise fulfils?
Answer
One promise of an array in the order of the calls
The array keeps the position of each call, whatever the order of the finishes.
-
When does Promise.all reject?
Answer
As soon as one of the promises rejects
The first rejection settles the combined promise, and the rest keep running without a report.
-
What does Promise.allSettled give for each promise?
Answer
An object with a status and a value or a reason
The status says what happened, and the other field carries the result or the reason.
-
What is the difference between race and any?
Answer
race settles with the first settled promise, any with the first fulfilled one
A rejection ends race but is skipped by any until every promise has failed.
-
What does this program print?
const results = await Promise.all([1, 2, 3]); console.log(results.join(","));Answer
1,2,3
A plain value is treated as an already fulfilled promise.
-
What does this program print?
const results = await Promise.allSettled([Promise.resolve(1), Promise.reject(new Error("no"))]); console.log(results.map((result) => result.status).join(","));Answer
fulfilled,rejected
allSettled reports both outcomes, in the order of the calls.
-
What does this program print?
const value = await Promise.race([Promise.resolve("first"), Promise.resolve("second")]); console.log(value);Answer
first
Both are already fulfilled, and race takes the first promise in the array.
-
What does this program print?
try { await Promise.any([Promise.reject(new Error("a")), Promise.reject(new Error("b"))]); } catch (error) { console.log(error.name, error.errors.length); }Answer
AggregateError 2
Every promise failed, so any rejects with the aggregate that holds both reasons.
-
A later call finishes before an earlier one in Promise.all. Where is its value?
Answer
In the position of its own call
The positions are fixed by the calls, and the finishes only fill them.
-
What happens to the promises left when Promise.all rejects?
Answer
They keep running, and their results are dropped
A promise cannot be cancelled from outside, so the work finishes and nobody reads it.
The code on this page was run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev