Readme.md
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