DEV Community

Cover image for Promise.race vs. Promise.any And Promise.all vs. Promise.allSettled
Sung M. Kim
Sung M. Kim

Posted on • Originally published at on

Promise.race vs. Promise.any And Promise.all vs. Promise.allSettled

                    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.
  • Rejected – When a promise failed.
  • Pending – 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.

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.
  • 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.
  • 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.

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.
  • Idiom – 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.
  • Idiom – Let’s “wait and see” 🤔.
  • Characteristic – 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.
  • Idiom – A race between Good 😇]( (Fulfilled) and Evil ![😈 (Rejected)
    • Not really an idiom though 😅
  • 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.
  • Idiom – All’s well that ends well.
  • Characteristic – 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?

The post Promise.race vs. Promise.any And Promise.all vs. Promise.allSettled appeared first on Sung's Technical Blog.

Top comments (14)

vulpcod3z profile image

Great post and explanation! I personally have dreaded not having an alternative to Promise.allSettled() as it has required me to rewrite much of my applications to still work with Promise.all(). It usually happens anytime there's a need to gather finalized data AFTER running async methods from an array.

dance2die profile image
Sung M. Kim

Thank you, vulpz 😃

rewrite much of my applications to still work with Promise.all()

How did you get around the issue of current short-circuit behavior of .all()? (write a custom .allSettled or used many try/catch blocks? Those are only two I can think of 🤔)

vulpcod3z profile image

Possibly bad form, but I went the route of "misusing" resolve and reject. If there was a bad case that had issues, yet needed to be caught by Promise.all(), I returned an object that used the try/catch but searched for a specific flag.

Not the most efficient, but it worked and was easier to implement than rewriting the majority of the project!

Thread Thread
dance2die profile image
Sung M. Kim

Getting things done FTW~

bingocaller profile image
Jesper N. Jakobsen

Great article! I wasn't even aware of the new Promise features but you did a good job of explaining them.
Also, it looks like you need to swap line 2 and 3 in your Promise.any example output gist so they correspond to the example order. :)

mayassalman profile image
mayas salman

I think that they correspond to the example order....
It is because of setTimeout(....

bingocaller profile image
Jesper N. Jakobsen

I agree that they correspond to what output you would get from the code (because of setTimeout()), but I don't agree that they correspond to the example order.
Maybe what I should have said was that to make the example and output more readable, one would swap example 2 and 3. That way the output Gist corresponds to the example order and the actual output of the code.

Thread Thread
dance2die profile image
Sung M. Kim • Edited

Thanks Jesper for the suggestion.
I've updated the "output" with comments.

The reason I left the order as it was because I initially expected people to "copy/paste" the code and see the result.
(as opposed to copy/paste each example one at a time)


Behold the power of Gist, now all my x-posts are updated too 😀

I will take notes of your suggestion when I post any types of examples next time.

iammpp94 profile image

Good post, looking forward to seeing these implemented in all browser vendors

dance2die profile image
Sung M. Kim

These methods will rid the need for boilterplate codes for sure :)

wormss profile image

So, what is the purpose of extractApples method? It seem to be be defined, but never used?

dance2die profile image
Sung M. Kim

Thank you @wormss for catching the vestigial code and I apologize for getting back late.

I removed extractApples from the code snippet as it's "never used" :)

davidokonji profile image
David Okonji

This was an awesome article, 👍🏼 really helped understand the different static methods of a promise.

dance2die profile image
Sung M. Kim

Thanks for the kind words, David. Glad that you liked it :)