when
DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/when package

2.6.0 • Public • Published

Promises/A+ logo

Build Status

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 and compact, and has no external dependencies.

What's New?

2.6.0

  • New promise.done allows consuming the ultimate value at the end of a promise chain while ensuring that any errors are thrown to the host environment so you get loud stack traces.
  • when/node/function bindCallback and liftCallback now behave more like standard node-style APIs in that they allow exceptions to propagate to the host environment for loud stack traces.

2.5.1

  • ensure now ignores non-functions, like then does, for consistency. (#207)

2.5.0

2.4.1

  • New MutationObserver scheduler further reduces "time-to-first-handler" in modern browsers. (#198)
    • Also, this works around a horrible IE10 bug (desktop and mobile) that renders setImmediate, MessageChannel, and postMessage unusable as fast task schedulers. Many thanks to @plaa and @calvinmetcalf for their help in discovering the problem and working out a solution. (#197)

2.4.0

  • Experimental support for vert.x 2.x. Should now run in vert.x >= 1.1.0.
  • New when.isPromiseLike as the more accurately-named synonym for when.isPromise.
  • DEPRECATED: when.isPromise. It can only tell you that something is "promise-like" (aka "thenable") anyway. Use the new, more accurately-named when.isPromiseLike instead.
  • Fix for promise monitor reporting extra unhandled rejections for when.all and when.map.

2.3.0

  • New promise.tap for adding side effects to a promise chain.
  • New MessageChannel scheduler reduces "time-to-first" handler, in environments that support it.
  • Performance optimizations for promise resolution.
  • Internal architecture improvements to pave the way for when.js 3.0.0.

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.

Package Sidebar

Install

npm i when@2.6.0

Homepage

cujojs.com

Version

2.6.0

License

MIT

Last publish

Collaborators

  • cujojs