Deferred and promise in jQuery
Deferred and promise? What is this article about? Deferred and promise are part of jQuery since version 1.5 and they help in handling asynchronous functions like Ajax.
Let's do a step back in time. A time without iPod or Xbox or Facebook. If you wanted to catch a mouseclick, you did it with element.onclick = someFunction; This became a problem when another part of the code also wanted to listen to this click. This was not possible, because you could only assign one function. This was solved at the time with the addEventListener DOM-function. With this, you can add as many listener functions as you want. Since then, that's the way we know how to do this.
Now we have a similar problem with Ajax-calls. This time it's not the events, but the fact that Ajax supports only one callback function. Not only the jQuery $.ajax()-call, but also the underlying XMLHttpRequest-object.
Promise
Until jQuery 1.5, a typical $.ajax()-call looked like this:
$.ajax({ url: "/myServerScript", success: mySuccessFunction, error: myErrorFunction });
The $.ajax()-call returns a jQuery XMLHttpRequest-object. Nothing new so far.
Since version 1.5, the returned object implements the CommonJS Promises/A-interface. That's a mouth full. CommonJS is a initiative to define common and independent interfaces (API's). Promises/A is one such interface. The advantage is that these are not jQuery specific. For example, if you work with Node.js, there is a good chance you'll program with this same interface. That's good.
The way of assigning callbacks with Promises is quite different:
var promise = $.ajax({ url: "/myServerScript" }); promise.done(mySuccessFunction); promise.fail(myErrorFunction);
“Okay, the interface has changed, so what's in it for me?”, you might ask.
The advantages of promises are:
1) You can call the done()- and fail()-functions more times, with different callbacks. Maybe you have a callback function that stops an animation, one that does a new Ajax-call and another function that shows the received data to the visitor.
var promise = $.ajax({ url: "/myServerScript" }); promise.done(myStopAnimationFunction); promise.done(myOtherAjaxFunction); promise.done(myShowInfoFunction); promise.fail(myErrorFunction);
2) Even after the Ajax-call has finished, you can still call the done()- and fail()-functions and the callbacks are executed immediately. So no messing around with variables holding different states. When a Ajax-call has finished, it will end up in either the success-state or the failed-state and this state will not change.
3) You can combine promises. Sometimes you need to do two simultaneous Ajax-calls and you want to execute a function when both are successfully finished. To do this, you use the new $.when()-function:
var promise1 = $.ajax("/myServerScript1"); var promise2 = $.ajax("/myServerScript2"); $.when(promise1, promise2).done(function(response1, response2){ // Handle both responses });
Deferred
So what is a deferred and what is the difference with a promise? As you have seen above, a promise is an object that is returned from an asynchronous function. You need a deferred when you write such a function yourself.
A deferred object can do the same as a promise object, but it has two functions to trigger the done()- and fail()-functions.
A deferred object has a resolve()-functions for a successful result and to execute the functions assigned with done(). The reject()-function is for a failed result and executes the functions assigned with fail().
You can give parameters to both the resolve()- and reject()-functions and they will be passed on to the functions registered with done() and fail().
The promise object does not have resolve()- or reject()-functions. This is because you give the promise away to other scripts and you don't want them to resolve or reject the promise.
Below is a simple script that illustrates how it works. The html is just an empty div with id "result".
$('#result').html('waiting...'); var promise = wait(); promise.done(result); function result() { $('#result').html('done'); } function wait() { var deferred = $.Deferred(); setTimeout(function() { deferred.resolve(); }, 2000); return deferred.promise(); }
You can also find this script on jsFiddle, so that you can experiment with it yourself.
The wait()-function is the function returning a promise. This will be resolved with a setTimeout of two seconds. Instead of setTimeout, everything can be used that is asynchronous, like animations, Web workers etcetera. It should be clear that inside the wait()-function, we use the deferred object, but we return the limited promise-object.
jQuery support
On the jQuery blog, you can read that jQuery goes completely for promises and the old API with the error()-, success()- and complete()-functions will disappear eventually. When you use these functions, you might as well start rewriting them and use the promise-interface.
Other possibilities
This article is just an introduction to the deferred-object. jQuery supports even more functions. Look at the jQuery deferred documentatie voor all possibilities. It is, for example, possible to track the progress of a process.
This article is originally posted in Dutch for the Fronteers Advent Calendar. Fronteers is the Dutch organisation of front end developers.