Module 9 · Promises

Promise.allSettled

Intermediate12m read9m practice21m total

PromisesCombinatorsPartial FailureReporting

Introduction

Promise.allSettled(iterable) waits for every input to finish, regardless of success or failure. It never rejects because one input rejected. Instead, it fulfils with an array of result objects: { status: 'fulfilled', value } or { status: 'rejected', reason }.

Why This Matters

Real systems often need partial success: upload five files and report which failed, query optional services, or run validations and show every error. Promise.allSettled is the combinator for complete reporting without fail-fast behavior.

Theory

Exact semantics

Promise.allSettled accepts an iterable of values, promises, or thenables. It waits until every input is settled, meaning every input is either fulfilled or rejected.

The returned promise fulfils with an array in input order. Each element has one of two shapes:

Input outcome	Result object
Fulfilled with value	`{ status: 'fulfilled', value: value }`
Rejected with reason	`{ status: 'rejected', reason: reason }`

It does not reject merely because an input rejected. Empty input fulfils with [].

Combinator comparison

Combinator	Fulfils when	Rejects when	Result shape	Typical use
`Promise.all`	Every input fulfils	First input rejects	Array of values in input order	All-or-nothing parallel work
`Promise.any`	First input fulfils	Every input rejects	First fulfilled value or `AggregateError`	Redundant sources, fastest success
`Promise.allSettled`	Every input settles	Never because of input rejection	Array of status objects in input order	Partial success reporting
`Promise.race`	First input fulfils if it settles first	First input rejects if it settles first	First settled value or reason	Timeouts, first signal wins

Why not just catch each promise?

You can emulate allSettled by mapping each input to a promise that catches and returns a status object. The built-in version gives that pattern a standard shape and avoids accidentally missing a catch.

When to use it

Use it when you need a complete audit of outcomes and one failure should not hide other results. Do not use it when a single failure should stop the operation; Promise.all communicates that all-or-nothing contract better.

Visual Diagrams

Collect every outcome

inputs: [ A, B, C ]
A fulfils
B rejects
C fulfils

Promise.allSettled waits for A, B, and C:
[
  fulfilled with A value,
  rejected with B reason,
  fulfilled with C value
]

The combined promise fulfils after every input has settled.

Code Examples

Report successes and failures together

No individual rejection escapes; every outcome becomes data.

Loading…

Partition settled results

A common production pattern is separating fulfilled values from rejection reasons for UI reporting.

Loading…

Playground

Loading editor…

Console

Press Run to execute the code and see output here.

Output Prediction

Predict the output #1

javascript

1function item(label, ms, shouldFulfill) {
2  return new Promise(function (resolve, reject) {
3    setTimeout(function () {
4      console.log('done ' + label);
5      if (shouldFulfill) {
6        resolve(label);
7      } else {
8        reject(label);
9      }
10    }, ms);
11  });
12}
13 
14Promise.allSettled([
15  item('A', 20, true),
16  item('B', 10, false),
17]).then(function (results) {
18  console.log(results[0].status + ':' + results[0].value);
19  console.log(results[1].status + ':' + results[1].reason);
20});
21 
22console.log('start');

Predict the output #2

javascript

1Promise.allSettled([Promise.resolve(1), Promise.reject(2), 3])
2  .then(function (results) {
3    console.log(results.map(function (result) {
4      return result.status;
5    }).join(','));
6  });
7 
8console.log('sync');

Coding Exercises

Implement a mini Promise.allSettled

Medium

Implement promiseAllSettled(iterable): accept values or promises, wait for every input to settle, and fulfil with result objects in input order. It should not reject because an input promise rejects.

Interview Questions

1When would you choose `Promise.allSettled` over `Promise.all`?

Use Promise.allSettled when you need every outcome and partial failure is acceptable or must be reported. Promise.all is all-or-nothing and rejects on the first failure. allSettled waits for all inputs and returns status objects in input order.

Asked at:MicrosoftAmazonAtlassian

Follow-ups

What is the shape of each result object?
Does `allSettled` preserve input order?

2Does `Promise.allSettled` ever reject?

It does not reject because an input promise rejects; those rejections become { status: 'rejected', reason } result objects. In normal usage it fulfils with an array after every input settles. Edge cases like a bad iterable can still reject before normal input observation.

Quiz

1. What does `Promise.allSettled` return when one input rejects?

2. Which property exists on a fulfilled `allSettled` result object?

Summary

`Promise.allSettled` waits for every input to fulfil or reject.
It fulfils with status objects in input order and does not reject because an input failed.
Fulfilled entries have `value`; rejected entries have `reason`.
Use it for partial success, reporting, dashboards, and bulk operations.

Cheat Sheet

Use when: you need every outcome.

Settles: after all inputs settle.

Fulfil value: array in input order.

Shapes: { status: 'fulfilled', value } or { status: 'rejected', reason }.

Rejects on input failure: no.

Empty: fulfils with [].