when.js

When.js is cujoJS's lightweight Promises/A+ and when() implementation that powers the async core of wire.js, cujoJS's IOC Container. It features:

• A rock solid, battle-tested Promise implementation
• Resolving, settling, mapping, and reducing arrays of promises
• Executing tasks in parallel and sequence
• Transforming Node-style and other callback-based APIs into promise-based APIs

It passes the Promises/A+ Test Suite, is very fast and compact, and has no external dependencies.

What's New?

2.6.0

• New promise.done allows consuming the ultimate value at the end of a promise chain while ensuring that any errors are thrown to the host environment so you get loud stack traces.
• when/node/function bindCallback and liftCallback now behave more like standard node-style APIs in that they allow exceptions to propagate to the host environment for loud stack traces.

2.5.1

• ensure now ignores non-functions, like then does, for consistency. (#207)

2.5.0

• Promises/A+ 1.1 compliant. Passes version 2.0.0 of the Promises/A+ test suite.

2.4.1

• New MutationObserver scheduler further reduces "time-to-first-handler" in modern browsers. (#198)
  • Also, this works around a horrible IE10 bug (desktop and mobile) that renders setImmediate, MessageChannel, and postMessage unusable as fast task schedulers. Many thanks to @plaa and @calvinmetcalf for their help in discovering the problem and working out a solution. (#197)

2.4.0

• Experimental support for vert.x 2.x. Should now run in vert.x >= 1.1.0.
• New when.isPromiseLike as the more accurately-named synonym for when.isPromise.
• DEPRECATED: when.isPromise. It can only tell you that something is "promise-like" (aka "thenable") anyway. Use the new, more accurately-named when.isPromiseLike instead.
• Fix for promise monitor reporting extra unhandled rejections for when.all and when.map.

2.3.0

• New promise.tap for adding side effects to a promise chain.
• New MessageChannel scheduler reduces "time-to-first" handler, in environments that support it.
• Performance optimizations for promise resolution.
• Internal architecture improvements to pave the way for when.js 3.0.0.

Full Changelog

Docs & Examples

API docs

More info on the wiki

Examples

Quick Start

AMD

1. Get it

   • bower install when or yeoman install when, or
   • git clone https://github.com/cujojs/when or git submodule add https://github.com/cujojs/when

2. Configure your loader with a package:

   packages: [
       { name: 'when', location: 'path/to/when/', main: 'when' },
       // ... other packages ...
   ]

3. define(['when', ...], function(when, ...) { ... }); or require(['when', ...], function(when, ...) { ... });

Node

1. npm install when
2. var when = require('when');

RingoJS

1. ringo-admin install cujojs/when
2. var when = require('when');

Legacy environments

1. git clone https://github.com/cujojs/when or git submodule add https://github.com/cujojs/when

2. Add a transient define shim, and a <script> element for when.js

   <script>
       window.define = function(factory) {
           try{ delete window.define; } catch(e){ window.define = void 0; } // IE
           window.when = factory();
       };
       window.define.amd = {};
   </script>
   <script src="path/to/when/when.js"></script>

3. when will be available as window.when

Running the Unit Tests

Node

Note that when.js includes the Promises/A+ Test Suite. Running unit tests in Node will run both when.js's own test suite, and the Promises/A+ Test Suite.

1. npm install
2. npm test

Browsers

1. npm install
2. npm start - starts buster server & prints a url
3. Point browsers at /capture, e.g. localhost:1111/capture
4. npm run-script test-browser

References

Much of this code was inspired by the async innards of wire.js, and has been influenced by the great work in Q, Dojo's Deferred, and uber.js.