kgo

kgo
===

Stupidly easy flow control.

Depricated

While kgo still works fine, I've since moved my efforts over to the much cleaner, faster, better tested, more flexible, and better maintained, righto, to which you can easily and incrementally migrate to if you want.

Why

flow contol should be seamless, you should be able to say what you want done, and say kgo.

Usage

`` javascript
kgo(result name, [dependencies], asynchronous function); // -> self
`

where result name is an arbitrary string that represents the result of the function,

dependencies is an array of strings that map to the result of another function,

and asynchronous function is a function that, when complete, calls a callback with it's results.

kgo returns its-self, so it can be chained:

` javascript
kgo
(name, deps, fn)
(name, deps, fn)
(name, deps, fn);
`

Example

require kgo:

` javascript
var kgo = require('./kgo');
`

use kgo:

` javascript
kgo
('things', function(done){

//Something async
setTimeout(function(){
done(null, 1);
}, 100);

})
('stuff', function(done){

//Something async
setTimeout(function(){
done(null, 2);
}, 100);

})
('whatsits', ['things', 'stuff'], function(things, stuff, done){

//Something async
setTimeout(function(){
done(null, things + stuff);
}, 100);

})
('dooby', ['things'], function(things, done){

//Something async
setTimeout(function(){
done(null, things/2);
}, 100);

})
(['whatsits', 'dooby'], function(whatsits, dooby, done){

//Done
console.log(whatsits, dooby);

});
`

The above will log 3, 0.5;

Async Mapping

Removed as of version 2. Use foreign instead.

Ignoring dependency results

You will often not need the result of a dependency, and it's annoying to have unused parameters in your functions.
You can specify that you have a dependency, whos result you don't want, by prefixing the dependency name with an exclamation mark:

` javascript
kgo

('a', function(done){
done(null, 'foo');
})

('b', ['!a'], function(done){
done(null, 'bar');
})

(['b'], function(b){
// here b will be "bar"
});
`

#### Note: Anonymous tasks will not be passed a done function:

`
kgo
('foo', getFoo) // getFoo will be passed (callback)
('bar', ['foo'], getFoo) // getFoo will be passed (bar, callback)
(['*', 'bar'], function(error, bar){
// arguments.length will be 2
})
`

Defaults

You can define default data for use in later tasks by passing an object into kgo, where the keys in the objects will map to dependency names:

` javascript
kgo

({
foo: 1
})

('bar', function(done){
done(null, 2);
})

('baz', ['foo', 'bar'], function(foo, bar, done){

});
`

This is especially useful when you want to use named functions that need additional parameters to run:

` javascript
var fs = require('fs');

kgo
({
'sourcePath': '/foo/bar'
})
('files', ['sourcePath'], fs.readdir);
`

$3

Multiple results

You can return more than one result in a single task by giving your task multiple names, and returning more results in the callback

` javascript
kgo

('foo', 'bar', function(done){
done(null, 2, 4);
})

('baz', ['foo', 'bar'], function(foo, bar, done){
// foo === 2
// bar === 4
});
`

kgo.sync

Sometimes you want to just run a synchonous function as a step in kgo, to do this you can use kgo.sync, which will return a callback-passing-style version.

` javascript

kgo
('task1', task1);
('task2', ['task1'], kgo.sync(function(x){ return x + 1 }))
('task3', ['task2'], task3);

`

Errors

You can handler errors from specific tasknames by prefixing the taskname with an astrix (*)

any task that has a dependency on any error task will resolve if any error dependency is resolved.

` javascript
kgo
('task1', task1)
('task2', task2)
(['*task1'], function(tast1error){
// Called if task1 errored
})
(['*task2'], function(tast2error){
// Called if task2 errored
})
(['task1', 'task2'], function(result1, result2){
// Called if task1 and task2 succeded.
});
`

there is an implicit error task, *, that will resolve to the first of any error that occurs.

` javascript
kgo
(task)
(another task)
(['*'], function(error){
// Called if any error occurs in any task
});
`

You can combine this with other dependencies to build a callback task:

` javascript
function doThings(callback){

kgo
('task1', ...)
('task2', ...)
('result', ['task1', 'task2'], ...)
(['*', 'result'], callback); // Will be called either if any task errors, OR if result resolves.

}
``