JavaScript Promise API

While synchronous code is easier to follow and debug, async is generally better for performance and flexibility. Why “hold up the show” when you can trigger numerous requests at once and then handle them when each is ready?  Promises are becoming a big part of the JavaScript world, with many new APIs being implemented with the promise philosophy. Let’s take a look at promises, the API, how it’s used!

Promises in the Wild

The XMLHttpRequest API is async but does not use the Promises API.  There are a few native APIs that now use promises, however:

  • Battery API
  • fetch API (XHR’s replacement)
  • ServiceWorker API (post coming soon!)

Promises will only become more prevalent so it’s important that all front-end developers get used to them.  It’s also worth noting that Node.js is another platform for Promises (obviously, as Promise is a core language feature).

Testing promises is probably easier than you think because setTimeout can be used as your async “task”!

Basic Promise Usage

The new Promise() constructor should only be used for legacy async tasks, like usage of setTimeout or XMLHttpRequest. A new Promise is created with the new keyword and the promise provides resolve and reject functions to the provided callback:

It’s up to the developer to manually call resolve or reject within the body of the callback based on the result of their given task. A realistic example would be converting XMLHttpRequest to a promise-based task:

Sometimes you don’t need to complete an async tasks within the promise — if it’s possible that an async action will be taken, however, returning a promise will be best so that you can always count on a promise coming out of a given function. In that case you can simply call Promise.resolve() or Promise.reject() without using the new keyword. For example:

Since a promise is always returned, you can always use the then and catch methods on its return value!


All promise instances get a then method which allows you to react to the promise.  The first then method callback receives the result given to it by the resolve() call:

The then callback is triggered when the promise is resolved.  You can also chain then method callbacks:

Each then receives the result of the previous then‘s return value.

If a promise has already resolved but then is called again, the callback immediately fires. If the promise is rejected and you call then after rejection, the callback is never called.


The catch callback is executed when the promise is rejected:

What you provide to the reject method is up to you. A frequent pattern is sending an Error to the catch:


Think about JavaScript loaders:  there are times when you trigger multiple async interactions but only want to respond when all of them are completed — that’s where Promise.all comes in.  The Promise.all method takes an array of promises and fires one callback once they are all resolved:

An perfect way of thinking about Promise.all is firing off multiple AJAX (via fetch) requests at one time:

You could combine APIs like fetch and the Battery API since they both return promises:

Dealing with rejection is, of course, hard. If any promise is rejected the catch fires for the first rejection:

Promise.all will be super useful as more APIs move toward promises.


Promise.race is an interesting function — instead of waiting for all promises to be resolved or rejected, Promise.race triggers as soon as any promise in the array is resolved or rejected:

A use case could be triggering a request to a primary source and a secondary source (in case the primary or secondary are unavailable).

Get Used to Promises

Promises have been a hot topic for the past few years (or the last 10 years if you were a Dojo Toolkit user) and they’ve gone from a JavaScript framework pattern to a language staple.  It’s probably wise to assume you’ll be seeing most new JavaScript APIs being implemented with a promise-based pattern…

…and that’s a great thing!  Developers are able to avoid callback hell and async interactions can be passed around like any other variable.  Promises take some time getting used to be the tools are (natively) there and now is the time to learn them!