Using promises

Asynchronous concepts in jQuery

jQuery promises and deferred

Many operations you perform in both JavaScript and jQuery can take a non-deterministic amount of time.

Some operations, such as animations, take place over a specified amount of time. While you will frequently be responsible for specifiying the amount of time an amination will take, there will be times when the length of time will be variable.

Also, when creating rich web applications, you'll frequently access server resources from your scripts. When you add such functionality, you don't know how long the server is going to take to process your request and return a value.

When those types of operations take place, you don't necessarily care how long they're going to take, but you do need to execute code when they complete. This is where promises come into play.

A promise is an object returned by functions in jQuery that take a long or variable amount of time. By using a promise, you can ensure your code executes whenever the operation completes, be notified of its success or failure, or potentially receive updates about an operation's progress.

Besides the built-in functions that return promises, jQuery also offers you a deferred object. A deferred object allows you to create your own long running operations, allowing developers to use the same patterns provided by the promise object, and be updated when your operation completes.

We're going to start our exploration of asynchronous programming in jQuery by introducing promises. We'll then see how you can create your own functions that return a promise through use of the deferred object. As part of this, we will also discuss the concept of a web worker, which is an HTML5 feature allowing web developers to simulate threads in a web browser.

Promises

jQuery promises

A promise is a programming pattern in which a long running operation "promises" to let you know when it has completed its work.

Long running operations

Any jQuery function that runs over a long period of time, such as an animation, or communicates with a remote server, such as Ajax calls, returns a promise. The promise object offers several events that are raised when the operation is completed, or if there is a progress update.

Promise events

done

done is raised when the operation completes successfully.

done accepts one or more event handler functions.

The event handler can accept one or more parameters, which will contain whatever data the promise object has returned. For example, when making Ajax calls, you will be able to access the data returned by the server in the event handler's parameter. The data returned is determined by the operation.

// code to obtain promise object
promise.done(function(data) {
 // data will contain the data returned by the operation
});

fail

fail is raised when the operation has completed with an error.

Like done, fail accepts one or more parameters. The parameters' values will be determined by the operation.

// code to obtain promise object
promise.fail(function(data) {
 // data will contain the data returned by the operation
});

progress

progress is raised when the operation raises an alert about its current state. Not all operations raise progress events.

Like done and fail, progress allows you to specify one or more event handlers, each optionally accepting parameters. The parameter values are set by the operation.

// code to obtain promise object
promise.progress(function(data) {
 // data will contain the data returned by the operation
});

Chaining

You can add done and fail (and potentially progress) event handlers by chaining the method calls as demonstrated below.

// code to obtain promise object
promise.done(function(data) {
 // success
}).fail(function(data) {
 // failure
});

then

then is a single function allowing you to register done, fail, and progress event handlers in one call. The sample below is identical to the chaining demonstration above.

// code to obtain promise object
promise.then(function(data) {
    // success
}, function(data) {
    // failure
});