JavaScript Promise

Promise.all, allSettled, and race, including rejection handling and the fact that a Promise is not cancelled automatically.

Promise is an ECMAScript built-in for a value that will be produced later. It is not the Fetch API, and it does not cancel work on its own. AbortSignal can be used with some Web APIs and some Node.js APIs, but it is not a method on Promise.

The examples below use async functions and timers that are available in Node.js. They do not use the DOM.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
Promise.all and Promise.allSettledWait for every input to fulfill, or collect every outcome, including rejections. A throw inside the executor rejects the new Promise.
Promise.raceSettle with the first of the inputs to settle. This does not cancel the remaining work.

all, allSettled, and executor errors

If the executor function throws, the Promise rejects. That is not the same as a later throw inside a then callback, but both become a rejection you can handle.

Promise.all() fulfills with an array of results, or rejects at the first rejection. Promise.allSettled() waits for every input and reports both fulfillments and rejections.

Promise.all and Promise.allSettled

Promise.all(iterable)
Promise.allSettled(iterable)
new Promise(executor)

Wait for every input to fulfill, or collect every outcome, including rejections. A throw inside the executor rejects the new Promise.

ParameterDescription
iterableAn iterable of promises or thenable values.
executorA function that receives resolve and reject. If it throws synchronously, the Promise rejects with that error.

Returns: A Promise. all() fulfills with an array of values. allSettled() fulfills with an array of { status, value } or { status, reason } objects.

  • Handle all() with try/catch or .catch(). allSettled() does not throw just because one input rejected.
javascript
async function main() {
  const thrown = new Promise(() => { throw new Error("boom"); });
  console.log(await thrown.then(() => "ok", (error) => error.message));
  console.log((await Promise.all([Promise.resolve(1), Promise.resolve(2)])).join(","));
  const settled = await Promise.allSettled([
    Promise.resolve("ok"),
    Promise.reject(new Error("nope")),
  ]);
  console.log(settled.map((item) => item.status).join(","));
  try {
    await Promise.all([Promise.resolve(1), Promise.reject(new Error("fail"))]);
  } catch (error) {
    console.log(error.message);
  }
}
await main();

Expected output

boom
1,2
fulfilled,rejected
fail

Related: Promise.race

MDN documentation →

race does not cancel the losers

Promise.race() settles with the first input that fulfills or rejects. The other inputs keep running. If you need to stop work, you have to do that yourself, for example with a flag or an AbortSignal on an API that accepts one.

Promise.race

Promise.race(iterable)

Settle with the first of the inputs to settle. This does not cancel the remaining work.

Returns: A Promise that fulfills or rejects with the first settled input.

  • The timers in this example keep the process running until both complete, which is why the final counts are 2 and 2.
  • This example uses setTimeout, which is available in Node.js and in browsers. It does not use document or fetch.
javascript
async function main() {
  let started = 0;
  let finished = 0;
  function later(ms, value) {
    started += 1;
    return new Promise((resolve) => {
      setTimeout(() => {
        finished += 1;
        resolve(value);
      }, ms);
    });
  }
  console.log(await Promise.race([later(5, "fast"), later(20, "slow")]));
  await new Promise((resolve) => setTimeout(resolve, 40));
  console.log(started, finished);
}
await main();

Expected output

fast
2 2

MDN documentation →