Promises can be both a blessing and a curse. They were supposed to clean the “callback pyramid of doom”, but instead they can often end up confusing (and I wanted to call that “The callback Temple of Doom”. It doesn’t really make sense in this context, I just like Indiana Jones)

While promises do help, they are a lot more complicated than plain callbacks. With callbacks, you just pass a function and maybe stick another function inside that. But with promises, there’s a lot more.

The chaining can be confusing, as exceptions, normal JS values and promises all affect it differently. Setting more complex flows can also be difficult, as you need to juggle multiple promises and their result values around.

Then there’s the whole topic of error handling. The default behavior with promises is super convenient: Unhandled errors are silently ignored, because apparently the person behind promises hates everyone and wants you to have extra fun debugging times.

But promises are the future. New asynchronous APIs tend to be promise-based. New JavaScript features such as async/await are based on promises as well.

This means the better you know the ins and outs of promises, the better prepared you are for the future – not to mention that promises are very convenient when used well, despite the complexities.

Because of the importance of this, and the questions I sometimes receive which relate to promises, I’ve put together a list of the best promise-related material for you!

Below you’ll find a ton of info on promises, from the basics to super in-depth!





1. Getting started

The promise article by David Walsh is a great primer to get started with. It gives a good overview on what promises are and how they work, with practical examples.

2. Understanding promises in more depth

To get a more in-depth understanding of how promises work, this article on Pony Foo is a great read. It gives more examples of how to use the different Promise-related functions too.

If you’re having trouble understanding how chaining with Promises work, a visualization can be a great help. Here is a tool which can be used to get a graphical representation of how a promise chain works

3. Free book chapters on promises

For a very comprehensive explanation on promises, including many practical examples and even common mistakes to avoid, read the Promises for asynchronous programming chapter of Exploring ES6

Another comprehensive resource with tons of examples is the YDKJS book chapter Async and Performance.

4. Reference material / quick information

For a quick reference, it’s hard to beat MDN. If you need to quickly look up how something works, or get a reference for a function, say to look up its parameters, the MDN promise reference is my go-to.

5. Common mistakes and anti-patterns

There are several common mistakes developers often make with promises. For a great overview of them, along with examples of what to do instead, read Promise Anti-patterns on Tao of Code

6. How do promises really work?

Do you want to know how promises actually work? How do they do what they do? Then read promises in wicked detail, which goes step by step to actually implement promises with plain JavaScript

7. Advanced promise usage

While the standard promise functions can be useful, more complex applications can require something more. The Bluebird library has a ton of useful promise-related functionality which can greatly simplify more complex uses

YDKJS author Kyle Simpson’s Asynquence library is an alternative to promises. It has support for a number of more interesting features, somewhat similar to Bluebird

8. Unit testing promises

And last but not least, when you want to unit test code using promises, read my definitive guide on javascript promises and unit tests

In closing

The above should cover pretty much any imaginable promise-related scenario. Do you have another resource in mind that would be helpful? Leave a comment!