all vs race vs allSettled

They all take an iterable of promises and return a promise, but they differ in when they settle and what they do when one of the inputs fails.

Promise.all waits for every promise to fulfil, and then resolves with an array of the results in the original order. If any of them rejects, the returned promise rejects immediately with that reason, and the other promises keep running but their results are ignored.

Promise.race settles with whichever promise settles first, whether that is a fulfilment or a rejection. It is the tool for implementing a timeout, or for taking the quickest response from several sources.

Promise.allSettled waits for every promise to settle and then resolves with an array describing the outcome of each one, either a status of fulfilled with the value or a status of rejected with the reason. It never rejects, which makes it the right choice when you want to collect several results and handle the failures individually rather than losing all of them.

const ok = (v) => Promise.resolve(v);
const fail = (msg) => Promise.reject(new Error(msg));

Promise.allSettled([ok(1), fail("bad"), ok(3)]).then((results) => {
  for (const result of results) {
    console.log(result.status, result.value ?? result.reason.message);
  }
});

The ordering guarantee of all is worth stating, because it is the one people forget. The results array is in the order of the input array, not in the order the promises completed, so you can always line the results up with the inputs that produced them.

Promise.all is for when you genuinely need every result and a failure of any one of them means the whole operation failed. Loading a page that needs a user profile, their permissions and their settings is the classic case: if any of the three requests fails, the page cannot render correctly, so failing fast is right.

Promise.race is for when you want the first answer, not all of them. A timeout is the standard use, where you race the real request against a promise that rejects after a delay. It is also useful when you query several mirrors of the same data and take whichever responds first, and it is how you implement a circuit breaker around a flaky service.

Promise.allSettled is for when you want all the outcomes but you do not want one failure to cancel the rest. Rendering a dashboard of several independent widgets is the ideal example, because one failing panel should not blank out the other four. It is also the right tool for a bulk operation where you want to report which items failed.

There is also a fourth option that comes up in interviews. Promise.any resolves with the first promise to fulfil and only rejects if every one of them rejects. It is the mirror image of race, and it is the right choice when you have several interchangeable sources and want the first success rather than the first outcome.

One practical warning about all: it rejects as soon as any input rejects, so if you need every result even when some fail, use allSettled instead of all. That difference is a very common source of a dashboard showing nothing at all because one panel failed.

The difference shows up in two places: what the combinator resolves with, and how quickly it settles.

const ok = (v, ms = 20) => new Promise((r) => setTimeout(() => r(v), ms));
const fail = (msg, ms = 10) => new Promise((_, r) => setTimeout(() => r(new Error(msg)), ms));

// all: fails fast, as soon as one input rejects.
Promise.all([ok("a", 30), fail("b", 10)])
  .then((values) => console.log("all resolved:", values))
  .catch((err) => console.log("all rejected:", err.message));

// allSettled: waits for everything and reports each outcome.
Promise.allSettled([ok("a", 30), fail("b", 10)]).then((results) => {
  console.log("allSettled:", results.map((r) => r.status));
});

// race: takes whichever settles first.
Promise.race([ok("slow", 50), fail("fast", 10)])
  .then((value) => console.log("race resolved:", value))
  .catch((err) => console.log("race rejected:", err.message));

// any: takes the first success, and only fails if every one fails.
Promise.any([fail("x", 10), ok("y", 20)])
  .then((value) => console.log("any resolved:", value))
  .catch((err) => console.log("any rejected:", err.message));

Read the timings as well as the values. The all combinator rejects after about ten milliseconds because the failing promise settles first, even though the slow one is still pending. The allSettled combinator only reports after about thirty milliseconds, because it waits for everything. The race combinator settles after ten milliseconds with the failure, since a rejection counts as settling.

Two behaviours that are easy to get wrong. First, when all rejects, the other promises are not cancelled. They keep running and their results are simply discarded, so if one of them was a write to a server, that write still happens.

Second, race and any behave differently on failure. Race takes the first outcome, including a rejection, so a single fast failure loses the race. Any ignores rejections and waits for the first success, only rejecting if every input rejects. That is why any is the right tool for interchangeable sources and race is the right tool for a timeout.