when.js

When.js is cujojs's lightweight CommonJS Promises/A and when() implementation, derived from the async core of wire.js, cujojs's IOC Container. It also provides several other useful Promise-related concepts, such as joining multiple promises, mapping and reducing collections of promises, timed promises, and has a robust unit test suite.

It passes the Promises/A Test Suite, is frighteningly fast, and is around 1.4k when compiled with Google Closure (w/advanced optimizations) and gzipped, and has no external dependencies.

What's New?

1.8.1

• Last 1.x.x release before 2.0.0 barring critical fixes.
  • To prepare for 2.0.0, test your code against the dev-200 branch. It is fully API compatible, but has fully asynchronous resolutions.
• Performance improvements for when/function.
• Documentation updates and fixes. Thanks, @unscriptable!
• DEPRECATED: deferred.progress and deferred.resolver.progress. Use deferred.notify and deferred.resolver.notify instead.
• DEPRECATED: when.chain. Use resolver.resolve(promise) or resolver.resolve(promise.yield) (see promise.yield) instead.
• DEPRECATED: when/timed module. Use when/delay and when/timeout modules instead.

1.8.0

• New when/function, when/node/function, and when/callbacks with functional programming goodness, and adapters for turning callback-based APIs into promise-based APIs. Kudos @riccieri!
• New when/unfold, and when/unfold/list promise-aware anamorphic unfolds that can be used to generate and/or process unbounded lists.
• New when/poll promise-based periodic polling and task execution. Kudos @scothis!

1.7.1

• Removed leftover internal usages of deferred.then.
• when/debug allows configuring the set of "fatal" error types that will be rethrown to the host env.

1.7.0

• DEPRECATED: deferred.then is deprecated and will be removed in an upcoming release. Use deferred.promise.then instead.
• promise.yield(promiseOrValue) convenience API for substituting a new value into a promise chain.
• promise.spread(variadicFunction) convenience API for spreading an array onto a fulfill handler that accepts variadic arguments. Mmmm, buttery
• Doc improvements:
  • when() and promise.then() have more info about callbacks and chaining behavior.
  • More info and clarifications about the roles of Deferred and Resolver
  • Several minor clarifications for various APIs
• Internal improvements to assimilation and interoperability with other promise implementations.

Full Changelog

Docs & Examples

API docs

More info on the wiki

Examples

Quick Start

AMD

1. 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, ...) { ... });

Script Tag

1. git clone https://github.com/cujojs/when or git submodule add https://github.com/cujojs/when
2. <script src="path/to/when/when.js"></script>
3. when will be available as window.when

Node

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

RingoJS

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

Running the Unit Tests

Node

Note that when.js includes @domenic's 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 @unscriptable's tiny promises, the async innards of wire.js, and some gists here, here, here, and here

Some of the code has been influenced by the great work in Q, Dojo's Deferred, and uber.js.