Broken Post? → Let me know

Photo by Ryan Franco on Unsplash

What’s new in JavaScript (Google I/O ’19) on May 8, 2019 showed what's coming/available for static Promise combinator methods, Promise.allSettled and Promise.any.

There are already two methods available in modern browsers, Promise.all and Promise.race.

Let's take a look at differences and how each method works.

🚀 Prerequisite

🔆 Promise Definition

I will skip on what a promise is and jump straight into static methods and will discuss differences.

A gist is that, a promise is JavaScript's way of promising you that a work will be done (or might fail if the work could not be completed).

If you are familiar with C#, it's analogous Task class.

For more info, refer to following documentations.

🔆 Promise State Definitions

Fulfilled - When a promise is resolved successfully.

- When a promise is resolved successfully. Rejected - When a promise failed.

- When a promise failed. Pending - When a promise is "neither fulfilled nor rejected".

- When a promise is "neither fulfilled nor rejected". Settled - Not really a state but an umbrella term to describe that a promise is either fulfilled or rejected. This term will be used to describe characteristics of new methods later.

- Not really a state but an umbrella term to describe that a promise is either fulfilled or rejected.

For more detailed explanation of states & fates, please refer to States and Fates.

There are other static Promise methods such as Promise.reject, Promise.resolve but I will cover only "combinator" methods, which takes in an iterable object as an argument.

🚀 Differences

Let's first take a look at difference between existing & new combinator methods.

🔅 Promise.all vs. Promise.allSettled

Both accepts an iterable object but

Promise.all rejects as soon as a promise within the iterable object rejected.

rejects as soon as a promise within the iterable object rejected. Promise.allSettled resolves regardless of rejected promise(s) within the iterable object.

🔅 Promise.race vs. Promise.any

Both accepts an iterable object but

Promise.race short-circuits on the first settled (fulfilled or rejected) promise within the iterable object.

short-circuits on the first settled (fulfilled or rejected) promise within the iterable object. Promise.any short-circuits on the first fulfilled promise and continues to resolve regardless of rejected promises unless all within the iterable object reject.

🚀 Comparison Table

Now let's take a look at existing/upcoming combinator methods.

Short-circuit? Short-circuits on? Fulfilled on? Rejected on? Promise.all ✅ First rejected promise All promise fulfilled First rejected promise Promise.allSettled ❌ N/A Always N/A Promise.race ✅ First settled First promise fulfilled First rejected promise Promise.any ✅ First fulfilled First promise fulfilled All rejected promises view raw Comparison Table.md hosted with ❤ by GitHub

Now let's move on to learn more about each method.

Note that all "Characteristics" are taken from TC39 proposal README.

🚀 Promise.all

What is this? Resolve all promises passed as an iterable object.

Resolve all promises passed as an iterable object. Idiom - One bad 🍏 spoils the bunch ("all").

- One bad 🍏 spoils the bunch ("all"). Characteristic - short-circuits when an input value is rejected

🔆 Example

When Promise.all fulfilled( promisesWithoutReject ), all apples are returned.

The latter example using promisesWithOneReject shows that one rejected promise results in rejecting all promises.

🚀 Promise.allSettled

What is this? all promises regardless of settled (fulfilled/rejected) status.

all promises regardless of settled (fulfilled/rejected) status. Idiom - Let's "wait and see" 🤔.

- Let's "wait and see" 🤔. Characteristic - Does not short-circuit unlike Promise.all/race

- Does not short-circuit unlike Promise.all/race Note - Available in Chrome 76.

🔆 Example

Regardless of settled (fulfilled or rejected) state, all promises resolve without short-circuiting to catch .

To differentiate if resolved values were successful, they are returned as an array of objects of following shape.

Fulfilled promise is returned as {status: 'fulfilled', value}

Rejected promise is returned as {status: 'rejected', reason}

🚀 Promise.race

What is this? The first fulfilled promise or reject the whole promise when even one promise rejects.

The first fulfilled promise or reject the whole promise when even one promise rejects. Idiom - A race between Good 😇 (Fulfilled) and Evil 😈 (Rejected) Not really an idiom though 😅

- A race between Good 😇 (Fulfilled) and Evil 😈 (Rejected) Characteristic - Short-circuits when an input value is settled

🔆 Example

In promiseWillFulfill example, the first promise fulfilled within 1 millisecond and thus the humanity survived.

But the second example using promiseWillReject had a promise rejecting in 1 millisecond and thus the humanity is doomed.

And the last example ( promisesWithOUTReject ) fulfilled without rejection thus the first fulfilled promise value of "

three" was returned.

From these examples, you can see that the first settled state (fulfilled or reject) short circuited the promise.

🚀 Promise.any

What is this? Returns the first fulfilled promise regardless of other rejected promises. If all promises reject, then reject by providing errors for all rejects.

Returns the first fulfilled promise regardless of other rejected promises. If all promises reject, then reject by providing errors for all rejects. Idiom - All's well that ends well.

- All's well that ends well. Characteristic - Short-circuits when an input value is fulfilled.

- Short-circuits when an input value is fulfilled. Note - Not yet implemented in any browsers and it is in Stage 1.

🔆 Example

First example has promises that rejects right away but did not short-circuit because of a fulfilled promise, thus you win at life.

Second example has promises resolving after a certain period. The first fulfilled promise was resolved after a series of rejects but didn't short-circuit. And you were able to get a job.

When all promises reject, then that's when Promise.any rejects and you didn't get any job offers.

👋 Conclusion

How I understood was that the new Promise.allSettled/any are introduced for Promise to try its best to resolve promises to fulfill unlike existing ones that fails on first encounter of reject.

Promise.all & Promise.race has been available in modern browsers (this exclude IE ;p) and Promise.allSettled will be available in Chrome 76.

Promise.any is still in stage 1 and not available in any browsers (but available in Bluebird or using polyfills - for the demo I used promise-any NPM library for demo.)

I'd love to hear where you would (have) use(d) each method to solve a problem.

And would you please kindly let me know if you find any mistakes and/or how I can improve the example?