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'.
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.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
-
git clone https://github.com/cujojs/when
or git submodule add https://github.com/cujojs/when
-
Configure your loader with a package:
packages: [
{ name: 'when', location: 'path/to/when/', main: 'when' },
]
-
define(['when', ...], function(when, ...) { ... });
or require(['when', ...], function(when, ...) { ... });
Script Tag
git clone https://github.com/cujojs/when
or git submodule add https://github.com/cujojs/when
<script src="path/to/when/when.js"></script>
when
will be available as window.when
Node
npm install when
var when = require('when');
RingoJS
ringo-admin install cujojs/when
var when = require('when');
Running the Unit Tests
Install buster.js
npm install -g buster
Run unit tests in Node:
buster test -e node
Run unit tests in Browsers (and Node):
buster server
- this will print a url- Point browsers at /capture, e.g.
localhost:1111/capture
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.