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

A lightweight CommonJS Promises/A and when() implementation. It also provides several other useful Promise-related concepts, such as joining and chaining, and has a robust unit test suite.

It's just over 1k when compiled with Google Closure (w/advanced optimizations) and gzipped.

when.js was derived from the async core of wire.js.

What's New?

1.4.4

• Change UMD boilerplate to check for exports to avoid a problem with QUnit. See #54 for more info.

1.4.3

• Fix for infinite promise coercion between when.js and Q (See #50). Thanks @kriskowal and @domenic

1.4.2

• Fix for IE8 infinite recursion (See #49)

1.4.1

• Code and unit test cleanup and streamlining--no functional changes.

1.4.0

• Create a resolved promise: when.resolve(value) creates a resolved promise for value. See API docs.
• Resolve/reject return something useful: deferred.resolve and deferred.reject now return a promise for the fulfilled or rejected value.
• Resolve a deferred with another promise: deferred.resolve(promise) - when promise resolves or rejects, so will deferred.

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

Install buster.js

npm install -g buster

Run unit tests in Node:

1. buster test -e node

Run unit tests in Browsers (and Node):

1. buster server - this will print a url
2. Point browsers at /capture, e.g. localhost:1111/capture
3. buster test or buster test -e 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.

Changelog

1.4.4

• Change UMD boilerplate to check for exports to avoid a problem with QUnit. See #54 for more info.