whif is a Promises A+ implementation compliant with version 1.1 passing the tests. many thanks to this lib's originator Rhys Brett-Bowen and his great article on Promises/A+ - understanding the spec through implementation.
basic usage
var promise = new whif(function(resolve, reject) {
if (condition) resolve(value)
else reject(reason)
})
promise.then(
function (value) { /* success */ },
function (reason) { /* failure */ }
)convenience shortcuts
var resolvedPromise = whif.resolve(value); // not necessarily fulfilled!
var rejectedPromise = whif.reject(reason);grouping concurrent processes
whif.join([p, q, true])
.then(function (values) {
var p_value = values[0];
var q_value = values[1];
var boolean = values[2];
throw new Error();
})
.fail(function (reason) {
// handler for whichever was rejected first,
// not necessarily the error thrown above!
});whif ships with a shim for cross-platform/-browser process.nextTick
whif.nextTick(function () {
// executed in the next run-loop-cycle
});promises usually resolve/reject their successors asynchronously to ensure consistent behaviour/order of execution since code wrapped in promises may or may not involve asynchronous actions.
var promise = whif.resolve('foo');
promise.then(console.log);
console.log('bar');the above logs bar first and then foo because the then-handler is wrapped by process.nextTick internally. however, if a promise wraps an asynchronous action anyway it's actually not necessary to defer the resolution until the next tick and thereby twice. for this and other edge cases you may call whif's sync method on the promise before you bind successors.
var promise = whif
.resolve($.ajax(request_settings))
.sync().then( /* ... */ )
.sync().fail( /* ... */ );be careful with this option since success may be yielded asynchronously but failure synchronously depending on your implementation. remember that promises were normalized by prolonging the resolution because of these potential differences in the first place.
whif is tested against the A+ testsuite which you can execute with npm test. In addition you may run the tests in the browser. First launch npm run testling, then open the url shown in the commandline http://localhost:8000/__testling?show=true. For convenience, a static version of testling's output has been pushed to gh-pages.
whif targets older environnements by using the UMD pattern. Use npm run build to generate the bundle ./dist/whif.js. Both the global export as well as the AMD module are named whif.
the API reference is based on jsdocstrings in the source, built using npm run --silent build-docs and appended to this readme.
promise class
init: function- factory to construct/fetch the future value, will be called with callbacks (resolve, reject) to fulfill or reject the promise being constructed
register callbacks to access future values
resolve: function- called on fulfillmentreject: function- called on rejection<return>: whif- successor promise
register a rejection callback, this is equivalent to .then(null, cb)
reject: function- called on rejection<return>: whif- successor promise
marks this promise as synchronous. all registered callbacks will be called synchronously. this deviates from the spec but allows for a minor speedup by avoiding duplicate runloop cycles.
<return>: whif- the instance itself
factory to fulfill a promise
value: *- the value to wrap in the promise<return>: whif- the promise wrapping the input value
factory to reject a promise
reason: *- the reason why the promise was rejected<return>: whif- the promise rejected for the given reason
schedule a function to be executed on the next runloop cycle
fn: function- the function to execute on the next runloop cycle
group multiple promises and either resolve when all of them have them been fulfilled or reject upon the first rejection, not waiting for the others.
promises: Array.<whif>- promises to group<return>: whif- group promise, resolve handlers are called with an array of future values