Promise combinators

Many promises, one plan

A promise is an object that stands for a result that isn't ready yet. You met it in the Promises lesson. Real pages often wait for many things at once:

• A dashboard may need the user, the settings, the messages, and the chart data.
• A photo uploader may send ten photos at the same time.
• A page may ask three servers for the same file and keep the first good answer.

Each promise ends in one of two ways. It fulfills: the work worked, and the promise has a value. Or it rejects: the work failed, and the promise has a reason. Both are called settling. A promise that hasn't settled yet is pending.

Promise combinators are methods that turn many promises into one promise. You call them on Promise itself, like Promise.all(...). You give them a list of promises, usually an array. They give back one new promise for the whole group. This lesson also uses ideas from Microtasks in depth, Promise chaining, and Error handling with promises.

1const user = Promise.resolve("Asha");2const cartItems = Promise.resolve(3);3 4Promise.all([user, cartItems]).then((values) => {5  console.log(values.join(" / "));6});

Line 1 makes a promise that fulfills with the name "Asha". Line 2 makes a promise that fulfills with the number 3, the number of items in a cart. Line 4 gives both promises to Promise.all in an array. When both are done, values is the array ["Asha", 3]. Line 5 joins the values and prints Asha / 3.

Each method in this lesson answers one question. Do you need every value, a report for each one, the first result, or the first success?

Promise.all takes an iterable: anything you can loop over with for...of, like an array. Each item can be:

• a promise,
• a thenable: any object with a then method, which JavaScript treats like a promise,
• or a plain value, like "plain". A plain value counts as a promise that has already fulfilled.

If the array is empty, Promise.all([]) fulfills right away with an empty array.

The values come back in input order: the order you passed the promises in. They don't come back in the order the promises finish. So a slow promise placed first still gets the first place.

The replay below uses three cooking tasks. Each task is a promise with a timer:

• Task A takes 30 milliseconds.
• Task B takes 10 milliseconds.
• Task C takes 20 milliseconds.

Choose which task fails, then step through it. When one task fails, Promise.all rejects right away. This is called fail-fast. The other tasks are not stopped. Their timers still run to the end.

1function cook(label, ms, shouldFail) {2  return new Promise((resolve, reject) => {3    setTimeout(() => {4      if (shouldFail) reject(label + " dropped");5      else resolve(label + " ready");6    }, ms);7  });8}9 10const orders = [11  cook("A", 30, false),Run12  cook("B", 10, true),13  cook("C", 20, false),14];15 16Promise.all(orders).then(17  (values) => console.log(values.join(" | ")),18  (reason) => console.log("failed: " + reason),19);

Promise.allSettled also takes an iterable. It waits until every promise has settled, even the ones that fail. A failed input doesn't make it reject. It gives back one report object for each input:

• For a promise that fulfilled: { status: "fulfilled", value }.
• For a promise that rejected: { status: "rejected", reason }.

Use it when you want to show every result, failures included. Upload reports and test results are good examples.

1Promise.allSettled([2  Promise.resolve("saved"),3  Promise.reject("offline"),4]).then((results) => {5  console.log(results.map((item) => item.status).join(" / "));6});

Line 2 is a promise that fulfills with "saved". Line 3 is a promise that rejects with "offline". results holds two report objects, in input order. Line 5 reads the status of each report and prints fulfilled / rejected. The failed promise is still in the report.

In the kitchen race track below, four tasks run on real timers. Pick a method to run them with and watch the timeline. You'll meet race and any in the next section.

1const tasks = [2  task("A", 800, true),3  task("B", 450, true),4  task("C", 1100, false),5];6 7Promise.all(tasks);        // every task must fulfill8Promise.allSettled(tasks); // report every result9Promise.race(tasks);       // first to finish wins10Promise.any(tasks);        // first success wins

Promise.race settles as soon as the first input settles. It copies that first result:

• If the first promise to finish fulfills, the race fulfills with its value.
• If the first promise to finish rejects, the race rejects with its reason.

With an empty array, Promise.race([]) stays pending forever. There is no promise that can finish first.

Promise.any waits for the first promise that fulfills. It skips failures, as long as another promise could still succeed. If every input rejects, Promise.any rejects with an AggregateError. An AggregateError is one error that holds a list of errors. Its .errors array lists the reasons in input order. Promise.any([]) rejects right away with an AggregateError, because no promise can ever succeed.

1const offline = Promise.reject("offline");2const tea = Promise.resolve("tea");3 4Promise.race([offline, tea]).catch((reason) => console.log("race: " + reason));5Promise.any([offline, tea]).then((value) => console.log("any: " + value));

Line 1 is a promise that has already rejected with "offline". Line 2 is a promise that has already fulfilled with "tea". Both lines 4 and 5 get the same array:

• Line 4: race takes the first result, which is the failure. It prints race: offline.
• Line 5: any skips the failure and takes the success. It prints any: tea.

Here are the small cases that are easy to forget. The last line rejects on purpose.

1await Promise.all(["plain", Promise.resolve("promise")]);2await Promise.all([]);3Promise.race([]); // stays pending forever4await Promise.any([]); // rejects with AggregateError

• Line 1: a plain value and a promise in one array. You get ["plain", "promise"].
• Line 2: an empty array. You get an empty array.
• Line 3: an empty race never settles, so the code doesn't wait for it.
• Line 4: an empty any rejects with an AggregateError.

1Promise.all([]).then((values) => console.log("all " + values.length));2Promise.allSettled([]).then((values) => console.log("settled " + values.length));3Promise.any([]).catch((error) => console.log(error.name + " " + error.errors.length));4 5let raceSettled = false;6Promise.race([]).then(() => { raceSettled = true; });7setTimeout(() => console.log("race pending " + !raceSettled), 10);

Lines 1 to 3 give each method an empty array. Line 5 starts an empty race, and line 6 checks it 10 milliseconds later. The output is:

• all 0: Promise.all fulfilled with an empty array.
• settled 0: Promise.allSettled did the same.
• AggregateError 0: Promise.any rejected with an AggregateError that holds no errors.
• race pending true: the race is still pending.

So if your array might be empty, don't pass it to Promise.race alone. Add a timer or another way to stop waiting.

Usually you make a promise with new Promise((resolve, reject) => ...). The two functions resolve and reject settle the promise. But they only exist inside those brackets.

Sometimes the code that makes the promise isn't the code that knows when to settle it. A click handler is one example. Promise.withResolvers() helps here. It gives back an object with three things:

• promise: the new promise, which other code can wait on.
• resolve: a function that fulfills the promise.
• reject: a function that rejects the promise.

It works in current browsers and in Node 22. If your code must also run on older versions, check that it exists first. This check is called feature detection.

1const { promise, resolve } = Promise.withResolvers();2resolve("order ready");3 4promise.then((value) => console.log(value));

Line 1 makes the promise and takes out promise and resolve. Line 2 calls resolve with the value "order ready". No new Promise brackets are needed. Line 4 adds a handler. The handler runs a moment later and prints order ready.

1function waitForClick(button) {2  const { promise, resolve, reject } = Promise.withResolvers();3 4  button.addEventListener("click", () => {5    resolve("button clicked");6  }, { once: true });7 8  return { promise, cancel: () => reject("cancelled") };9}

A real use is waitForClick(button). It makes a promise and fulfills it when the button is clicked. It can also hand out a cancel function that rejects the promise.

A function can fail in two ways:

• It can throw an error right away. This is a synchronous throw: it happens now, before the function returns.
• It can return a promise that rejects later.

Promise.try(fn) handles both the same way. It calls fn right now and gives back a promise for its result. If fn throws right away, that promise rejects. So one .catch handles both kinds of failure.

Promise.try is new. It works in newer browsers and in Node 23, but not in Node 22. So this lesson checks whether it exists. If it doesn't, the lesson uses a small stand-in function instead. A stand-in like this is called a fallback.

1function promiseTry(fn, ...args) {2  if (typeof Promise.try === "function") {3    return Promise.try(fn, ...args);4  }5  return new Promise((resolve) => resolve(fn(...args)));6}7 8promiseTry(readConfig)9  .then((value) => console.log(value))10  .catch((error) => console.log(error.message));

You may also see Promise.resolve().then(fn). It also turns a throw into a rejection. But it doesn't call fn right away. It calls it a moment later, as a microtask: a small job that runs after the current code finishes. Promise.try(fn) calls fn right away.

1function promiseTry(fn) {2  if (typeof Promise.try === "function") return Promise.try(fn);3  return new Promise((resolve) => resolve(fn()));4}5 6function readPrice() {7  console.log("read now");8  return 3;9}10 11promiseTry(readPrice).then((price) => console.log("price " + price));12console.log("after call");

Lines 1 to 4 are the fallback helper. Line 2 uses the real Promise.try if it exists. Line 3 is the fallback: it calls fn inside new Promise, which also turns a throw into a rejection.

Line 11 calls readPrice through the helper. The output is:

1. read now: readPrice runs right away, from line 7.
2. after call: line 12 runs next.
3. price 3: the .then handler runs last, after the current code finishes.

Promise.all gives back an array. When each place in the array means something different, it's easy to mix them up. Look at this code:

1const [alerts, user] = await Promise.all([2  fetchUser(),3  fetchAlerts(),4]);5// Oops: alerts contains the user, and user contains the alerts.

Line 1 takes the two values out of the array by place. The first value goes into alerts, and the second goes into user. But line 2 puts fetchUser() first. So the names are swapped.

A new feature fixes this. It adds two methods, Promise.allKeyed and Promise.allSettledKeyed. You give them an object of promises, and they give back an object with the same property names. Then you read result.user, not the first place in an array.

This feature is a proposal: a planned addition that isn't part of the language yet. Firefox 155 has early, experimental support. Node 22 and most browsers don't have it.

1async function allKeyed(object) {2  const keys = Object.keys(object);3  const values = await Promise.all(keys.map((key) => object[key]));4  return Object.fromEntries(keys.map((key, index) => [key, values[index]]));5}6 7const dashboard = await allKeyed({8  user: fetchUser(),9  stats: fetchStats(),10  alerts: fetchAlerts(),11});

1async function allSettledKeyed(object) {2  const keys = Object.keys(object);3  const results = await Promise.allSettled(keys.map((key) => object[key]));4  return Object.fromEntries(keys.map((key, index) => [key, results[index]]));5}

You can write a small version yourself today:

1async function allKeyed(object) {2  const keys = Object.keys(object);3  const values = await Promise.all(keys.map((key) => object[key]));4  return Object.fromEntries(keys.map((key, index) => [key, values[index]]));5}6 7const dashboard = await allKeyed({8  user: fetchUser(),9  stats: fetchStats(),10  alerts: fetchAlerts(),11});

1. Line 1 defines the helper. It takes an object of promises.
2. Line 2 saves the property names, like ["user", "stats", "alerts"].
3. Line 3 waits for all the values with Promise.all. They come back in the same order as the names.
4. Line 4 puts each name back next to its value and builds a new object.

The helper uses Object.keys, which lists only the text property names. The real feature also handles symbol keys. For most code, text names are all you need.

Where you'll use combinators

The method you pick tells the reader what your code needs:

• Promise.all says: "This page needs every piece."
• Promise.allSettled says: "Show how each one ended."
• Promise.any says: "The first success is enough."
• Promise.race says: "Whatever finishes first decides."

1async function loadDashboard() {2  const [user, widgets, flags] = await Promise.all([3    loadUser(),4    loadWidgets(),5    loadFeatureFlags(),6  ]);7 8  const uploads = await Promise.allSettled(files.map(uploadFile));9  const fastest = await Promise.any(cdnMirrors.map(loadFromMirror));10 11  return { user, widgets, flags, uploads, fastest };12}

• Line 2 needs the user, the widgets, and the feature flags. If one fails, the dashboard can't show.
• Line 8 uploads every file and keeps a report for each one, failed or not.
• Line 9 asks several copies of the same server and takes the first one that answers well.

1const timeout = new Promise((_, reject) => {2  setTimeout(() => reject(new Error("too slow")), 3000);3});4 5const data = await Promise.race([loadData(), timeout]);

Line 1 makes a promise that rejects with "too slow" after 3000 milliseconds, which is 3 seconds. Line 5 races loadData() against it. If the data comes first, data gets it. If the timer comes first, the await throws the "too slow" error.

Common misconceptions

Read each row from left to right: the method, when it fulfills, when it rejects, and what it's good for.

• "Promise.all stops the other promises." It doesn't. It rejects early, but the other work keeps running unless you stop it yourself.
• "The values come back in the order they finish." No. all and allSettled keep input order.
• "allSettled gives me the values." It gives report objects. Check status first, then read value or reason.
• "race means the first success." race means the first result, success or failure. Use any for the first success.
• "New methods work everywhere." Check that withResolvers, Promise.try, and proposals like allKeyed exist before you use them.

Key takeaways

• Promise.all is for "every one must succeed." It keeps input order. It rejects with the reason from the first failure.
• Promise.allSettled is for reports. It waits for every input and gives a report object for each one.
• Promise.race takes the first result, success or failure. Promise.any takes the first success, or rejects with an AggregateError.
• withResolvers and Promise.try are newer. Check that they exist, and use a fallback when they don't.
• allKeyed is a proposal. A small helper built on Object.keys gives you the same idea today.

Final definition: A promise combinator turns many promises into one promise. You pick the one whose waiting rule matches what your code needs.

Up next: Promisification & promise-based APIs.