Deferreds.js is a utility library centered around working with Promises/A+ Promise/Deferred objects. The main goal is to do for Deferred objects what async.js does for Node-style asynchronous functions — that is, provide many common higher-order functions (map, reduce, filter, etc.) accepting potentially-asynchronous Deferred objects as arguments.
Using npm:
npm install deferreds
UMD (AMD and CommonJS) and browser-global copies are included.
- v1.x -
Promises/A+-compliant
implementations
- The test suite is currently run against jQuery.Deferred 1.8, Q 0.x, RSVP 2.x, and when 2.x.
- v0.x - Promise implementations with a non-chainable
thenmethod (such as jQuery.Deferred < 1.8)
Utility functions fall into one of two categories: Collection functions and Control Flow functions. They can be further split into functions which operate on inputs in parallel and ones which operate in series:
var Deferred = require('deferreds/Deferred');
var series = require('deferreds/series');
//_delayed is a Function which returns a Promise
//is fulfilled with `val` after `t` milliseconds
var _delayed = function(t, val) {
var deferred = new Deferred();
setTimeout(function() {
deferred.resolve(val);
}, t);
return deferred.promise();
};
//regular usage: Array of Functions returning Promises
series([
function() {
return _delayed(20, 'A');
},
//20ms passes, then:
function(){
return _delayed(30, 'B');
},
//30ms passes, then:
function(){
return _delayed(10, 'C');
}
]).then(function(result) {
console.log(result); //> ['A', 'B', 'C']
});
//Deferred/Promise objects and regular values may be passed as-is, and result
//will still be in order
series([
function() {
return _delayed(20, 'A');
},
_delayed(30, 'B'),
'C'
]).then(function(result) {
console.log(result); //> ['A', 'B', 'C']
});In most functions, iterator is expected to be an asynchronous function which
returns a Deferred or Promise object. This is not a requirement, but you
are using this library to work with asynchronous code, right? All functions
return a Promise object referencing a "master" Deferred object which will
resolve with a value which would normally be returned in common higher-order
function libraries. Deferreds' methods can all accept asynchronous functions,
so the final result is not always known at return time. Therefore we supply
output within the resolved values of Deferred objects rather than returning
them.
Parallel methods will call iterator for all items in the list in
parallel, not guaranteeing the order in which items are processed. They return
a Promise referencing a "master" Deferred object which will be resolved
when all Deferred objects returned from iterator (or the Deferred objects
referenced from the Promise objects returned from iterator) are resolved.
If any Deferred object referenced in iterator is rejected, the "master"
Deferred object will immediately be rejected. However, because iterator was
initially called for all items in parallel, those calls will continue to run
(by necessity, not by design) in the background.
Series methods will call iterator for each item in the list
one-at-a-time, each time waiting for the Deferred object returned from
iterator (or referenced from the Promise object returned from iterator)
to resolve. If list is an Array, order of iteration is guaranteed. They
return a Promise object referencing a "master" Deferred object which will
be resolved when the Deferred object returned from the last call to
iterator (or the Deferred object referenced from the Promise object
returned from the last call to iterator) is resolved. If any Deferred
object returned from iterator is rejected, series methods will fail fast,
skipping any remaining items and rejecting the "master" Deferred object.
All methods will cease processing and immediately reject their returned
Deferred object if any iterator (for collection functions) or task (for
flow control functions) evaluates to a Deferred object which is rejected.
This is especially useful for series methods because they process in order,
making skipping further processing possible when failing fast.
Released under the MIT License.