This is a port of jQuery.Deferred as an Underscore mixin, but it can be
used without any depencencies. It currently matches the Deferred specifications
and implementation from jQuery 1.8.0, with all the associated helpers.
Deferreds are great, let's take them everywhere
jQuery offers a robust, consistent and well documented API; this project aims
to make it portable. jQuery added a handful of helper methods to their
implementation of the Common.js Promises/A Spec and they're faithfully
reproduced without any dependencies.
Usage
underscore.deferred works on the server and in the browser.
In the browser, just require it like you would any other file. If you're
including Underscore on the page, make sure you include it before
underscore.deferred. If you don't have Underscore, the plugin attaches to
window._.
On the server, simply install via npm and include it with require:
var _ = require('underscore.deferred');var dfd = new _.Deferred(); // tada!
Or if you'd like to use it as an Underscore or Lodash mixin:
var _ = require('underscore');_.mixin( require('underscore.deferred') );
Underscore isn't a strict requirement, and assigning it to another
name will always work.
Addionally, underscore.Deferred can be used with Ender.js, if
you're still into that sort of thing.
Enhancements / Changes
So far, there's only 1 substantial difference between the jQuery API and
underscore.deffered's. This may change in the future as new or
divergent functionality is tested out, but rest assured that all differences
will be called out here (and will have proper test coverage.)
###_.when
underscore.deferred will apply an Array if it's the only argument, providing a
useful shortcut for using when with an array of promises. Example:
var form = _.Deferred();var auth = _.Deferred();var promises = [ form.promise(), auth.promise() ];_.when(promises).done(function(){ // ...});form.resolve();auth.resolve();
API
underscore.deferred is an implementation of the jQuery.Deferred
API. Here are some of the methods implemented:
This project wouldn't exist if not for the the hard work and effort put
into jQuery by its core team and contributors--thanks for making this
possible!
The goal is to slim the code footprint for robust deferreds as much as
possible while maintaining mixin integration with Underscore and faithfullness
to the jQuery API.
This is a work in progress, feel free to contribute.
0.1.4 - updating to match jQuery 1.7.2; Please note that as of 0.1.4 underscore.deferred will be ALL LOWERCASE on
npm. The camelcasing was a mistake from the outset, please update your
package.json appropriately.