Understanding JavaScript Promises
Nicholas C. Zakas
This book is for sale at http://leanpub.com/understanding-javascript-promises
This version was published on 2023-01-16
This is a Leanpub book. Leanpub empowers authors and publishers with the Lean
Publishing process. Lean Publishing is the act of publishing an in-progress ebook
using lightweight tools and many iterations to get reader feedback, pivot until you
have the right book and build traction once you do.
© 2020 - 2023 Nicholas C. Zakas
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1. Promise Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
The Promise Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Creating New (Unsettled) Promises . . . . . . . . . . . . . . . . . . . . . . . . 13
Creating Settled Promises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2. Chaining Promises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Catching Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Using finally() in Promise Chains . . . . . . . . . . . . . . . . . . . . . . . . . 24
Returning Values in Promise Chains . . . . . . . . . . . . . . . . . . . . . . . 28
Returning Promises in Promise Chains . . . . . . . . . . . . . . . . . . . . . . 29
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3. Working with Multiple Promises . . . . . . . . . . . . . . . . . . . . . . . . . 36
The Promise.all() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
The Promise.allSettled() Method . . . . . . . . . . . . . . . . . . . . . . . . . . 44
The Promise.any() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The Promise.race() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4. Async Functions and Await Expressions . . . . . . . . . . . . . . . . . . . . 59
Defining Async Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
CONTENTS
What Makes Async Functions Different . . . . . . . . . . . . . . . . . . . . . 60
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5. Unhandled Rejection Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Detecting Unhandled Rejections . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Web Browser Unhandled Rejection Tracking . . . . . . . . . . . . . . . . . . 75
Node.js Unhandled Rejection Tracking . . . . . . . . . . . . . . . . . . . . . . 80
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Final Thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Download the Extras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Support the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Help and Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Follow the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Introduction
One of the most powerful aspects of JavaScript is how easily it handles asynchronous
programming. As a language created for the web, JavaScript needed to respond to
user interactions such as clicks and key presses from the beginning, and so event
handlers such as onclick were created. Event handlers allowed developers to specify
a function to execute at some later point in time in reaction to an event.
Node.js further popularized asynchronous programming in JavaScript by using
callback functions in addition to events. As more and more programs started
using asynchronous programming, events and callbacks were no longer sufficient
to support everything developers wanted to do. Promises are the solution to this
problem.
Promises are another option for asynchronous programming, and they work like
futures and deferreds do in other languages. A promise specifies some code to be
executed later (as with events and callbacks) and also explicitly indicates whether
the code succeeded or failed at its job. You can chain promises together based on
success or failure in ways that make your code easier to understand and debug.
About This Book
The goal of this book is to explain how JavaScript promises work while giving
practical examples of when to use them. All new asynchronous JavaScript APIs
will be built with promises going forward, and so promises are a central concept
to understanding JavaScript as a whole. My hope is that this book will give you the
information you need to successfully use promises in your projects.
Browser, Node.js, and Deno Compatibility
There are multiple JavaScript runtimes that you may use, such as web browsers,
Node.js, and Deno. This book doesn’t attempt to address differences between these