jQuery Deferred

Deferred Object (is like MochiKit?.Async) for jQuery. Simple and clean asynchronous processing.

Sample

http://svn.coderepos.org/share/lang/javascript/jquery-deferred/sample.html

Download

http://svn.coderepos.org/share/lang/javascript/jquery-deferred/jquery-deferred.js

Documentation

See source.

http://svn.coderepos.org/share/lang/javascript/jquery-deferred/doc/index.html

Test

http://svn.coderepos.org/share/lang/javascript/jquery-deferred/test.html

Concept

• Compact (Main Deferred object is only 51 line)
• Core is independent from jQuery (actually jQuery Deferred use jQuery only for XMLHttpRequest and wrapping $.{get,port,getJSON}.)

Internal

This sections use some words as following meaning.

chain

a sequence of processes.

child

the Deferred which returns from a callback.

Deferred#foobar

Deferred.prototype.foobar

Deferred structure and chain structure

A Deferred object has only one callback as its process. Deferred object packages a process (function) as callback and has reference to next Deferred (this is thought like continuation).

Example for understanding Deferred structure.

var d1 = new Deferred();
d1.callback.ok = function () {
    alert("1");
};

var d2 = new Deferred();
d2.callback.ok = function () {
    alert("2");
};

// Set d2 as continuation of d1.
d1._next = d2;

// Invoke the chain.
d1.call();

And example for usual use.

next(function () { // this `next` is global function
    alert("1");
}.
next(function () { // this `next` is Deferred#next
    alert("2");
}).
next(function () {
    alert("3");
});

Deferred#next creates new Deferred, sets the passed functions to process of the new Deferred, sets it as continuation of this and returns it.

This structure makes easy to chain child Deferreds.

next(function () {
    alert("1");
}).
next(function () {
    alert("2");
    // child Deferred
    return next(function () {
        alert("3");
    });
}).
next(function () {
    alert("4");
});

When the callback returns Deferred, the Deferred called the callback only sets its continuation (_next) to returned Deferred's continuation.

next(function () {
    alert("1");
}).
next(function () {
    alert("2");
    var d = next(function () {
        alert("3");
    });
    d._next = this._next;
    this.cancel();
}).
next(function () {
    alert("4");
});

After the process, above code is same as following:

next(function () {
    alert("1");
}).
next(function () {
    alert("2");
    next(function () {
        alert("3");
    }).
    next(function () {
        alert("4");
    });
});

Error processing and recovering

A Deferred has also error-back for error processing. Let's just see a example (from test):

next(function () {
    throw "Error";
}).
error(function (e) {
	expect("Errorback called", "Error", e);
	return e; // recovering error
}).
next(function (e) {
	expect("Callback called", "Error", e);
	throw "Error2";
}).
next(function (e) {
	// This process is not called because
	// the error is not recovered.
	ng("Must not be called!!");
}).
error(function (e) {
	expect("Errorback called", "Error2", e);
});

The error thrown in callback is propagated by error-back chain. If the error-back returns normal value, the error is considered as recovery and continue the callback chain.

Deference between MochiKit? and this

• MochiKit? Deferred has chain by Array. This Deferred has chain by chain of Deferred.
• MochiKit? Deferred separates parent chain and child chain.