> functors@2.3.1 doc /home/wojtek/gits/functors
> coffee doc.coffee


delay:
-----------
# `delay( syncFun )` turns `syncFun` into an async function.
#
# `delay(syncFun, timeout = 0)` defines an async function,
# which, when called, will be execuded with delay `timeout`.

compose:
-----------
# `compose(asyncFn1, asyncFn2, ...)` composes the asynchronous functions
# `asyncFn1`, `asyncFn2`, ...

product:
-----------
# `product(asyncFn1, asyncFn2, ..., asyncFnk)` generates a new async function
# which takes an array of k elements and a callback `cb` as arguments, runs
# the async functions with the elements of the array. Finnaly, it calls `cb`
# with the array of results

map:
-----------
# `map(asyncFn)` generates a new async function which takes an array of
# k elements and a callback `cb` as arguments, runs the async function
# with every element of the array. Finnaly, it calls `cb`
# with the array of results

merge:
-----------
# `merge(afn1, afn2, ...)` transforms `afn1, afn2, ...` into a new
# async function which takes two arguments, `[a1, a2, ...], cb`. 
# It tries to  execute `afn1(a1,cb)` and if error occurs, it tries
# `afn2(a2, cb)`, and so on, till one of the calls does not generate
# an error.

concurrent:
-----------
# `concurrent(aFn1, aFn2, ..., aFnk)` generates a new async function
# which takes an array of k elements and a callback `cb` as arguments,
# runs the functions cuncurrently with the elements of the array,
# respectively.
# The first function which succeeds, (err = null), calls `cb`
# with its results.

semaphore:
-----------
#  `semaphore(maxRunning = 10)` constructs a 'semaphore' which is a
#  function `function(afn, context)` that creates a new async
#  function which behaves as its argument `afn`. If there are already
#  `maxRunning` functions running against the semaphore, the execution
#  is delayed.

retry:
-----------
#    `retry(asyncFun)` transforms `asyncFun` into another async function
# which will try executing `asyncFun` twice, if an error occurs, before
# calling its `callback`. Actually, the signature is:
#   `retry(asyncFun,times=2,interval=500)`
# and it returns an async function.

throttle:
-----------
#  `throttle(fn, waitTime = 2000)` constructs a function, which behaves
#  as its argument `fn`, unless it is called in intervals smaller than `waitTime`.
#  In that case only the last call within that `waiting time` will be made.

LazyValue:
-----------
# `value = new LazyValue( fetch_fn )` creates a read only value initialized
# by an async `fetch_fn`. The value is read by `value.get( cb )`.  E.g.:
#
#   > var val = new LazyValue(function(cb){fs.readFile('/etc/passwd', cb);});
#   > val.get( function( err, data ){ console.log(data.toString() ) });
#
# There is also a helper method `select`:
# `select(obj, path, cb)` a field `obj.path` in `obj` which may contain
# `LazyValue`s.
# The callback `cb(err,val)` is called once value `val` of `obj.path`
# is retrived or error occurs.

Maker:
-----------
#     maker = new Maker(spec)
#  constructs a DAG of 'targets'. Ex:
#     var Maker = require('functors/Maker'),
#       maker = new Maker({
#         a: (_,cb) => cb(null, 12),
#         b: {deps: 'a',
#             value: function(deps,cb) { cb(null, deps.a + 1); }}});
#      maker.get('a','b', (err, result) => console.log(result))
#     // should print: `[12, 13]`

helpers:
-----------
# Helper (synchronous) functions:
#  flatten: e.g., [[1,2],3,4] -> [1,2,3,4] 
#  isArray: e.g., [1,2,3] -> true
#  isNumber: e.g., 0 -> true 
#  isString: e.g., 123 -> false
#  isFunction: ...
#  isEmpty: e.g., {} -> true, [] -> true, ""-> true, but 0 -> false