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, 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.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.