Dmitri Pavlutin
I help developers understand JavaScript and React

How to Use Promise.allSettled()

Promise.allSettled(promises) is a helper function that runs promises in parallel and aggregates the settled statuses (either fulfilled or rejected) into a result array.

Let’s see how Promise.allSettled() works.

1. Promise.allSettled()

Promise.allSettled() is useful to perform independent async operations in parallel, and collect the result of these operations.

The function accepts an array (or generally an iterable) of promises as an argument:

const statusesPromise = Promise.allSettled(promises);

When all input promises are being fulfilled or rejected, in parallel, statusesPromise resolves to an array having their statuses:

  1. { status: 'fulfilled', value: value } — if the corresponding promise has fulfilled
  2. Or { status: 'rejected', reason: reason } — if the corresponding promise has rejected

Promise.allSettled() in JavaScript

After all input promises are being resolved, you can extract their statuses using a then-able syntax:

statusesPromise.then(statuses => {
 statuses; // [{ status: '...', value: '...' }, ...]
});

or using an async/await syntax:

const statuses = await statusesPromise;

statuses; // [{ status: '...', value: '...' }, ...]

The promise returned by Promise.allSettled() always fulfills with an array of statuses, no matter if some (or even all!) input promises are rejected.

2. Fetching fruits and vegetables

Before diving into Promise.allSettle(), let’s define 2 simple helper functions.

First, resolveTimeout(value, delay) — returns a promise that fulfills with value after passing delay time:

function resolveTimeout(value, delay) {
  return new Promise(
    resolve => setTimeout(() => resolve(value), delay)
  );
}

Second, rejectTimeout(reason, delay) — returns a promise that rejects with reason after passing delay time:

function rejectTimeout(reason, delay) {
  return new Promise(
    (r, reject) => setTimeout(() => reject(reason), delay)
  );
}

Let’s use these helper functions to experiment on Promise.allSettled().

2.1 All promises fulfilled

Let’s access in parallel the vegetables and fruits available at the local grocerry store. Accessing each list is an asynchornous operation:

const statusesPromise = Promise.allSettled([
  resolveTimeout(['potatoes', 'tomatoes'], 1000),  resolveTimeout(['oranges', 'apples'], 1000)]);

// wait...
const statuses = await statusesPromise;

// after 1 second
console.log(statuses); 
// [
//   { status: 'fulfilled', value: ['potatoes', 'tomatoes'] },
//   { status: 'fulfilled', value: ['oranges', 'apples'] }
// ]

Try the demo.

Promise.allSettled([...]) returns a promise statusesPromise that resolves in 1 second, right after vegetables and fruits were resolved, in parallel.

The promise statusesPromise resolves to an array containing the statuses:

  1. The first item of the array contains the fulfilled status with vegetables: { status: 'fulfilled', value: ['potatoes', 'tomatoes'] }
  2. Same way, the second item is the fulfilled status of fruits: { status: 'fulfilled', value: ['oranges', 'apples'] }.

2.2 One promise rejected

Imagine there are no more fruits at the grocery. In such a case, let’s reject the fruits’ promise.

How would Promise.allSettled() would work in such a case?

const statusesPromise = Promise.allSettled([
  resolveTimeout(['potatoes', 'tomatoes'], 1000),
  rejectTimeout(new Error('Out of fruits!'), 1000)]);

// wait...
const statuses = await statusesPromise;

// after 1 second
console.log(statuses); 
// [
//   { status: 'fulfilled', value: ['potatoes', 'tomatoes'] },
//   { status: 'rejected', reason: Error('Out of fruits!') }
// ]

Try the demo.

The promise returned by Promise.allSettled([...]) resolves to an array of statuses after 1 second:

  1. The first item of the array, since vegetables promise resolved successfully, is { status: 'fulfilled', value: ['potatoes', 'tomatoes'] }
  2. The second item, because fruits promise rejected with an error, is a rejection status: { status: 'rejected', reason: Error('Out of fruits') }.

Even though the second promise in the input array is rejected, the statusesPromise still resolves successfully with an array of statuses.

2.3 All promises rejected

What if the grocerry is out of both vegetables and fruits? In such case both promises reject:

const statusesPromise = Promise.allSettled([
  rejectTimeout(new Error('Out of vegetables!'), 1000),  rejectTimeout(new Error('Out of fruits!'), 1000)]);

// wait...
const statuses = await statusesPromise;

// after 1 second
console.log(statuses); 
// [
//   { status: 'rejected', reason: Error('Out of vegetables!')  },
//   { status: 'rejected', reason: Error('Out of fruits!') }
// ]

Try the demo.

In such a case statusesPromise still resolves successfully to an array of statuses. However, the array contains the statuses of rejected promises.

3. Conclusion

Promise.allSettled(promises) lets you run promises in parallel and collect the statuses (either fulfilled or reject) into an aggregate array.

Promise.allSettled(...) works great when you need to perform parallel and independent asynchronous operations and collect all the results even if some async operations could fail.

Challenge: do you know cases when Promise.allSettled() returns a rejected promise? If so, please write a comment below!

Like the post? Please share!

Quality posts into your inbox

I regularly publish posts containing:

  • Important JavaScript concepts explained in simple words
  • Overview of new JavaScript features
  • How to use TypeScript and typing
  • Software design and good coding practices

Subscribe to my newsletter to get them right into your inbox.

Join 4172 other subscribers.

About Dmitri Pavlutin

Software developer, tech writer and coach. My daily routine consists of (but not limited to) drinking coffee, coding, writing, coaching, overcoming boredom 😉.
Email addressTwitter profileFacebook pageLinkedIn profile