API Documentation

####go #####ceci.go(gen, args...)

Executes a go block. The first argument must be an ES6 generator (created via function*), which is called with the remaining arguments. Go blocks run uninterrupted until a yield is encountered, at which point control is passed to the next (possibly the same) go block that is able to continue.

Returns a deferred value (see below) which is eventually resolved with the return value of the specified generator.

var gen = function*(name) { console.log('Goodbye'); yield null; console.log(name + '!'); };
ceci.go(gen, 'callbacks');
ceci.go(function*() { console.log('cruel'); });
// prints "Goodbye", then "cruel", then "callbacks!"

####defer #####ceci.defer()

Creates a deferred value. A deferred value can be resolved with a value via the resolve method or rejected with an error object via the reject method. Prefixing a deferred value with the yield keyword blocks the current go block until the value is resolved.

A deferred value can be resolved or rejected no more than once, and can be used with a yield no more than once. The method isResolved can be used to test without blocking whether a deferred value has been resolved or not, but there is no supported way to retrieve its value without a yield.

var result = ceci.defer();
ceci.go(function*() { console.log('Waiting...'); console.log(yield result); });
ceci.go(function*() { result.resolve(1); console.log('Resolved!'); });
// prints "Waiting...", then "Resolved!", then 1

####longStackSupport #####ceci.longStackSupport (new in 0.2.0)

Enables stack rewriting when passing exceptions out of go blocks. This provides more readable stack traces that reflect dynamic calling relationships of go block, but effects an additional memory and runtime cost per go block execution.

ceci.longStackSupport = true;

ceci.top(ceci.go(function*() {
  return yield ceci.go(function*() {
    return yield ceci.go(function*() {
      throw new Error('Oops!');
    });
  });
}));

####top #####ceci.top(deferred) (new in 0.2.0)

Registers a callback on the given deferred that prints a stack trace in case of rejection. This is a utility function that simulates the familiar behaviour of uncaught exceptions in code outside of go blocks.

ceci.top(ceci.go(function*() {
  throw new Error('Oops!');
}));

####join #####ceci.join(deferreds) (new in 0.2.0)

Accepts an array of deferred values and returns a single deferred that will be resolved to an array of the results.

var delay = function(ms, val) { return ceci.go(function*() { yield ceci.sleep(ms); return val; }) };
ceci.go(function*() { console.log(yield ceci.join([delay(200, 2), delay(1000, 3), delay(500, 5)])); });
// pauses for a second, then prints [2, 3, 5]

####lift #####ceci.lift(fn, thisBinding)

Creates an asynchronous wrapper around an ordinary function. Arguments to the wrapped function can be an arbitrary mix of immediate and deferred values, and the result is a deferred value.

var asyncArray = ceci.lift(Array);
var delay = function(ms, val) { return ceci.go(function*() { yield ceci.sleep(ms); return val; }) };
ceci.go(function*() { console.log(yield asyncArray(delay(200, 2), delay(1000, 3), delay(500, 5))); });
// pauses for a second, then prints [2, 3, 5]

####chain #####ceci.chain(start, forms...)

Executes a chain of function calls and returns a deferred value which is eventually resolved with the final result. Start value and intermediate values can be deferred, in which case the next function in the chain is called with the resolved value (via yield). The first argument specifies the start value, each subsequent argument is a form consisting of a function to be called and optionally further arguments to the call.

In the simplest case, a form is just a function object, which is executed with the current value as its sole argument. A form can also be an array consisting of a function, a single argument or array of arguments to be inserted before the current value, and all remaining arguments to be inserted after. Finally, it can be an array starting with a string, in which case the corresponding method is called on the current value, with the remain array elements as arguments.

A form that is none of the above simply replaces the current value with itself.

var plus = function(a, b) { return a + b; };
var div = function(a, b) { return a / b; };
ceci.chain(
  ceci.go(function*() { yield ceci.sleep(1000); return 5; }),
  [ceci.lift(plus), 3],       // x -> ceci.lift(plus)(3, yield x)
  [ceci.lift(div), [], 2],    // x -> ceci.lift(div)(yield x, 2)
  console.log);               // x -> console.log(yield x)
// pauses for a second, then prints 4

####sleep #####ceci.sleep(ms)

Returns a deferred value that is resolved after the specified number of miliseconds.

ceci.go(function*() { console.log('Hello'); yield ceci.sleep(1000); console.log('Ceci!'); });
// prints "Hello", pauses for a second, then prints "Ceci!"

####ncallback #####ceci.ncallback(deferred)

Creates a NodeJS-style callback which resolves or rejects the given deferred value as appropriate.

var result = ceci.defer();
require('dns').resolve('github.com', ceci.ncallback(result));
ceci.chain(result, console.log);
/// prints something like [ '192.30.252.129' ]

####nbind #####ceci.nbind(fn, thisBinding)

Creates a wrapper for a function following the NodeJS callback conventions. The wrapper returns a deferred value which is eventually resolved or rejected depending on the success of the call.

var dnsResolve = ceci.nbind(require('dns').resolve);
ceci.chain(dnsResolve('github.com'), console.log);
/// prints something like [ '192.30.252.129' ]

####nodeify #####ceci.nodeify(deferred, callback)

Registers a NodeJS-style callback function to be executed when the given deferred value is resolved or rejected. If no callback is given, returns the deferred value as is.

var result = ceci.chain(5);
ceci.nodeify(result, function(err, val) {
  if (err)
    throw new Error(err);
  else
    console.log(val);
});
/// prints 5