A lightweight CommonJS Promises/A and when()
implementation. It also provides several other useful Promise-related concepts, such as joining and chaining.
when.js is derived from the async core of wire.js, and future versions of wire will use when.js directly.
Register a handler for a promise or immediate value:
when(promiseOrValue, callback, errback, progressback)
// Always returns a promise, so can be chained:
when(promiseOrValue, callback, errback, progressback).then(anotherCallback, anotherErrback, anotherProgressback)
Create a new Deferred containing separate promise
and resolver
parts:
var deferred = when.defer();
var promise = deferred.promise;
var resolver = deferred.resolver;
The deferred has the full promise
+ resolver
API:
deferred.then(callback, errback, progressback);
deferred.resolve(value);
deferred.reject(reason);
deferred.progress(update);
The promise
API:
// var promise = deferred.promise;
promise.then(callback, errback, progressback);
The resolver
API:
// var resolver = deferred.resolver;
resolver.resolve(value);
resolver.reject(err);
resolver.progress(update);
when.some(promisesOrValues, howMany, callback, errback, progressback)
Return a promise that will resolve when howMany
of the supplied promisesOrValues
have resolved. The resolution value of the returned promise will be an array of length howMany
containing the resolutions values of the triggering promisesOrValues
.
when.some(promisesOrValues, callback, errback, progressback)
Return a promise that will resolve only once all the supplied promisesOrValues
have resolved. The resolution value of the returned promise will be an array containing the resolution values of each of the promisesOrValues
.
when.any(promisesOrValues, callback, errback, progressback)
Return a promise that will resolve when any one of the supplied promisesOrValues
has resolved. The resolution value of the returned promise will be the resolution value of the triggering promiseOrValue
.
when.chain(promiseOrValue, resolver, optionalValue)
Ensure that resolution of promiseOrValue
will complete resolver
with the completion value of promiseOrValue
, or instead with optionalValue
if it is provided.
Returns a new promise that will complete when promiseOrValue
is completed, with the completion value of promiseOrValue
, or instead with optionalValue
if it is provided.
Note: If promiseOrValue
is not an immediate value, it can be anything that supports the promise API (i.e. then()
), so you can pass a deferred
as well. Similarly, resolver
can be anything that supports the resolver API (i.e. resolve()
, reject()
), so a deferred
will work there, too.
Much of this code is based on @unscriptable's tiny promises, the async innards of wire.js, and some gists here, here, here, and here