jQuery.Deferred(), introduced in version 1.5, is a chainable utility object that can register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.
In JavaScript it is common to invoke functions that optionally accept callbacks that are called within that function.
For example, in versions prior to jQuery 1.5, asynchronous processes such as jQuery.ajax() accept callbacks to be invoked some time in the near-future upon success, error, and completion of the ajax request.
jQuery.Deferred() introduces several enhancements to the way callbacks are managed and invoked. In particular, jQuery.Deferred() provides flexible ways to provide multiple callbacks, and these callbacks can be invoked regardless of whether the original callback dispatch has already occurred. jQuery Deferred is based on the CommonJS Promises/A design.
One model for understanding Deferred is to think of it as a chain-aware function wrapper. The deferred.then(), deferred.done(), and deferred.fail() methods specify the functions to be called and the deferred.resolve(args) or deferred.reject(args) methods “call” the functions with the arguments you supply. Once the Deferred has been resolved or rejected it stays in that state; a second call to deferred.resolve() is ignored for example. If more functions are added by deferred.then() after the Deferred is resolved, they are called immediately with the arguments previously provided.
In most cases where a jQuery API call returns a Deferred or Deferred-compatible object, such as jQuery.ajax() or jQuery.when(), you will only want to use the deferred.then(), deferred.done(), and deferred.fail() methods to add callbacks to the Deferred’s queues. The internals of the API call or code that created the Deferred will invoke deferred.resolve() or deferred.reject() on the deferred at some point, causing the appropriate callbacks to run.
jQuery.Deferred Constructor
The jQuery.Deferred() constructor creates a new Deferred object. The new operator is optional.
jQuery.Deferred can be passed an optional function, which is called just before the constructor returns and is passed the constructed deferred object as both the this object and as the first argument to the function. The called function can attach callbacks using deferred.then() for example.
A Deferred object starts in the pending state. Any callbacks added to the object with deferred.then(), deferred.done(), or deferred.fail() are queued to be executed later. Calling deferred.resolve() or deferred.resolveWith() transitions the Deferred into the resolved state and immediately executes any doneCallbacks that are set. Calling deferred.reject() or deferred.rejectWith() transitions the Deferred into the rejected state and immediately executes any failCallbacks that are set. Once the object has entered the resolved or rejected state, it stays in that state. Callbacks can still be added to the resolved or rejected Deferred — they will execute immediately.
The Deferred object is chainable, similar to the way a jQuery object is chainable, but it has its own methods. After creating a Deferred object, you can use any of the methods below by either chaining directly from the object creation or saving the object in a variable and invoking one or more methods on that variable.
-
deferred.always()
Add handlers to be called when the Deferred object is either resolved or rejected.
-
deferred.done()
Add handlers to be called when the Deferred object is resolved.
-
deferred.fail()
Add handlers to be called when the Deferred object is rejected.
-
deferred.isRejected()
DeprecatedDetermine whether a Deferred object has been rejected.
-
deferred.isResolved()
DeprecatedDetermine whether a Deferred object has been resolved.
-
deferred.notify()
Call the progressCallbacks on a Deferred object with the given
args. -
deferred.notifyWith()
Call the progressCallbacks on a Deferred object with the given context and
args. -
deferred.pipe()
Utility method to filter and/or chain Deferreds.
-
deferred.progress()
Add handlers to be called when the Deferred object generates progress notifications.
-
deferred.promise()
Return a Deferred's Promise object.
-
deferred.reject()
Reject a Deferred object and call any failCallbacks with the given
args. -
deferred.rejectWith()
Reject a Deferred object and call any failCallbacks with the given
contextandargs. -
deferred.resolve()
Resolve a Deferred object and call any doneCallbacks with the given
args. -
deferred.resolveWith()
Resolve a Deferred object and call any doneCallbacks with the given
contextandargs. -
deferred.state()
Determine the current state of a Deferred object.
-
deferred.then()
Add handlers to be called when the Deferred object is resolved or rejected.
-
.promise()
Return a Promise object to observe when all actions of a certain type bound to the collection, queued or not, have finished.
-
jQuery.when()
CoreProvides a way to execute callback functions based on one or more objects, usually Deferred objects that represent asynchronous events.