How to Use Promise.allSettled in Node.js: Syntax and Examples

In Node.js, Promise.allSettled takes an array of promises and returns a new promise that resolves when all input promises have settled, either fulfilled or rejected. It provides an array of objects describing the outcome of each promise, allowing you to handle all results without failing fast.

Syntax

The Promise.allSettled method accepts an iterable (usually an array) of promises and returns a single promise. This returned promise resolves with an array of objects, each describing the outcome of the corresponding input promise.

• Input: An array of promises.
• Output: A promise that resolves to an array of result objects.
• Result object: Each object has a status property ('fulfilled' or 'rejected'). If fulfilled, it has a value property; if rejected, it has a reason property.

javascript

Promise.allSettled(iterableOfPromises).then((results) => {
  results.forEach((result) => {
    if (result.status === 'fulfilled') {
      console.log('Value:', result.value);
    } else {
      console.log('Reason:', result.reason);
    }
  });
});

Example

This example shows how Promise.allSettled waits for all promises to finish, then logs each result whether it succeeded or failed.

javascript

const promise1 = Promise.resolve('Success 1');
const promise2 = Promise.reject(new Error('Error 2'));
const promise3 = new Promise((resolve) => setTimeout(() => resolve('Success 3'), 100));

Promise.allSettled([promise1, promise2, promise3])
  .then((results) => {
    results.forEach((result, index) => {
      if (result.status === 'fulfilled') {
        console.log(`Promise ${index + 1} fulfilled with:`, result.value);
      } else {
        console.log(`Promise ${index + 1} rejected with:`, result.reason);
      }
    });
  });

Output

Promise 1 fulfilled with: Success 1
Promise 2 rejected with: Error: Error 2
Promise 3 fulfilled with: Success 3

Common Pitfalls

One common mistake is using Promise.all when you want to handle all results regardless of failure. Promise.all rejects immediately on the first failure, while Promise.allSettled waits for all promises.

Another pitfall is not checking the status property of each result, which can cause errors if you assume all promises succeeded.

javascript

const p1 = Promise.resolve('OK');
const p2 = Promise.reject(new Error('Fail'));

// Wrong: Using Promise.all will reject immediately
Promise.all([p1, p2])
  .then(results => console.log('All succeeded:', results))
  .catch(error => console.log('Promise.all rejected:', error));

// Right: Using Promise.allSettled to get all results
Promise.allSettled([p1, p2])
  .then(results => {
    results.forEach(r => {
      if (r.status === 'fulfilled') {
        console.log('Fulfilled:', r.value);
      } else {
        console.log('Rejected:', r.reason);
      }
    });
  });

Output

Promise.all rejected: Error: Fail
Fulfilled: OK
Rejected: Error: Fail

Quick Reference

Feature	Description
Input	An array or iterable of promises
Output	A promise resolving to an array of result objects
Result Object	Has 'status' ('fulfilled' or 'rejected') and 'value' or 'reason'
Use Case	When you want to wait for all promises regardless of success or failure
Node.js Support	Available since Node.js 12.9.0

Key Takeaways

Use Promise.allSettled to wait for all promises to finish without failing fast.

Check each result's status property to handle fulfilled and rejected promises properly.

Promise.allSettled returns an array of objects describing each promise's outcome.

It is supported in Node.js starting from version 12.9.0.

Avoid using Promise.all if you need to handle all results regardless of errors.