Andrew.

Promises in Node: An alternative to callbacks

Promises are a compelling alternative to callbacks when dealing with asynchronous code. Unfortunately, promises can be confusing and perhaps you’ve written them off. However, significant work has been done to bring out the essential beauty of promises in a way that is interoperable and verifiable. The result is Promises/A+, a specification that has made its way into ES6 JavaScript as well as multiple third-party libraries.

So what are promises and what do they offer Node developers?

Promises in the abstract

First we’ll talk about the behavior of promises: What are they and how can they be useful? Then we’ll discuss how to create and use promises.

So what is a promise? Let’s look at a definition:

A promise is an abstraction for asynchronous programming. It’s an object that proxies for the return value or the exception thrown by a function that has to do some asynchronous processing. – Kris Kowal on JSJ

Callbacks are the simplest possible mechanism for asynchronous code in JavaScript. Unfortunately, raw callbacks sacrifice the control flow, exception handling, and function semantics familiar from synchronous code. Promises provide a way to get those things back.

The core component of a promise object is its then method. The then method is how we get the return value (known as the fulfillment value) or the exception thrown (known as the rejection reason) from an asynchronous operation. then takes two optional callbacks as arguments, which we’ll call onFulfilled and onRejected:

var promise = doSomethingAync()
promise.then(onFulfilled, onRejected)

onFulfilled and onRejected are called when the promise is resolved (the asynchronous processing has completed). Only one will ever be triggered since only one resolution is possible.

Callbacks to promises

Given this basic knowledge of promises, let’s take a look at a familiar asynchronous Node callback:

If our readFile function returned a promise, we would write the same logic as:

var promise = readFile()
promise.then(console.log, consoler.error)

At first glance, it looks like just the aesthetics changed. However, we now have access to a value representing the asynchronous operation (the promise). We can pass the promise around and anyone with access to the promise can consume it using thenregardless if the asynchronous operation has completed or not. We also have guarantees that the result of the asynchronous operation won’t change somehow, as the promise will only be resolved once (either fulfilled or rejected).

Promises and synchronous functions

Promises model synchronous functions in a number of ways. One such way is using return for continuation instead of calling another function. The previous examples returned readAnotherFile() to signal what to do after readFile() was done.

If you return a promise, it will signal the next then when the asynchronous operation completes. You can also return any other value and the next onFulfilled will be passed the value as an argument:

Error handling in promises

In addition to return, you also can use the throw keyword and try/catch semantics. This may be one of the most powerful features of promises. For example, consider the following synchronous code:

try {
doThis()
doThat()
} catch (err) {
console.error(err)
}

In this example, if doThis() or doThat() would throw an error, we would catch and log the error. Since try/catch blocks allow multiple operations to be grouped, we can avoid having to explicitly handle errors for each operation. We can do this same thing asynchronously with promises:

doThisAsync()
.then(doThatAsync)
.then(undefined, console.error)

If doThisAsync() is unsuccessful, its promise will be rejected and the next then in the chain with an onRejected handler will be called. In our case, this is the console.error function. And just like try/catch blocks, doThatAsync() would never get called. This is a huge improvement over raw callbacks where you have to handle errors explicitly at each step.

However, it gets better! Any thrown exception, implicit or explicit, from the then callbacks is also handled in promises:

Promises in the concrete

So far, our examples have used promise-returning dummy methods to illustrate the then method from ES6 and Promises/A+. Let’s turn now and look at more concrete examples.

Converting callbacks to promises

You may be wondering how a promise is generated in the first place. The API for creating a promise isn’t specified in Promise/A+ because it’s not necessary for interoperability. However, ES6 did standardize a Promise constructor which we will come back to. One of the most common cases for use promises is converting existing callback-based libraries. Here, promise libraries like Bluebird can provide convenient helpers.

For example, Node’s core asynchronous functions do not return promises; they take callbacks. However, we can easily make them return promises using Bluebird:

Making APIs that support both callbacks and promises

We have seen two ways to turn callback code into promise code. You can also make APIs that provide both a promise and callback interface. For example, let’s turn fs.readFile into an API that supports both callbacks and promises:

If a callback is provided, it will be called with the standard Node style (err, result) arguments.

readFileAsync('myfile.txt', 'utf8', function (er, data) {
// ...
})

Doing parallel operations with promises

So far, we’ve only talked about sequential asynchronous operations. For parallel operations, ES6 provides the Promise.all method which takes in an array of promises and returns a new promise. The new promise is fulfilled after all the operations have completed successfully. If any of the operations fail, the new promise is rejected.

It’s important to note again that promises mimic functions. A function only has one return value. When passing Promise.all two promises that complete successfully, onFulfilled will be called with only one argument (an array with both results). This may surprise you; however, consistency with synchronous counterparts is an important guarantee that promises provide.

Making promises even more concrete

The best way to really understand promises is to use them. Here are some ideas to get you started: