# when

> A lightweight Promises/A+ and when() implementation, plus other async goodies.

Latest version **3.7.8** (published 2017-02-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install when
pnpm add when
yarn add when
bun add when
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.7.8 |
| Published | 2017-02-20 |
| First published | 2012-05-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/when) |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3420 |
| Maintainers | cujojs |
| Keywords | cujo, Promises/A+, promises-aplus, promise, promises, deferred, deferreds, when, async, asynchronous, ender |

## Links

- npm: https://www.npmjs.com/package/when
- Repository: https://github.com/cujojs/when
- Homepage: http://cujojs.com
- Issues: https://github.com/cujojs/when/issues
- npm.io page: https://npm.io/package/when

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 3.7.8 (latest) — 2017-02-20
- 3.7.7 — 2015-12-24
- 3.7.6 — 2015-12-23
- 3.7.5 — 2015-11-21
- 3.7.4 — 2015-10-24
- 3.7.3 — 2015-04-27
- 3.7.2 — 2015-01-30
- 3.7.1 — 2015-01-28
- 3.7.0 — 2015-01-26
- 3.6.4 — 2014-12-14
- 3.6.3 — 2014-11-14
- 3.6.2 — 2014-11-13
- 3.6.1 — 2014-11-11
- 3.6.0 — 2014-11-07
- 3.5.2 — 2014-10-29
- … 48 more at https://npm.io/package/when/versions

## README

<a href="http://promises-aplus.github.com/promises-spec"><img src="http://promises-aplus.github.com/promises-spec/assets/logo-small.png" alt="Promises/A+ logo" align="right" /></a>

[![Build Status](https://travis-ci.org/cujojs/when.svg?branch=master)](https://travis-ci.org/cujojs/when)
[![Inline docs](http://inch-ci.org/github/cujojs/when.svg?branch=master)](http://inch-ci.org/github/cujojs/when)

when.js
=======

When.js is a rock solid, battle-tested [Promises/A+](http://promises-aplus.github.com/promises-spec) and `when()` implementation, including a complete [ES6 Promise shim](docs/es6-promise-shim.md).  It's a powerful combination of small size, high performance, debuggability, and rich features:

* Resolve arrays and hashes of promises, as well as infinite promise sequences
* Execute tasks in parallel or sequentially
* Transform Node-style and other callback-based APIs into promise-based APIs

When.js is one of the many stand-alone components of [cujoJS](http://cujojs.com), the JavaScript Architectural Toolkit. 

Check it out:

- [What's new](CHANGES.md)
- [API docs](docs/api.md#api)
- Read more about how [promises simplify async programming](http://know.cujojs.com/tutorials/async/simplifying-async-with-promises)

Installation
------------

#### AMD

Available as `when` through [bower](http://bower.io), or just clone the repo and load `when.js` from the root.

```
bower install --save when
```

#### CommonJS/Node

```
npm install --save when
```

[More help & other environments &raquo;](docs/installation.md)

Usage
-----

Promises can be used to help manage complex and/or nested callback flows in a simple manner. To get a better handle on how promise flows look and how they can be helpful, there are a couple examples below (using commonjs).

This first example will print `"hello world!!!!"` if all went well, or `"drat!"` if there was a problem. It also uses [rest](https://github.com/cujojs/rest) to make an ajax request to a (fictional) external service.

```js
var rest = require('rest');

fetchRemoteGreeting()
    .then(addExclamation)
    .catch(handleError)
    .done(function(greeting) {
        console.log(greeting);
    });

function fetchRemoteGreeting() {
    // returns a when.js promise for 'hello world'
    return rest('http://example.com/greeting');
}

function addExclamation(greeting) {
    return greeting + '!!!!'
}

function handleError(e) {
    return 'drat!';
}
```

The second example shows off the power that comes with when's promise logic. Here, we get an array of numbers from a remote source and reduce them. The example will print `150` if all went well, and if there was a problem will print a full stack trace.

```js
var when = require('when');
var rest = require('rest');

when.reduce(when.map(getRemoteNumberList(), times10), sum)
    .done(function(result) {
        console.log(result);
    });

function getRemoteNumberList() {
    // Get a remote array [1, 2, 3, 4, 5]
    return rest('http://example.com/numbers').then(JSON.parse);
}

function sum(x, y) { return x + y; }
function times10(x) {return x * 10; }
```

License
-------

Licensed under MIT. [Full license here &raquo;](LICENSE.txt)

Contributing
------------

Please see the [contributing guide](CONTRIBUTING.md) for more information on running tests, opening issues, and contributing code to the project.

References
----------

Much of this code was inspired by the async innards of [wire.js](https://github.com/cujojs/wire), and has been influenced by the great work in [Q](https://github.com/kriskowal/q), [Dojo's Deferred](https://github.com/dojo/dojo), and [uber.js](https://github.com/phiggins42/uber.js).

---
_Source: https://npm.io/package/when · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._