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]
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.
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.
22 var result = yield Promise.resolve(true);
24 }).then(function (value) {
27 console.error(err.stack);
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*)`.
35 var fn = co.wrap(function* (val) {
36 return yield Promise.resolve(val);
39 fn(true).then(function (val) {
44 ## Platform Compatibility
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.
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.
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/).
56 io.js is supported out of the box, you can use `co` without flags or polyfills.
64 ## Associated libraries
66 Any library that returns promises work well with `co`.
68 - [mz](https://github.com/normalize/mz) - wrap all of node's code libraries as promises.
70 View the [wiki](https://github.com/visionmedia/co/wiki) for more libraries.
75 var co = require('co');
79 var result = yield Promise.resolve(true);
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];
92 // errors can be try/catched
95 yield Promise.reject(new Error('boom'));
97 console.error(err.message); // "boom"
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);
111 The `yieldable` objects currently supported are:
115 - array (parallel execution)
116 - objects (parallel execution)
117 - generators (delegation)
118 - generator functions (delegation)
120 Nested `yieldable` objects are supported, meaning you can nest
121 promises within objects within arrays, and so on!
125 [Read more on promises!](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
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`.
135 `yield`ing an array will resolve all the `yieldables` in parallel.
144 console.log(res); // => [1, 2, 3]
150 Just like arrays, objects resolve all `yieldable`s in parallel.
155 1: Promise.resolve(1),
156 2: Promise.resolve(2),
158 console.log(res); // => { 1: 1, 2: 2 }
162 ### Generators and Generator Functions
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.
170 ### co(fn*).then( val => )
172 Returns a promise that resolves a generator, generator function,
173 or any function that returns a generator.
177 return yield Promise.resolve(true);
178 }).then(function (val) {
181 console.error(err.stack);
185 ### var fn = co.wrap(fn*)
187 Convert a generator into a regular function that returns a `Promise`.
190 var fn = co.wrap(function* (val) {
191 return yield Promise.resolve(val);
194 fn(true).then(function (val) {
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