pbarnes / when

A solid, fast Promises/A+ and when() implementation, plus other async goodies.

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

• Fix for when.defer().reject() bypassing the unhandled rejection monitor. (#166)
• Fix for when/function, when/callbacks, and when/node/function not preserving thisArg. (#162)
• Doc clarifications for promise.yield. (#164)

2.2.0

• New experimental promise monitoring and debugging via when/monitor/console.
• New when.promise(resolver) promise creation API. A lighter alternative to the heavier when.defer()
• New bindCallback and liftCallback in when/node/function for more integration options with node-style callbacks.

2.1.1

• Quote internal usages of promise.yield to workaround .NET minifier tools that don't yet understand ES5 identifier-as-property rules. See #157

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.