JavaScript Promise API

The Promise class ships several static methods for combining and creating promises. Instead of wiring up multiple .then() chains by hand, you hand an array of promises to one combinator and get a single promise back that settles once the group reaches a defined state.

This page covers the four combinators — Promise.all, Promise.allSettled, Promise.race, and Promise.any — plus the two creation helpers Promise.resolve and Promise.reject. If you are new to promises, start with JavaScript: Promises first.

The examples below use .then()/.catch() so the control flow is explicit. In real code you would usually read the result with async/await.

Choosing the right combinator

The key distinction: Promise.all fast-fails — it rejects the instant any input rejects, even if other promises are still pending. If you instead want to wait for every promise no matter what, use Promise.allSettled.

Utilizing Promise.all for Concurrent Tasks

Promise.all is an essential method for handling multiple promises concurrently. When you need to perform several asynchronous operations and only proceed once all of them have successfully completed, Promise.all is the tool you need.

How to Implement Promise.all

Below is an example demonstrating how to use Promise.all to handle multiple API requests simultaneously:

In this example, Promise.all takes an array of promises and resolves to an array of their results in the same order as the input (not in the order they finished). If any promise rejects, Promise.all immediately rejects with the reason of that first rejection — the results of the others are discarded. See Error handling with promises for how to recover from such failures.

Mastering Promise.allSettled

Unlike Promise.all, the Promise.allSettled method returns a promise that resolves after all the given promises have either resolved or rejected, with an array of objects that each describe the outcome of each promise.

Example of Promise.allSettled

Here's how you can use Promise.allSettled:

Note: Promise.allSettled never rejects. It always resolves with an array of result objects, each containing a status property ('fulfilled' or 'rejected') and either a value or reason property.

This method is particularly useful when you need to ensure that all promises proceed to completion regardless of whether they are fulfilled or rejected.

Implementing Promise.race

Promise.race is another powerful tool that allows handling multiple promises by resolving or rejecting as soon as one of the promises in the iterable resolves or rejects.

How to Use Promise.race

Below is a practical application of Promise.race:

This method is ideal for scenarios where you need the fastest result among multiple asynchronous operations — for example, racing a request against a timeout promise. Note that race settles on the first promise to settle, whether it fulfills or rejects.

Getting the First Success with Promise.any

Promise.any is the optimistic counterpart of Promise.race. It ignores rejections and resolves with the value of the first promise to fulfill. It only rejects if every promise rejects, in which case it throws an AggregateError whose .errors property holds all the individual reasons.

How to Use Promise.any

Use Promise.any when you have several sources for the same data (e.g. mirror servers) and you only care about the first one that succeeds.

Creating Promises with resolve and reject

Promise.resolve(value) and Promise.reject(reason) are shortcuts for building an already-settled promise without the new Promise(executor) boilerplate.

• Promise.resolve(value) returns a promise that is already fulfilled with value. If value is itself a thenable, it is "adopted" and followed.
• Promise.reject(reason) returns a promise that is already rejected with reason.

These helpers are commonly used to return a cached value from an otherwise async function, or to start a .then() chain.

Creating a Polyfill for Promise.allSettled

Not all environments support Promise.allSettled natively. Therefore, implementing a polyfill can ensure compatibility across different JavaScript environments.

Polyfill for Promise.allSettled

Here’s how you can create a simple polyfill:

This polyfill provides a basic functionality where each promise is individually handled and resolved to its respective outcome, ensuring the allSettled behavior is mimicked effectively.

By integrating these advanced promise techniques and understanding the underlying mechanics of polyfills, you can elevate your JavaScript code to new heights. These methods not only enhance code reliability but also offer refined control over asynchronous operations, paving the way for more robust web applications.

Practice