Deferred

The Deferred constructor encapsulates a single value that is not available yet. The most important example of this in the context of a web browser would be an XMLHttpRequest to a server. The importance of the Deferred is that it allows a consistent API to be exposed for all asynchronous computations that occur exactly once.

The producer of the Deferred is responsible for doing all of the complicated work behind the scenes. This often means waiting for a timer to fire, or waiting for an event (e.g. onreadystatechange of XMLHttpRequest). It could also be coordinating several events (e.g. XMLHttpRequest with a timeout, or several Deferreds (e.g. fetching a set of XML documents that should be processed at the same time).

Since these sorts of tasks do not respond immediately, the producer of the Deferred does the following steps before returning to the consumer:

1. Create a new Deferred(); object and keep a reference to it, because it will be needed later when the value is ready.
2. Setup the conditions to create the value requested (e.g. create a new XMLHttpRequest, set its onreadystatechange).
3. Return the Deferred object.

Since the value is not yet ready, the consumer attaches a function to the Deferred that will be called when the value is ready. This is not unlike setTimeout, or other similar facilities you may already be familiar with. The consumer can also attach an "errback" to the Deferred, which is a callback for error handling.

When the value is ready, the producer simply calls myDeferred.callback(theValue). If an error occurred, it should call myDeferred.errback(theValue) instead. As soon as this happens, the callback that the consumer attached to the Deferred is called with theValue as the only argument.

There are quite a few additional "advanced" features baked into Deferred, such as cancellation and callback chains, so take a look at the API reference if you would like to know more!

Errors

AlreadyCalledError:

Thrown by a Deferred if .callback or .errback are called more than once.

Availability:

Available in MochiKit 1.3.1+

BrowserComplianceError:

Thrown when the JavaScript runtime is not capable of performing the given function. Currently, this happens if the browser does not support XMLHttpRequest.

Availability:

Available in MochiKit 1.3.1+

CancelledError:

Thrown by a Deferred when it is cancelled, unless a canceller is present and throws something else.

Availability:

Available in MochiKit 1.3.1+

GenericError:

Results passed to .errback of a Deferred are wrapped by this Error if !(result instanceof Error).

Availability:

Available in MochiKit 1.3.1+

XMLHttpRequestError:

Thrown when an XMLHttpRequest does not complete successfully for any reason. The req property of the error is the failed XMLHttpRequest object, and for convenience the number property corresponds to req.status.

Availability:

Available in MochiKit 1.3.1+

Constructors

Deferred():

Encapsulates a sequence of callbacks in response to a value that may not yet be available. This is modeled after the Deferred class from Twisted [3].

Why do we want this? JavaScript has no threads, and even if it did, threads are hard. Deferreds are a way of abstracting non-blocking events, such as the final response to an XMLHttpRequest.

The sequence of callbacks is internally represented as a list of 2-tuples containing the callback/errback pair. For example, the following call sequence:

var d = new Deferred();
d.addCallback(myCallback);
d.addErrback(myErrback);
d.addBoth(myBoth);
d.addCallbacks(myCallback, myErrback);

is translated into a Deferred with the following internal representation:

[
    [myCallback, null],
    [null, myErrback],
    [myBoth, myBoth],
    [myCallback, myErrback]
]

The Deferred also keeps track of its current state (see the fired property below). A Deferred will be in the error state if one of the following conditions are met:

1. The result given to callback or errback is "instanceof Error"
2. The callback or errback threw while executing. If the thrown object is not instanceof Error, it will be wrapped with GenericError.

Otherwise, the Deferred will be in the success state. The state of the Deferred determines the next element in the callback sequence to run.

When a callback or errback occurs with the example deferred chain, something equivalent to the following will happen (imagine that exceptions are caught and returned as-is):

// d.callback(result) or d.errback(result)
if (!(result instanceof Error)) {
    result = myCallback(result);
}
if (result instanceof Error) {
    result = myErrback(result);
}
result = myBoth(result);
if (result instanceof Error) {
    result = myErrback(result);
} else {
    result = myCallback(result);
}

The result is then stored away in case another step is added to the callback sequence. Since the Deferred already has a value available, any new callbacks added will be called immediately.

If the initial callback value provided to the Deferred is omitted, an undefined value will be passed instead. This also happens if a callback or errback function does not return a value.

There are two other "advanced" details about this implementation that are useful:

Callbacks are allowed to return Deferred instances, so you can build complicated sequences of events with (relative) ease.

The creator of the Deferred may specify a canceller. The canceller is a function that will be called if Deferred.prototype.cancel is called before the Deferred fires. You can use this to allow an XMLHttpRequest to be cleanly cancelled, for example. Note that cancel will fire the Deferred with a CancelledError (unless your canceller throws or returns a different Error), so errbacks should be prepared to handle that Error gracefully for cancellable Deferred instances.

Object Properties:

fired:

the internal (read-only) status of the Deferred. May have one of the following three values:

Value	Condition
-1	no value yet (initial condition)
0	success
1	error

chained:

an internal (read-only) boolean indicating if this Deferred is chained to another, i.e. its results will propagate to another Deferred. If true, no more callbacks can be added.

finalized:

an internal (read-only) boolean indicating if this Deferred has been finalized. If true, no more callbacks can be added.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.state():

Returns a textual representation of the current deferred state. See also the fired property. The values returned are:

Value	Condition
'unfired'	no result yet (initial condition)
'success'	a successful result has been returned
'error'	an error has been returned

Availability:

Available in MochiKit 1.5+

Deferred.prototype.addBoth(func[, ...]):

Add the same function as both a callback and an errback as the next element on the callback sequence. This is useful for code that you want to guarantee to run.

If additional arguments are given, then func will be replaced with MochiKit.Base.partial.apply(null, arguments). This differs from Twisted, because the result of the callback or errback will be the last argument passed to func.

If func returns a Deferred, then it will be chained (its value or error will be passed to the next callback). Note that once the returned Deferred is chained, it can no longer accept new callbacks.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.addCallback(func[, ...]):

Add a single callback to the end of the callback sequence.

If additional arguments are given, then func will be replaced with MochiKit.Base.partial.apply(null, arguments). This differs from Twisted, because the result of the callback will be the last argument passed to func.

If func returns a Deferred, then it will be chained (its value or error will be passed to the next callback). Note that once the returned Deferred is chained, it can no longer accept new callbacks.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.addCallbacks(callback, errback):

Add separate callback and errback to the end of the callback sequence. Either callback or errback may be null, but not both.

If callback or errback returns a Deferred, then it will be chained (its value or error will be passed to the next callback). Note that once the returned Deferred is chained, it can no longer accept new callbacks.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.addErrback(func[, ...]):

Add a single errback to the end of the callback sequence.

If additional arguments are given, then func will be replaced with MochiKit.Base.partial.apply(null, arguments). This differs from Twisted, because the result of the errback will be the last argument passed to func.

If func returns a Deferred, then it will be chained (its value or error will be passed to the next callback). Note that once the returned Deferred is chained, it can no longer accept new callbacks.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.setFinalizer(func[, ...]):

Sets the finalizer function of the callback sequence. The finalizer will always be called last in the sequence, regardless of the number of callbacks added afterwards. Note that the value returned by the finalizer will always be ignored, and no new callbacks can be added to the Deferred once finalized.

If additional arguments are given, then func will be replaced with MochiKit.Base.partial.apply(null, arguments).

Availability:

Available in MochiKit 1.5+

Deferred.prototype.callback([result]):

Begin the callback sequence with a non-Error result. Result may be any value except for a Deferred.

Either .callback or .errback should be called exactly once on a Deferred.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.cancel([error]):

Cancels a Deferred that has not yet received a value, or is waiting on another Deferred as its value.

If a canceller is defined, the canceller is called. If the canceller did not return an Error, or there was no canceller, then the errback chain is started with CancelledError.

Since MochiKit 1.5, an optional error argument can be used to send either a generic error message (GenericError) or any subclass of Error.

Availability:

Available in MochiKit 1.3.1+

Deferred.prototype.errback([result]):

Begin the callback sequence with an error result. Result may be any value except for a Deferred, but if !(result instanceof Error), it will be wrapped with GenericError.

Either .callback or .errback should be called exactly once on a Deferred.

Availability:

Available in MochiKit 1.3.1+

DeferredLock():

A lock for asynchronous systems.

The locked property of a DeferredLock will be true if it locked, false otherwise. Do not change this property.

Availability:

Available in MochiKit 1.3.1+

DeferredLock.prototype.acquire():

Attempt to acquire the lock. Returns a Deferred that fires on lock acquisition with the DeferredLock as the value. If the lock is locked, then the Deferred goes into a waiting list.

Availability:

Available in MochiKit 1.3.1+

DeferredLock.prototype.release():

Release the lock. If there is a waiting list, then the first Deferred in that waiting list will be called back.

Availability:

Available in MochiKit 1.3.1+

DeferredList(list, [fireOnOneCallback, fireOnOneErrback, consumeErrors, canceller]):

Combine a list of Deferred into one. Track the callbacks and return a list of (success, result) tuples, 'success' being a boolean indicating whether result is a normal result or an error.

Once created, you have access to all Deferred methods, like addCallback, addErrback, addBoth. The behaviour can be changed by the following options:

fireOnOneCallback:

Flag for launching the callback once the first Deferred of the list has returned.

fireOnOneErrback:

Flag for calling the errback at the first error of a Deferred.

consumeErrors:

Flag indicating that any errors raised in the Deferreds should be consumed by the DeferredList.

Example:

// We need to fetch data from 2 different urls
var d1 = loadJSONDoc(url1);
var d2 = loadJSONDoc(url2);
var l1 = new DeferredList([d1, d2], false, false, true);
l1.addCallback(function (resultList) {
    MochiKit.Base.map(function (result) {
        if (result[0]) {
            alert("Data is here: " + result[1]);
        } else {
            alert("Got an error: " + result[1]);
        }
    }, resultList);
});

Availability:

Available in MochiKit 1.3.1+

Functions

callLater(seconds, func[, args...]):

Call func(args...) after at least seconds seconds have elapsed. This is a convenience method for:

func = partial.apply(extend(null, arguments, 1));
return wait(seconds).addCallback(function (res) { return func() });

Returns a cancellable Deferred.

Availability:

Available in MochiKit 1.3.1+

doXHR(url[, {option: value, ...}]):

Perform a customized XMLHttpRequest and wrap it with a Deferred that may be cancelled.

Note that only 200 (OK), 201 (CREATED), 204 (NO CONTENT) and 304 (NOT MODIFIED) are considered success codes. All other status codes will result in an errback with an XMLHttpRequestError.

url:

The URL for this request.

The following options are currently accepted:

method:

The HTTP method. Default is 'GET'.

sendContent:

The content to send (e.g. with POST). Default is no content.

queryString:

If present it will be used to build a query string to append to the url using MochiKit.Base.queryString. Default is no query string.

username:

The username for the request. Default is no username.

password:

The password for the request. Default is no password.

headers:

Additional headers to set in the request, either as an object such as {'Accept': 'text/xml'} or as an Array of 2-Arrays [['Accept', 'text/xml']]. Default is no additional headers.

mimeType:

An override mime type. The typical use of this is to pass 'text/xml' to force XMLHttpRequest to attempt to parse responseXML. Default is no override.

responseType:

An override response type for the request. This can be used to force different parsing of the response in the browser, e.g. using 'arraybuffer' to load binary data efficiently. Accepted values are 'arraybuffer', 'blob', 'document', 'json', and 'text'. Default is no override.

withCredentials:

Set the boolean withCredentials property of the XMLHttpRequest object, to indicate to the browser that cookies will be sent with the request, and to look for the Access-Control-Allow-Credentials header.

returns:

Deferred that will callback with the XMLHttpRequest instance on success

Availability:

Available in MochiKit 1.4+.

doSimpleXMLHttpRequest(url[, queryArguments...]):

Perform a simple XMLHttpRequest and wrap it with a Deferred that may be cancelled.

Note that only 200 (OK), 201 (CREATED), 204 (NO CONTENT) and 304 (NOT MODIFIED) are considered success codes. All other status codes will result in an errback with an XMLHttpRequestError.

url:

The URL to GET

queryArguments:

If this function is called with more than one argument, a "?" and the result of MochiKit.Base.queryString with the rest of the arguments are appended to the URL.

For example, this will do a GET request to the URL http://example.com?bar=baz:

doSimpleXMLHttpRequest("http://example.com", {bar: "baz"});

returns:

Deferred that will callback with the XMLHttpRequest instance on success

Availability:

Available in MochiKit 1.3.1+. Support for 201 and 204 were added in MochiKit 1.4.

evalJSONRequest(req):

Evaluate a JSON [4] XMLHttpRequest

req:

The request whose .responseText property is to be evaluated. If the JSON is wrapped in a comment, the comment will be stripped before evaluation.

returns:

A JavaScript object

Availability:

Available in MochiKit 1.3.1+

fail([result]):

Return a Deferred that has already had .errback(result) called.

See succeed documentation for rationale.

result:

The result to give to Deferred.prototype.errback(result).

returns:

A new Deferred()

Availability:

Available in MochiKit 1.3.1+

gatherResults(deferreds):

A convenience function that returns a DeferredList from the given Array of Deferred instances that will callback with an Array of just results when they're available, or errback on the first array.

Availability:

Available in MochiKit 1.3.1+

getXMLHttpRequest():

Return an XMLHttpRequest compliant object for the current platform.

In order of preference:

• new XMLHttpRequest()
• new ActiveXObject('Msxml2.XMLHTTP')
• new ActiveXObject('Microsoft.XMLHTTP')
• new ActiveXObject('Msxml2.XMLHTTP.4.0')

Availability:

Available in MochiKit 1.3.1+

maybeDeferred(func[, argument...]):

Call a func with the given arguments and ensure the result is a Deferred.

func:

The function to call.

returns:

A new Deferred based on the call to func. If func does not naturally return a Deferred, its result or error value will be wrapped by one.

Availability:

Available in MochiKit 1.3.1+

loadJSONDoc(url[, queryArguments...]):

Do a simple XMLHttpRequest to a URL and get the response as a JSON [4] document.

url:

The URL to GET

queryArguments:

If this function is called with more than one argument, a "?" and the result of MochiKit.Base.queryString with the rest of the arguments are appended to the URL.

For example, this will do a GET request to the URL http://example.com?bar=baz:

loadJSONDoc("http://example.com", {bar: "baz"});

returns:

Deferred that will callback with the evaluated JSON [4] response upon successful XMLHttpRequest

Availability:

Available in MochiKit 1.3.1+

loadScript(url):

Loads and evaluates an external JavaScript (possibly on another server). The script will be added to the page <head> element. Note that only trusted scripts should be added like this, since they execute in the current page environment.

url:

The URL to the JavaScript to load.

returns:

A new Deferred that will callback without value on success, or with a URIError if the script failed to load.

Availability:

Available in MochiKit 1.5+

sendXMLHttpRequest(req[, sendContent]):

Set an onreadystatechange handler on an XMLHttpRequest object and send it off. Will return a cancellable Deferred that will callback on success.

Note that only 200 (OK), 201 (CREATED), 204 (NO CONTENT) and 304 (NOT MODIFIED) are considered success codes. All other status codes will result in an errback with an XMLHttpRequestError.

req:

An preconfigured XMLHttpRequest object (open has been called).

sendContent:

Optional string or DOM content to send over the XMLHttpRequest.

returns:

Deferred that will callback with the XMLHttpRequest instance on success.

Availability:

Available in MochiKit 1.3.1+. Support for 201 and 204 were added in MochiKit 1.4.

succeed([result]):

Return a Deferred that has already had .callback(result) called.

This is useful when you're writing synchronous code to an asynchronous interface: i.e., some code is calling you expecting a Deferred result, but you don't actually need to do anything asynchronous. Just return succeed(theResult).

See fail for a version of this function that uses a failing Deferred rather than a successful one.

result:

The result to give to Deferred.prototype.callback(result)

returns:

a new Deferred

Availability:

Available in MochiKit 1.3.1+

wait(seconds[, res]):

Return a new cancellable Deferred that will .callback(res) after at least seconds seconds have elapsed.

Availability:

Available in MochiKit 1.3.1+

timeout(deferred, ms):

Return a Deferred that will automatically be cancelled after ms milliseconds.

Availability:

Available in MochiKit 1.5+

when(valueOrDeferred):

Similar to maybeDeferred but looks at a value instead of a function call.

Availability:

Available in MochiKit 1.5+