Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

94 lines (59 sloc) 4.709 kb

when.js Build Status

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 under 1.3k when compiled with Google Closure (w/advanced optimizations) and gzipped, and has no dependencies.

What's New?



  • Performance optimization for when.defer, up to 1.5x in some cases.
  • when/debug can now log exceptions and rejections in deeper promise chains, in some cases, even when the promises involved aren't when.js promises.


  • New task execution and concurrency management: when/sequence, when/pipeline, and when/parallel.
  • Performance optimizations for when.all and, up to 2x in some cases.
  • Options for disabling paranoid mode that provides a significant performance gain in v8 (e.g. Node and Chrome). See this v8 performance problem with Object.freeze for more info.
  • Important: deferred and deferred.resolver no longer throw when resolved/rejected multiple times. They will return silently as if the they had succeeded. This prevents parties to whom only the resolver has been given from using try/catch to determine the state of the associated promise.
    • For debugging, you can use the when/debug module, which will still throw when a deferred is resolved/rejected multiple times.

Full Changelog

Docs & Examples

API docs

More info on the wiki


Quick Start


  1. git clone or git submodule add
  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 or git submodule add
  2. <script src="path/to/when/when.js"></script>
  3. when will be available as window.when


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


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

Running the Unit Tests


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


  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


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.

Jump to Line
Something went wrong with that request. Please try again.