Promise combinators

Many promises, one plan

A single promise is a value for work that finishes later. Real pages rarely wait for just one thing. A dashboard may need the user, feature flags, notifications, and chart data. A file uploader may start many uploads. A CDN loader may ask three mirrors and keep the first good answer.

Promise combinators are static methods that take an iterable of promises or values and return one new promise that describes the group. This lesson builds on Promises and Microtasks in depth. The previous lessons by title, Promise chaining and Error handling with promises, explain how values and rejections travel once the group promise settles.

That is the pattern for the whole lesson: each method answers a different group question. Do you need every value, every outcome, the first outcome, or the first success?

Promise.all(iterable) accepts any iterable. Each item can be a promise, a thenable, or a plain value. Plain values count as already fulfilled. If the iterable is empty, Promise.all([]) fulfills with an empty array.

The success result is an array in input order, not completion order. That matters when one promise is slow but appears first in the array. Try the kitchen race track, then step through the fail-fast replay.

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 settlement wins10Promise.any(tasks);        // first fulfillment wins

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(iterable) waits for everything and always fulfills because of the inputs. Each result is an object: either { status: "fulfilled", value } or { status: "rejected", reason }. Use it when failures are data you still need to show, such as upload reports or test results.

Promise.race(iterable) settles as soon as the first input settles. If the fastest promise fulfills, the race fulfills. If the fastest promise rejects, the race rejects. An empty race, Promise.race([]), stays pending forever because there is no first settlement.

Promise.any(iterable) waits for the first fulfillment. Rejections are ignored until every input has rejected. If that happens, the returned promise rejects with an AggregateError, and its .errors array is in input order. Promise.any([]) rejects immediately with an AggregateError because there can never be a fulfillment.

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

Sometimes the code that creates a promise is not the same code that knows when to settle it. Promise.withResolvers() returns an object with promise, resolve, and reject. It is a Baseline 2024/newer-environment feature; Node 22 includes it, but feature detection is still healthy when you support older browsers.

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 realistic use is waitForClick(button): create a promise, resolve it when a real click happens, and optionally reject it if the wait is canceled.

Promise.try(fn, ...args) is a safety net for code that might fail before it returns a promise. It calls fn now, wraps the return value in a promise, and turns a synchronous throw into a rejection. It is an ES2025/newer-browser feature and is not in Node 22, so this lesson uses a small fallback in tests.

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));

Compare it with Promise.resolve().then(fn). That pattern also turns a thrown error into a rejection, but it starts fn later in a microtask. Promise.try(fn) starts fn immediately.

Arrays are easy to mix up when each position means something different. The TC39 proposal informally known as “Await dictionary of Promises” adds Promise.allKeyed and Promise.allSettledKeyed. It is Stage 3 and no engine ships it yet. The proposal awaits all own enumerable keys, including symbols. The helper below is intentionally smaller and uses Object.keys, so it handles string keys.

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

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}

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});

Where you’ll use combinators

Combinators make async intent readable. A loader using Promise.all says “this page needs every piece.” A report using allSettled says “show every outcome.” A CDN loader using any says “first success wins.” A timeout preview using race says “the first settlement 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}

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

Common misconceptions

• “Promise.all cancels the rest.” It does not. It rejects early, but other work keeps running unless you cancel it yourself.
• “Results come back in finish order.” all and allSettled preserve input order.
• “allSettled gives me values directly.” It gives status objects. Check status before reading value or reason.
• “race means first success.” race means first settlement. Use any for first success.
• “New APIs are everywhere.” Feature-detect withResolvers, Promise.try, and proposals such as allKeyed.

Key takeaways

• Promise.all is for “all must succeed.” It preserves input order and rejects with the first rejection reason.
• Promise.allSettled is for reports. It waits for every input and gives status objects.
• Promise.race is first settlement; Promise.any is first fulfillment or AggregateError.
• withResolvers and Promise.try are newer APIs, so feature-detect and use fallbacks when needed.
• allKeyed is a Stage 3 proposal; a small Object.keys helper can teach the pattern today.

Final definition: Promise combinators turn many promised outcomes into one promise whose rules match the way your feature wants to wait.

Up next: Promisification & promise-based APIs.