A set of yield handlers for Bluebird coroutines
npm install bluebird-cobluebird-co
=============
[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][npm-url]
[![MIT License][license-image]][npm-url]
[![Build Status][build-image]][build-link]
A set of high performance yield handlers for Bluebird coroutines.
async-to-module-method (or bluebirdCoroutines in Babel 5) transformer, you can write easy and comprehensive async/await functions.
npm install bluebird-co
npm install bluebird@3
javascript
require('bluebird-co');
`
and done.
Alternatively, manually adding the yield handler to Bluebird:
`javascript
var Promise = require('bluebird'),
bluebird_co = require('bluebird-co/manual');
Promise.coroutine.addYieldHandler(bluebird_co.toPromise);
var fn = Promise.coroutine(function*(){
//do stuff
});
fn().then(...);
`
In the automatic bootstrapping version, it actually executes the same first four lines of code as above to add the yield handler. Bluebird-co provides manual bootstrapping for control over the process if desired.
$3
Babel 6 provides the transform-async-to-module-method plugin which can pass a generator to a function to convert it to an asynchronous coroutine. Using bluebird-co instead of the default Bluebird install will automatically bootstrap the yield handler while remaining completely transparent.
.babelrc file
`javascript
{
"plugins": [
["transform-async-to-module-method", {
"module": "bluebird-co",
"method": "coroutine"
}]
]
}
`
ES7 file to be transformed
`javascript
async function fn() {
//do stuff
}
fn().then(...);
`
Example coroutines
Note: bluebird-co has to be added to Bluebird via automatic bootstrapping or manual addition before these snippets can work.
`javascript
var Promise = require('bluebird');
var fs = Promise.promisifyAll(require('fs'));
var myAsyncFunction = Promise.coroutine(function*() {
var results = yield [Promise.delay( 10 ).return( 42 ),
readFileAsync( 'index.js', 'utf-8' ),
[1, Promise.resolve( 12 )]];
console.log(results); //[42, "somefile contents", [1, 12]]
});
myAsyncFunction().then(...);
`
$3
`javascript
import Promise from 'bluebird';
import {readFile} from 'fs';
let readFileAsync = Promise.promisify(readFile);
async function myAsyncFunction() {
let results = await [Promise.delay( 10 ).return( 42 ),
readFileAsync( 'index.js', 'utf-8' ),
[1, Promise.resolve( 12 )]];
console.log(results); //[42, "somefile contents", [1, 12]]
}
myAsyncFunction().then(...);
`
$3
`javascript
import {co} from 'bluebird-co';
co(...);
co.wrap(...);
`
##### For more examples, see the tj/co README and the Bluebird Coroutines API.
Yieldable Types
* Promises
* Arrays
* Objects
* Generators and GeneratorFunctions
* Iterables (like new Set([1, 2, 3]).values())
* Functions (as Thunks)
* Custom data types via .addYieldHandler(fn)#addyieldhandlerfn--function
* Any combination or nesting of the above.
Custom yieldable types
It may become desirable to add custom yield handling for types not listed above based on the needs of a certain application. To make this easy, bluebird-co provides an analogue to Bluebird's [Bluebird.coroutine.addYieldHandler that works together in combination with the above yield handlers.
To do this, bluebird-co provides the .coroutine.addYieldHandler(fn) function, or just .addYieldHandler(fn) for short. The first is for strict compatibility with Bluebird.
Example of automatically fetching model data by yielding the model instance:
`javascript
import {coroutine} from 'bluebird-co';
class MyModel {
async fetch() {
//do stuff
return data;
}
}
coroutine.addYieldHandler(function(value) {
if(value instanceof MyModel) {
return value.fetch();
}
});
async function test() {
let model = new MyModel();
let data = await model; //calls model.fetch() and waits on it.
}
`
Additionally, you can even access the array of yield handlers manually if you ever need to remove one, like so:
`javascript
console.log(coroutine.yieldHandlers); //array of functions
`
#### Caveats:
Although this works for most classes and even null, it will NOT work if the class inherits from Object or if Object is in the prototype chain for the value's constructor. If it inherits from Object, it will be considered an Object instance and processed like any other object. Values without any constructor property will be considered an Object, as well.
API
All functions and properties listed below are exported by the bluebird-co module.
-----
##### .toPromise(value : any) -> Promise
toPromise is the central function of bluebird-co. It takes any of the supported yieldable types (and those added via .addYieldHandler), and attempts to convert it to a Promise. Any Promises within the value are resolved before the returned Promise resolves.
In the event that the given value cannot be transformed into a Promise, like when it is not in the possible yieldable types, the original value is returned. When used in conjunction with Bluebird coroutines, Bluebird will throw an error because the value is not a Promise instance.
-----
##### .addYieldHandler(fn : Function)
alias: .coroutine.addYieldHandler(fn : Function)
Very similar to Bluebird.coroutine.addYieldHandler, .addYieldHandler allows custom types to be processed by bluebird-co in conjunction with any other yieldable types, even other custom yield handlers. This includes nested yieldable types.
Aside from the caveats of Object types when using custom yield handlers, any other type or value can be handled, even null, undefined, Symbols, anything. However, built-in yield handlers cannot be overridden.
See the above section on Custom yieldable types for an example.
-----
##### .coroutine(gfn : -> Function
alias: .wrap(gfn : -> Function
alias: .co.wrap(gfn : -> Function
This calls Bluebird.coroutine and returns the resulting function. When called, the returned function will return a Promise.
The .wrap alias is provided to be a drop-in replacement for co.wrap.
-----
##### .execute(gfn : -> Promise
alias: .co(gfn : -> Promise
This calls [.coroutine](), then invokes the resulting function with the arguments provided, or just runs the generator object directly.
It is meant as a drop in replacement for tj/co co, like so:
`javascript
//import {co} from 'bluebird-co';
var co = require('bluebird-co').co;
function* do_stuff(num) {
return num;
}
co(do_stuff, 10).then(function(result){
console.log(result); //10
});
`
-----
##### .coroutine.yieldHanlders -> Array
Exposes all custom yield handlers that have been added.
bluebird-co expects this to be an array, so don't overwrite it with something silly.
-----
##### .isThenable(value : any) -> boolean
alias: .isPromise(value : any) -> boolean
`javascript
function isThenable(value) {
return value && typeof value.then === 'function';
}
`
-----
##### .isGenerator(value : any) -> boolean
Checks if the value is a generator instance with .next and .throw.
-----
##### .isGeneratorFunction(value : any) -> boolean
Checks if the value is a GeneratorFunction.
-----
Changelog
##### 2.2.0
* Allow .co to accept generators and generator functions like tj/co does. (thanks pkaminski)
##### 2.1.2
* Add .co.wrap alias for .wrap
##### 2.1.1
* Add simple quickstart section to README
* Add usage docs with Babel 6
##### 2.1.0
* Added .execute/.co functions.
* ~~(BUILD)~~(FIXED) As of this release, the build is failing only because Babel runtime is screwed up.
##### 2.0.0
* Improve docs
* Upgrade to Bluebird 3.0
* Upgrade to Babel 6 for build system
* (MAJOR) Change behavior of classes that inherit from Object
* Small internal improvements
##### 1.3.1 - 1.3.2
* Significantly improve performance of iterables.
##### 1.3.0
* Basic support for Iterables
##### 1.2.0
* Allow manual addition of the yield handler via requiring bluebird-co/manual
* Exposed toPromise function in extra API
##### 1.1.2 - 1.1.12
* Optimizations and bugfixes
##### 1.1.1
* Don't export isNativeObject, because it isn't generic enough to use in most places, only internally under the right circumstances.
##### 1.1.0
* Differentiate between native objects and class instances. Fixes addYieldHandler` functionality when used with class instances, but does not accept class instances as objects when there is not a handler for them.