1 | <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>
|
2 |
|
3 | [![Build Status](https://travis-ci.org/cujojs/when.svg?branch=master)](https://travis-ci.org/cujojs/when)
|
4 | [![Inline docs](http://inch-ci.org/github/cujojs/when.svg?branch=master)](http://inch-ci.org/github/cujojs/when)
|
5 |
|
6 | when.js
|
7 | =======
|
8 |
|
9 | 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:
|
10 |
|
11 | * Resolve arrays and hashes of promises, as well as infinite promise sequences
|
12 | * Execute tasks in parallel or sequentially
|
13 | * Transform Node-style and other callback-based APIs into promise-based APIs
|
14 |
|
15 | When.js is one of the many stand-alone components of [cujoJS](http://cujojs.com), the JavaScript Architectural Toolkit.
|
16 |
|
17 | Check it out:
|
18 |
|
19 | - [What's new](CHANGES.md)
|
20 | - [API docs](docs/api.md#api)
|
21 | - Read more about how [promises simplify async programming](http://know.cujojs.com/tutorials/async/simplifying-async-with-promises)
|
22 |
|
23 | Installation
|
24 | ------------
|
25 |
|
26 | #### AMD
|
27 |
|
28 | Available as `when` through [bower](http://bower.io), or just clone the repo and load `when.js` from the root.
|
29 |
|
30 | ```
|
31 | bower install --save when
|
32 | ```
|
33 |
|
34 | #### CommonJS/Node
|
35 |
|
36 | ```
|
37 | npm install --save when
|
38 | ```
|
39 |
|
40 | [More help & other environments »](docs/installation.md)
|
41 |
|
42 | Usage
|
43 | -----
|
44 |
|
45 | 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).
|
46 |
|
47 | 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.
|
48 |
|
49 | ```js
|
50 | var rest = require('rest');
|
51 |
|
52 | fetchRemoteGreeting()
|
53 | .then(addExclamation)
|
54 | .catch(handleError)
|
55 | .done(function(greeting) {
|
56 | console.log(greeting);
|
57 | });
|
58 |
|
59 | function fetchRemoteGreeting() {
|
60 | // returns a when.js promise for 'hello world'
|
61 | return rest('http://example.com/greeting');
|
62 | }
|
63 |
|
64 | function addExclamation(greeting) {
|
65 | return greeting + '!!!!'
|
66 | }
|
67 |
|
68 | function handleError(e) {
|
69 | return 'drat!';
|
70 | }
|
71 | ```
|
72 |
|
73 | 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.
|
74 |
|
75 | ```js
|
76 | var when = require('when');
|
77 | var rest = require('rest');
|
78 |
|
79 | when.reduce(when.map(getRemoteNumberList(), times10), sum)
|
80 | .done(function(result) {
|
81 | console.log(result);
|
82 | });
|
83 |
|
84 | function getRemoteNumberList() {
|
85 | // Get a remote array [1, 2, 3, 4, 5]
|
86 | return rest('http://example.com/numbers').then(JSON.parse);
|
87 | }
|
88 |
|
89 | function sum(x, y) { return x + y; }
|
90 | function times10(x) {return x * 10; }
|
91 | ```
|
92 |
|
93 | License
|
94 | -------
|
95 |
|
96 | Licensed under MIT. [Full license here »](LICENSE.txt)
|
97 |
|
98 | Contributing
|
99 | ------------
|
100 |
|
101 | Please see the [contributing guide](CONTRIBUTING.md) for more information on running tests, opening issues, and contributing code to the project.
|
102 |
|
103 | References
|
104 | ----------
|
105 |
|
106 | 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).
|