April 5, 2013

In the not too distant past the primary tool available to JavaScript programmers for handling asynchronous events was the callback.

A callback is a piece of executable code that is passed as an argument to other code, which is expected to call back ( execute ) the argument at some convenient time



— Wikipedia

In other words, a function can be passed as an argument to another function to be executed when it is called.

There’s nothing inherently wrong with callbacks, but depending on which environment we are programming in there are a number of options available for managing asynchronous events. In this post my goal is to examine one set of available tools: promise objects and deferred objects. In part I, we will cover theory and semantics and in part 2 we will look at the use.

One of the keys to effectively working with asynchronous events in JavaScript is understanding that the program continues execution even when it doesn’t have the value it needs for work that is in progress. Dealing with as yet unknown values from unfinished work can make working with asynchronous events in JavaScript challenging — especially when you’re first getting started.

A classic example of this would be an XMLHttpRequest ( Ajax ). Imagine we want to:

make an Ajax request to get some data

immediately do something with that data, and then

do other things

In our program we initiate our Ajax request. The request is made but unlike with synchronous events, execution of our program isn’t stopped while the server is responding, instead the program continues running. By the time we get the response data from our Ajax request, the program has already finished execution.

Promises & Deferreds: What are they? #

Promises are a programming construct that have been around since 1976. In short:

a promise represents a value that is not yet known

a deferred represents work that is not yet finished

Considered from a high level, promises in JavaScript give us the ability to write asynchronous code in a parallel manner to synchronous code. Let’s start with a diagram to get an overview of the big picture before diving into the specifics.

A promise is a placeholder for a result which is initially unknown while a deferred represents the computation that results in the value. Every deferred has a promise which functions as a proxy for the future result. While a promise is a value returned by an asynchronous function, a deferred can be resolved or rejected by it’s caller which separates the promise from the resolver. The promise itself can be given to any number of consumers and each will observe the resolution independently meanwhile the resolver / deferred can be given to any number of producers and the promise will be resolved by the one that first resolves it. From a semantic perspective this means that instead of calling a function ( callback ), we are able to return a value ( promise ).

Promises According to the Promise/A Proposal #

The Promises /A Proposal suggests the following standard behavior and API regardless of implementation details.

A promise:

Represents the eventual value returned from the single completion of an operation

may be in one of 3 states: unfulfilled, fulfilled and failed and may only move from unfulfilled to either fulfilled or failed

has a function as a value for the property “then” ( which must return a promise )

Adds a fulfilledHandler, errorHandler, and progressHandler to be called for completion of a promise. then(fulfilledHandler, errorHandler, progressHandler)

The value that is returned from the callback handler is the fulfillment value for the returned promise

promise’s value MUST not be changed (avoids side effects from listeners creating unanticipated behavior)

In other words, stripping out some of the nuances for a moment:

A promise serves as a proxy for a future value, has 3 possible states and needs to have a function which adds handlers for it’s states: fulfilledHandler, errorHandler and progressHandler ( optional ) and returns a new promise ( to allow chaining ) which will be resolved / rejected when the handler finishes executing.

The states and return value of a promise #

A promise has 3 possible states: unfulfilled, fulfilled and failed.

unfulfilled: since a promise is a proxy for an unknown value it starts in an unfulfilled state

fulfilled: the promise is filled with the value it was waiting for

failed: if the promise was returned an exception, it is in the failed state.

A promise may only move from unfulfilled to either fulfilled or failed. Upon resolution or rejection, any observers are notified and passed the promise / value. Once the promise has been resolved or rejected neither it’s state or the resulting value can be modified.

Here is an example of what this looks like:

// Promise to be filled with future value var futureValue = new Promise(); // .then() will return a new promise var anotherFutureValue = futureValue.then(); // Promise state handlers ( must be a function ). // The returned value of the fulfilled / failed handler will be the value of the promise. futureValue.then({ // Called if/when the promise is fulfilled fulfilledHandler: function() {}, // Called if/when the promise fails errorHandler: function() {}, // Called for progress events (not all implementations of promises have this) progressHandler: function() {} });

Implementation differences & Performance #

When choosing a promise library, there are a number of considerations to take into account. Not all implementations are created equal. They can differ in regards to what utilities are offered by the API, performance and even in behaviour.

Since the Promise/A proposal only outlines a proposal for the behaviour of promises and not implementation specifics, varying promise libraries have differing sets of features. All Promise/A compliant implementations have a .then() function but also have varying features in their API. Additionally, they are still able to exchange promises with each other. jQuery is the noticeable exception to the rule because its implementation of promises is not fully Promise/A compliant. The impact of this decision is documented here and discussed here.

In Promise/A compliant libraries, a thrown exception is translated into a rejection and the errorHandler() is called with the exception. In jQuery’s implementation an uncaught exception will hault the program’s execution. As a result of the differing implementation, there are interoperability problems if working with libraries which return or expect Promise/A compliant promises.

One solution to this problem is to convert jQuery promises into Promise/A compliant promises with another promise library and then use the API from the compliant library.

For example:

when($.ajax()).then()

When reading through jQuery’s decision to stick with their implementation of promises, a mention of performance considerations piqued my curiosity and I decided to do a quick performance test. I used Benchmark.js and tested the results of creating and resolving a deferred object with a success handler in .then().

The results:

jQuery 91.6kb When.js 1.04kb Q.js 8.74kb 9,979 ops/sec ±10.22% 96,225 ops/sec ±10.10% 2,385 ops/sec ±3.42%

Note: minified with Closure compiler, not gzipped

After running these tests, I discovered a much more in-depth test-suite of promise libraries which reveals similar overall results.

The differences in performance may be negligible in a real application but in my Benchmark.js tests, when.js comes out as a clear winner. This combination of speed and the small size of the library make when.js a great choice when considering performance in the equation.

Clearly there are tradeoffs to consider when choosing a promise library. The answer to which library you should use depends on your specific use case and the needs of your project. Some implementations to start exploring are:

When.js : Fast, lightweight implementation that has a number of useful utilities and as of v2.0 has full support for asynchronous resolution.

: Fast, lightweight implementation that has a number of useful utilities and as of v2.0 has full support for asynchronous resolution. Q.js : Runs in the browser or Node.js, offers a robust API and is fully Promise/A compliant.



: Runs in the browser or Node.js, offers a robust API and is fully Promise/A compliant. RSVP : Barebones implementation that is fully Promise/A compliant.

: Barebones implementation that is fully Promise/A compliant. jQuery: Not Promise/A compliant but is widely used. If you are already using jQuery in your project it’s easy to get started with and worth a look.

Promises provide the JavaScript developer a tool for working with asynchronous events . Now that we’ve covered some of the specifics of what promise objects and deferred objects are and how they behave, we are ready to dive into the specifics of how to work with them. In part 2, we’ll take a closer look at using promises, some common gotcha’s and some specifics of the jQuery API. In the meantime, feel free to start a conversation on App.net or Hacker News.

Further Resources #

Books

Articles

JSFiddle

Promise/A forwarding - jsFiddle documenting value and thrown error propagation in when.js

jQuery .then() and error propagation - jsfiddle demonstrating value and thrown error propagation in jQuery

5,241 Kudos