Implementing Promise barriers with Promise.all()

The Promise.all() method accepts an iterable collection of promises (for example, an array of Promise objects or an object with a number of promise properties), and it will attempt to resolve all of them as a single aggregate promise. The parameter of the aggregate resolved handler will be an array or object that matches the resolved values of the contained promises:

var outerResolveA, outerResolveB;   const promiseA = new Promise((resolve, reject) => {     outerResolveA = resolve;   });   const promiseB = new Promise((resolve, reject) => {     outerResolveB = resolve;   });      const multiPromiseAB = Promise.all([promiseA, promiseB])     .then((values) => console.log(values));      outerResolveA(123);   outerResolveB(456);      // [123, 456]   

If any of the promises in the collection are rejected, the aggregate promise will be rejected. The parameter of the aggregate rejected handler will be the returned value of the rejected promise:

var outerResolveC, outerRejectD;   const promiseC = new Promise((resolve, reject) => {     outerResolveC = resolve;   });   const promiseD = new Promise((resolve, reject) => {     outerRejectD = reject;   });      const multiPromiseCD = Promise.all([promiseC, promiseD])     .then(       values => console.log(values),       rejectedValue => console.error(rejectedValue));      // resolve a collection promise, no handler execution   outerResolveC(123);   // reject a collection promise, rejection handler executes   outerRejectD(456);      // (error) 456   

As demonstrated, the aggregate promise will reach the final state only when all of the enclosed promises are resolved, or when a single enclosed promise is rejected. Using this type of promise is useful when the collection of promises do not need to reason about one another, but collective completion is the only metric of success for the group.

In the case of a contained rejection, the aggregate promise will not wait for the remaining promises to complete, but those promises will not be prevented from reaching their final state. Only the first promise to be rejected will be able to pass rejection data to the aggregate promise rejection handler.

Promise.all() is in many ways extremely similar to an operating-system-level process synchronization barrier. A process barrier is a common point in the thread instruction execution that a collection of processes will reach independently and at different times, and no process can proceed further until all have reached this point. In the same way, Promise.all() will not proceed unless either all of the contained promises have been resolved—reached the barrier—or a single contained rejection will prevent that state from ever being achieved, in which case the failover handler logic will take over.

Since Promise.all() allows you to have a recombination of promises, it also allows your application's Promise chains to become a directed acyclic graph (DAG). The following is an example of a promise progression graph that diverges first and converges later:

This level of complexity is uncommon, but it is available for use should your application require it.