Promise & Deferred objects in JavaScript
Introduction
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?
- 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
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.
- Q.js: 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.
- 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.
