1 | # co
|
2 |
|
3 | [![Gitter][gitter-image]][gitter-url]
|
4 | [![NPM version][npm-image]][npm-url]
|
5 | [![Build status][travis-image]][travis-url]
|
6 | [![Test coverage][coveralls-image]][coveralls-url]
|
7 | [![Downloads][downloads-image]][downloads-url]
|
8 |
|
9 | Generator based control flow goodness for nodejs and the browser,
|
10 | using promises, letting you write non-blocking code in a nice-ish way.
|
11 |
|
12 | ## Co v4
|
13 |
|
14 | `co@4.0.0` has been released, which now relies on promises.
|
15 | It is a stepping stone towards [ES7 async/await](https://github.com/lukehoban/ecmascript-asyncawait).
|
16 | The primary API change is how `co()` is invoked.
|
17 | Before, `co` returned a "thunk", which you then called with a callback and optional arguments.
|
18 | Now, `co()` returns a promise.
|
19 |
|
20 | ```js
|
21 | co(function* () {
|
22 | var result = yield Promise.resolve(true);
|
23 | return result;
|
24 | }).then(function (value) {
|
25 | console.log(value);
|
26 | }, function (err) {
|
27 | console.error(err.stack);
|
28 | });
|
29 | ```
|
30 |
|
31 | If you want to convert a `co`-generator-function into a regular function that returns a promise,
|
32 | you now use `co.wrap(fn*)`.
|
33 |
|
34 | ```js
|
35 | var fn = co.wrap(function* (val) {
|
36 | return yield Promise.resolve(val);
|
37 | });
|
38 |
|
39 | fn(true).then(function (val) {
|
40 |
|
41 | });
|
42 | ```
|
43 |
|
44 | ## Platform Compatibility
|
45 |
|
46 | `co@4+` requires a `Promise` implementation.
|
47 | For versions of node `< 0.11` and for many older browsers,
|
48 | you should/must include your own `Promise` polyfill.
|
49 |
|
50 | When using node 0.11.x or greater, you must use the `--harmony-generators`
|
51 | flag or just `--harmony` to get access to generators.
|
52 |
|
53 | When using node 0.10.x and lower or browsers without generator support,
|
54 | you must use [gnode](https://github.com/TooTallNate/gnode) and/or [regenerator](http://facebook.github.io/regenerator/).
|
55 |
|
56 | io.js is supported out of the box, you can use `co` without flags or polyfills.
|
57 |
|
58 | ## Installation
|
59 |
|
60 | ```
|
61 | $ npm install co
|
62 | ```
|
63 |
|
64 | ## Associated libraries
|
65 |
|
66 | Any library that returns promises work well with `co`.
|
67 |
|
68 | - [mz](https://github.com/normalize/mz) - wrap all of node's code libraries as promises.
|
69 |
|
70 | View the [wiki](https://github.com/visionmedia/co/wiki) for more libraries.
|
71 |
|
72 | ## Examples
|
73 |
|
74 | ```js
|
75 | var co = require('co');
|
76 |
|
77 | co(function *(){
|
78 | // yield any promise
|
79 | var result = yield Promise.resolve(true);
|
80 | }).catch(onerror);
|
81 |
|
82 | co(function *(){
|
83 | // resolve multiple promises in parallel
|
84 | var a = Promise.resolve(1);
|
85 | var b = Promise.resolve(2);
|
86 | var c = Promise.resolve(3);
|
87 | var res = yield [a, b, c];
|
88 | console.log(res);
|
89 | // => [1, 2, 3]
|
90 | }).catch(onerror);
|
91 |
|
92 | // errors can be try/catched
|
93 | co(function *(){
|
94 | try {
|
95 | yield Promise.reject(new Error('boom'));
|
96 | } catch (err) {
|
97 | console.error(err.message); // "boom"
|
98 | }
|
99 | }).catch(onerror);
|
100 |
|
101 | function onerror(err) {
|
102 | // log any uncaught errors
|
103 | // co will not throw any errors you do not handle!!!
|
104 | // HANDLE ALL YOUR ERRORS!!!
|
105 | console.error(err.stack);
|
106 | }
|
107 | ```
|
108 |
|
109 | ## Yieldables
|
110 |
|
111 | The `yieldable` objects currently supported are:
|
112 |
|
113 | - promises
|
114 | - thunks (functions)
|
115 | - array (parallel execution)
|
116 | - objects (parallel execution)
|
117 | - generators (delegation)
|
118 | - generator functions (delegation)
|
119 |
|
120 | Nested `yieldable` objects are supported, meaning you can nest
|
121 | promises within objects within arrays, and so on!
|
122 |
|
123 | ### Promises
|
124 |
|
125 | [Read more on promises!](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
|
126 |
|
127 | ### Thunks
|
128 |
|
129 | Thunks are functions that only have a single argument, a callback.
|
130 | Thunk support only remains for backwards compatibility and may
|
131 | be removed in future versions of `co`.
|
132 |
|
133 | ### Arrays
|
134 |
|
135 | `yield`ing an array will resolve all the `yieldables` in parallel.
|
136 |
|
137 | ```js
|
138 | co(function* () {
|
139 | var res = yield [
|
140 | Promise.resolve(1),
|
141 | Promise.resolve(2),
|
142 | Promise.resolve(3),
|
143 | ];
|
144 | console.log(res); // => [1, 2, 3]
|
145 | }).catch(onerror);
|
146 | ```
|
147 |
|
148 | ### Objects
|
149 |
|
150 | Just like arrays, objects resolve all `yieldable`s in parallel.
|
151 |
|
152 | ```js
|
153 | co(function* () {
|
154 | var res = yield {
|
155 | 1: Promise.resolve(1),
|
156 | 2: Promise.resolve(2),
|
157 | };
|
158 | console.log(res); // => { 1: 1, 2: 2 }
|
159 | }).catch(onerror);
|
160 | ```
|
161 |
|
162 | ### Generators and Generator Functions
|
163 |
|
164 | Any generator or generator function you can pass into `co`
|
165 | can be yielded as well. This should generally be avoided
|
166 | as we should be moving towards spec-compliant `Promise`s instead.
|
167 |
|
168 | ## API
|
169 |
|
170 | ### co(fn*).then( val => )
|
171 |
|
172 | Returns a promise that resolves a generator, generator function,
|
173 | or any function that returns a generator.
|
174 |
|
175 | ```js
|
176 | co(function* () {
|
177 | return yield Promise.resolve(true);
|
178 | }).then(function (val) {
|
179 | console.log(val);
|
180 | }, function (err) {
|
181 | console.error(err.stack);
|
182 | });
|
183 | ```
|
184 |
|
185 | ### var fn = co.wrap(fn*)
|
186 |
|
187 | Convert a generator into a regular function that returns a `Promise`.
|
188 |
|
189 | ```js
|
190 | var fn = co.wrap(function* (val) {
|
191 | return yield Promise.resolve(val);
|
192 | });
|
193 |
|
194 | fn(true).then(function (val) {
|
195 |
|
196 | });
|
197 | ```
|
198 |
|
199 | ## License
|
200 |
|
201 | MIT
|
202 |
|
203 | [npm-image]: https://img.shields.io/npm/v/co.svg?style=flat-square
|
204 | [npm-url]: https://npmjs.org/package/co
|
205 | [travis-image]: https://img.shields.io/travis/tj/co.svg?style=flat-square
|
206 | [travis-url]: https://travis-ci.org/tj/co
|
207 | [coveralls-image]: https://img.shields.io/coveralls/tj/co.svg?style=flat-square
|
208 | [coveralls-url]: https://coveralls.io/r/tj/co
|
209 | [downloads-image]: http://img.shields.io/npm/dm/co.svg?style=flat-square
|
210 | [downloads-url]: https://npmjs.org/package/co
|
211 | [gitter-image]: https://badges.gitter.im/Join%20Chat.svg
|
212 | [gitter-url]: https://gitter.im/tj/co?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
|