when

What is when?

The 'when' npm package is a robust library for working with asynchronous programming in JavaScript, particularly using promises. It provides utilities for creating, managing, and composing promises, making it easier to handle asynchronous operations and their potential complexities.

What are when's main functionalities?

Creating Promises

This feature allows the creation of new promises. The code sample demonstrates how to create a simple promise that resolves with 'Hello, World!' after 1 second.

const when = require('when');
const promise = when.promise(function(resolve, reject) {
  setTimeout(() => resolve('Hello, World!'), 1000);
});
promise.then(response => console.log(response));

Chaining Promises

This feature demonstrates chaining multiple promises. It shows how to perform a series of tasks sequentially, where each task starts only after the previous one has completed.

const when = require('when');
const cleanRoom = () => when.promise(resolve => resolve('Room cleaned'));
const removeTrash = () => when.promise(resolve => resolve('Trash removed'));
const winIcecream = () => when.promise(resolve => resolve('Won ice cream'));
cleanRoom()
  .then(result => {
    console.log(result);
    return removeTrash();
  })
  .then(result => {
    console.log(result);
    return winIcecream();
  })
  .then(result => console.log(result));

Handling Errors

This feature involves error handling in promises. The code sample shows how to catch and handle errors that occur during the execution of promises.

const when = require('when');
const failTask = () => when.promise((resolve, reject) => reject('Failed task'));
failTask()
  .then(result => console.log('Success:', result))
  .catch(error => console.log('Error:', error));

Other packages similar to when

bluebird

Bluebird is a full-featured promise library with a focus on innovative features and performance. It is similar to 'when' but often cited for its superior performance and additional features like cancellation, progress tracking, and more detailed stack traces.

q

Q is one of the earliest promise libraries that influenced many others. It offers a similar API to 'when' but is generally considered to be less performant in modern applications. It provides a straightforward approach to handling asynchronous operations with promises.

promise

The 'promise' package provides a minimalist implementation similar to the ES6 Promise specification. It is more lightweight compared to 'when' but lacks some of the more advanced features and utilities provided by 'when'.

README

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

What's New?

1.6.1

• Fix for accidental coercion of non-promises. See #62.

1.6.0

• New when.join - Joins 2 or more promises together into a single promise.
• when.some and when.any now act like competitive races, and have generally more useful behavior. Read the discussion in #60.
• Experimental progress event propagation. Progress events will propagate through promise chains. Read the details here.
• Temporarily removed calls to Object.freeze. Promises are no longer frozen due to a horrendous v8 performance penalty. Read discussion here.
  • IMPORTANT: Continue to treat promises as if they are frozen, since freeze() will be reintroduced once v8 performance improves.
• when/debug now allows setting global a debugging callback for rejected promises.

1.5.2

• Integrate @domenic's Promises/A Test Suite. Runs via npm test.
• No functional change

1.5.1

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

1.5.0

• New task execution and concurrency management: when/sequence, when/pipeline, and when/parallel.
• Performance optimizations for when.all and when.map, 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

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.