www.aleph1.co.uk Git - yaffs-website/blob - node_modules/co/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