espretto / whif

Promises/A+ v1.1 implementation >>> testsuite at

whif

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.

Table of Contents

• Usage
• Extras
• Testing
• Building
• API reference
  • [new] whif (global)
  • whif#then (instance)
  • whif#fail (instance)
  • whif#sync (instance)
  • whif.resolve (static)
  • whif.reject (static)
  • whif.nextTick (static)
  • whif.join (static)

Usage

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!
  });

Extras

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.

Testing

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.

Building

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.

API reference

[new] whif (global)

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

whif#then (instance)

register callbacks to access future values

• resolve: function - called on fulfillment
• reject: function - called on rejection
• <return>: whif - successor promise

whif#fail (instance)

register a rejection callback, this is equivalent to .then(null, cb)

• reject: function - called on rejection
• <return>: whif - successor promise

whif#sync (instance)

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

whif.resolve (static)

factory to fulfill a promise

• value: * - the value to wrap in the promise
• <return>: whif - the promise wrapping the input value

whif.reject (static)

factory to reject a promise

• reason: * - the reason why the promise was rejected
• <return>: whif - the promise rejected for the given reason

whif.nextTick (static)

schedule a function to be executed on the next runloop cycle

• fn: function - the function to execute on the next runloop cycle

whif.join (static)

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