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

  1. 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?
  2. Change the delays in the first program so that all three finish in the order of the calls. Is the result the same?
  3. Give all a promise that rejects after a delay of ten milliseconds. Which message does the catch print first?
  4. Print the whole result object of allSettled with JSON.stringify. Which fields appear for a failure?
  5. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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