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, is under 1.5k when compiled with Google Closure + gzip, and has no external dependencies.

What's New?

2.1.0

• New when.settle that settles an array of promises
• New when/guard generalized concurrency guarding and limiting
• New promise.inspect for synchronously getting a snapshot of a promise's state at a particular instant.
• Significant performance improvements when resolving promises with non-primitives (e.g. with Arrays, Objects, etc.)
• Experimental vert.x support
• DEPRECATED: onFulfilled, onRejected, onProgress handler arguments to when.all, when.any, when.some. Use the returned promise's then() (or otherwise(), ensure(), etc) to register handlers instead.
  • For example, do this: when.all(array).then(onFulfilled, onRejected) instead of this: when.all(array, onFulfilled, onRejected). The functionality is equivalent.

2.0.1

• Account for the fact that Mocha creates a global named process. Thanks Narsul

2.0.0

• Fully asynchronous resolutions.
• Promises/A+ compliance.
• New when/keys module with all() and map() for object keys/values.
• New promise.ensure as a better, and safer, replacement for promise.always. See discussion as to why promise.always is mistake-prone.
  • DEPRECATED: promise.always
• lift() is now the preferred name for what was bind() in when/function, when/node/function, and when/callbacks.
  • DEPRECATED: bind() in when/function, when/node/function, and when/callbacks. Use lift() instead.

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.