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 – JavaScript on MDN
- JavaScript Promises: an Introduction on Google Developers
🔆 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 😇](https://s.w.org/images/core/emoji/12.0.0-1/72x72/1f607.png) (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)
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 withPromise.all()
. It usually happens anytime there's a need to gather finalized data AFTER running async methods from an array.Thank you, vulpz 😃
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 🤔)Possibly bad form, but I went the route of "misusing"
resolve
andreject
. If there was a bad case that had issues, yet needed to be caught byPromise.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!
Getting things done FTW~
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. :)
I think that they correspond to the example order....
It is because of setTimeout(....
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.
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.
Good post, looking forward to seeing these implemented in all browser vendors
Thanks.
These methods will rid the need for boilterplate codes for sure :)
This was an awesome article, 👍🏼 really helped understand the different static methods of a promise.
Thanks for the kind words, David. Glad that you liked it :)
So, what is the purpose of extractApples method? It seem to be be defined, but never used?
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" :)