higher order flow control functions for creating generators
Higher order flow control functions for creating generators
Compose coroutines and koa middleware using higher order functions!
npm install shen
in beta
There’s still alot of work to be done on this repo. I’m putting it out there
for people to try out early and let you all get a taste of what’s to come.
If you’d like to contribute, I’d love ideas for things to implement.
Its a brave new world so lets find out what makes sense!
Tests are also very much appreciated.
you can run the tests supplied with
npm install
mocha --harmony test
Make sure to have node 0.11 installed or you’ll be a sad panda!
Higher order functions for generators
Generators are the new concurrency primitive slated for ecmascript 6.
There is scant information on how generators work. The one really useful
library I’ve seen out there is TJHollowaychuck’s co module.
var co = require('co');
co(function *() {
var data = yield someAsyncTask();
doStuffWithData(data);
return data;
})();
Shen is a set of tools for constructing generators from smaller generators. Through
composition, Shen allows you to assemble coroutines from smaller coroutines. The asynchronous
code even looks synchronous and the shnozberries taste like shnozberries!
They are all nestable so you can build arbitrarily large generators from smaller ones like
lego pieces.
shen.bind(gen, ctx, [arg1, arg2 …]);
Takes a generator and binds it to the context, optional args are partially applied to the
returned generator.
var shen = require('shen');
var boundGenerator = shen.bind(context, function *() {
//etc
});
shen.cascade(gen1, gen2…genN);
Takes one or more generators and returns a new generator that can be passed
into a coroutine function. each generator is passed a next which allows you
to yield downstream to the next generator on the list.
it('should pass returned values to the next function', function(done) {
var list = [];
var genFunc = shen.cascade(
function *(next) {
list.push(1);
var b = yield next;
list.push(3);
return b;
},
shen.cascade(
function *(next) {
list.push(2);
return yield next;
},
function *() {
list.push(7);
return 'ret';
}));
co(genFunc)(function(err, val) {
list.should.have.property('0', 1);
list.should.have.property('1', 2);
list.should.have.property('2', 7);
list.should.have.property('3', 3);
val.should.equal('ret');
done();
});
});
shen.branch(cond, path1, path2)
Takes a three generators. The first one receives links to the other two.
With this you can set up conditional branches to either path1 or path2.
it('should yield to the second argument', function(done) {
var stub;
var genFunc = shen.branch(
function *(path1, path2) {
yield path1;
stub.should.equal(5);
},
function *(next) {
stub = 5;
},
function *() {
stub = 6;
});
co(genFunc)(done);
});
it('should yield to the third argument', function(done) {
var stub;
var genFunc = shen.branch(
function *(path1, path2) {
yield path2;
stub.should.equal(6);
},
function *(next) {
stub = 5;
},
function *() {
stub = 6;
});
co(genFunc)(done);
});
shen.dispatch(gen, map)
Takes a generator and an object of generators. Inside gen, you can yield control
to one of the generators inside the map.
it('should dispatch to a branch', function(done) {
var genFunc = shen.dispatch(function *(paths) {
var foo = yield paths['fuu'];
return foo;
}, {
fuu: function *() {
return 'yeaaaa';
}
});
co(genFunc)(function(err, value) {
value.should.equal('yeaaaa');
done();
});
});
shen.parallel(gen1, gen2, gen3… genN)
Takes one or more generators. All the generators are run asynchronously. The
returned values can be returned upstream into an array yielded from the generators
yielding to the parallel generator.
var genFunc = shen.cascade(function *(next) {
var vals = yield next;
return vals;
},
shen.parallel(
function *() {
return yield request('http://www.google.com').then(function() {
//console.log('wierd', arguments[0][1]);
return arguments[0][1];
});
},
function *() {
return 'two';
}));
co(genFunc)(function(err, val) {
var countOne = !!val[0].match('google');
countOne.should.be.true;
var countTwo = val[1] === 'two';
countTwo.should.be.true;
done();
});
shen.delay(gen, timeout)
Takes a generator and timeout. it returns a generator that runs the
passed in generator after the timeout.
it('should delay timeout', function(done) {
this.timeout(10000);
var timeStamp = Date.now();
//defer = Promise.defer();
var start = Date.now();
//defer.resolve('resolved');
var genFunc = function *() {
var delay = Date.now() - timeStamp;
return delay;
};
co(shen.delay(genFunc, 3000))(function (err, delay) {
delay.should.be.greaterThan(2950);
done();
});
});
shen.oscillator(gen, interval)
Takes a generator and returns a generator which returns an eventEmitter that
calls a function with the return values from calling gen at specified intervals.
it('should run run the function over and over', function(done) {
this.timeout(10000);
var i = 0;
var test = function() { i++; };
var genFunc = shen.oscillator(function *() {
test();
}, 500);
co(genFunc)();
setTimeout(function() {
i.should.be.greaterThan(5);
done();
}, 6000);
});
xit('should let me stop the oscillation with stopTick()', function(done) {
this.timeout(10000);
var i = 0;
var test = function() { i++; };
var genFunc = shen.oscillator(function *() {
test();
}, 500);
co(genFunc)();
setTimeout(function(err, val) {
i.should.be.greaterThan(5);
done();
}, 6000);
});
Koa compatibility
You can compose together koa middleware using shen functions.
The follow example shows how returns up the middleware chain are gracefully
passed up.
var koa = require('koa');
var app = koa();
var shen = require('shen');
app.use(function *(next) {
this.status = 200;
this.body = yield next;
});
var foo = shen.cascade(
function *(next) {
return (yield next) + 6;
},
shen.branch(function *( path1, path2) {
return (yield path2)+ 5;
},
function *(next) {
//this never runs
return (yield next);
},
shen.cascade(
function *(next) {
return (yield next) + 4;
},
function *(next) {
return (yield next) + 3;
},
function *(next) {
return (yield next) + 2;
})),
function *(next) {
return (yield next) + 1;
});
app.use(foo);
app.use(function *() {
return "hello world ";
});
console.log('now listening on port 3000');
app.listen(3000);
You should see ‘hello world 123456’ in your browser!