uchain v0.17.0

uchain

A tiny library for chaining functions asynchronously.

  let chain = InSeries(
    InParallel(
      (next, a, b) => next(null, a + b),
      (next, a, b) => next(null, a - b),
    ),
    (next, [ sum ], [ difference ]) => next(null, sum * difference),
    (next, result) => console.log('asynchronous math', result)
  );

  chain(null, 1, 2); // prints out -3, eventually

Links in the chain

There are two function signatures expected by uchain. Every 'task' in the chain takes in a next function, and then any number of arguments.

function (next, ...args) {...}

Every 'next' function is a callback, that takes in an error parameter, and then any number of results; These results are passed to the next link in the chain.

function (err, ...results) {...}

The utilities provided in the library generate next functions to bind your tasks together asynchronously.

API

Objects

Typedefs

uchain : object

Kind: global namespace

• uchain : object
  • .FromPromise ⇒ taskFunction
  • .ToPromise ⇒ function
  • .Assert(validator, message) ⇒ taskFunction
  • .CatchError(task) ⇒ taskFunction
  • .If(conditionTask, thenTask, elseTask) ⇒ taskFunction
  • .InOrder(...tasks) ⇒ taskFunction
  • .InParallel(...tasks) ⇒ taskFunction
  • .InSeries(...tasks) ⇒ taskFunction
  • .Logging(...statements) ⇒ taskFunction
  • .ParallelFilter(filter) ⇒ taskFunction
  • .ParallelForEach(task) ⇒ taskFunction
  • .ParallelMap(task) ⇒ taskFunction
  • .ParallelObjectFilter(task) ⇒ taskFunction
  • .ParallelObjectMap(task) ⇒ taskFunction
  • .PassThrough()
  • .PromiseWrapper(generator) ⇒ taskFunction
  • .Promisify(task) ⇒ function
  • .Race(...tasks) ⇒ taskFunction
  • .Retry(task, options) ⇒ taskFunction
  • .Throttle(task, limit) ⇒ taskFunction
  • .TimeIn(task, ms) ⇒ taskFunction
  • .TimeOut(task, ms) ⇒ taskFunction
  • .Timer(task, label) ⇒ taskFunction
  • .While(conditionTask, loopTask) ⇒ taskFunction

uchain.FromPromise ⇒ taskFunction

  let chain = InSeries(
    function(next, ...args) {...},
    FromPromise(
      (...args) => new Promise((resolve, reject) => resolve(...args))
    ),
    function(next, ...args) {},
    ...
  );

  chain(next, ...args);

Alias for PromiseWrapper Wraps around a promise generator function, to make it easier to integrate with task functions.

Kind: static constant of uchain
Returns: taskFunction - a task that wraps around the promise

uchain.ToPromise ⇒ function

  let chain = InSeries(
    function(next, ...args) {...},
    function(next, ...args) {...},
    ...
  );

 new Promise()
   .then(
     ToPromise(chain)
   );

Alias for Promisify

Wraps around a task function and greates a promise generator, to make it easier to integrate task functions and promises.

NOTE: uchain does not come bundled with a promise library, it expects Promise to already exists in the global namespace.

NOTE: because uchain can 'return' multiple values through the next callback, Promisify always resolves to an array of the results returned.

Kind: static constant of uchain
Returns: function - a function that generates a Promise when called

uchain.Assert(validator, message) ⇒ taskFunction

Builds an async assertion task. When called, if the arguments do not match the validator functions, Assert passes an error to its callback.

Kind: static method of uchain
Returns: taskFunction - an assertion task

uchain.CatchError(task) ⇒ taskFunction

Errors bypass the normal flow of execution. They're always returned to the last link in the chain, even if they occur inside nested InSeries or InParallel chains.

  let chain = InSeries(
    (next) => { console.log(1); next(); }
    InSeries(
      (next) => { console.log(2); next(); }
      (next) => { console.log(3); next('Error'); }
    ),
    InSeries(
      (next) => { console.log(4); next();}
      (next) => { console.log(5); next();}
    )
  )(console.log); // prints out 1 2 3 Error, eventually

If you need to catch an error explicitly at some point, wrap a chain in CatchError, which will return the error as the first argument to the next function.

  let chain = InSeries(
    (next) => { console.log(1); next();}
    CatchError(
      InSeries(
        (next) => { console.log(2); next();}
        (next) => { console.log(3); next('Error');}
      ),
    ),
    (next, error) => error != null ? console.log('Error Caught') : null,
    InSeries(
      (next) => { console.log(4); next();}
      (next) => { console.log(5); next();}
    )
  )(console.log); // prints out 1 2 3 Error Caught 4 5, eventually

Kind: static method of uchain
Returns: taskFunction - a wrapper function around the task

uchain.If(conditionTask, thenTask, elseTask) ⇒ taskFunction

  let task = If(
    function(next, ...args) {},
    function(next, ...args) {},
    function(next, ...args) {}
  );

  chain(next, ...args);

If accepts up to three tasks and returns a task that conditionally executes some.

  let logIfEven = If(
    (next, num) => next(null, num % 2 === 0)
    (next, num) => { console.log('is even!'); next(null, num); },
    (next, num) => { console.log('is not even!'); next(null, num); },
  );

  let onDone = (err, ...results) => console.log(results);

  logIfEven(null, 1); // prints out 'is not even!' eventually
  logIfEven(null, 2); // prints out 'is even!' eventually

note: by default, the conditionTask, thenTask, and elseTask are all set to PassThrough note: the conditionTask can return multiple results, but only the first is checked for truthiness

Kind: static method of uchain

uchain.InOrder(...tasks) ⇒ taskFunction

  let chain = InOrder(
    function(next, ...args) {},
    function(next, ...args) {},
    ...
  );

  chain(next, ...args);

Runs several asynchronous tasks one after another. Each task gets the arguments that were originally passed into the wrapper. This is different from InSeries, where the output of each is task is passed as the input to the next.

  let chain = InOrder(
    (next, a) => { a.val = 1; console.log(a.val); next();}
    (next) => { a.val = 2; console.log(a.val); next();}
    (next) => { a.val = 3; console.log(a.val); next();}
  )(null, {}); // prints out 1 2 3, eventually

Kind: static method of uchain
Returns: taskFunction - a wrapper function that runs the tasks in order

uchain.InParallel(...tasks) ⇒ taskFunction

  let chain = InParallel(
    function(next, ...args) {},
    function(next, ...args) {},
    ...
  );

  chain(next, ...args);

InParallel accepts a number of functions, and returns a task function that executes all of its child tasks in parallel.

  let chain = InParallel(
    (next) => next(null, 1),
    (next) => next(null, 2),
    (next) => next(null, 3, 4),
  );

  let onDone = (err, ...results) => console.log(results);

  chain(onDone); // prints out [ 1 ] [ 2 ] [ 3, 4 ], eventually

note: because the callbacks can return any number of results, the results from each task are autoboxed into an array. This includes an empty array for tasks that don't return results.

Kind: static method of uchain
Returns: taskFunction - a wrapper function that runs the tasks in parallel

uchain.InSeries(...tasks) ⇒ taskFunction

  let chain = InSeries(
    function(next, ...args) {},
    function(next, ...args) {},
    ...
  );

  chain(next, ...args);

Runs several tasks in series, and passes the results from one down to the next. This works similarly to the 'waterfall' method in caolan's async.

  let chain = InSeries(
    (next) => { console.log(1); next();}
    InSeries(
      (next) => { console.log(2); next();}
      (next) => { console.log(3); next();}
    ),
    InSeries(
      (next) => { console.log(4); next();}
      (next) => { console.log(5); next();}
    )
  )(); // prints out 1 2 3 4 5, eventually

Kind: static method of uchain
Returns: taskFunction - a wrapper function that runs the tasks in series

uchain.Logging(...statements) ⇒ taskFunction

A logging utility. It passes the arguments received into all the statements, collects the results, and joins them together with newlines to build the final log statement

Kind: static method of uchain
Returns: taskFunction - a logging task

uchain.ParallelFilter(filter) ⇒ taskFunction

Builds a task that filters all of its arguments in parallel, and returns the results

Kind: static method of uchain
Returns: taskFunction - a filtering task

uchain.ParallelForEach(task) ⇒ taskFunction

Builds a task wrapper that calls a task once on each of its arguments in parallel

Kind: static method of uchain
Returns: taskFunction - a parallel foreach task

uchain.ParallelMap(task) ⇒ taskFunction

Builds a task wrapper that asynchronously maps each of its arguments to a result. Note: even though the mapping function can return any number of results, ParallelMap only uses the first result

Kind: static method of uchain
Returns: taskFunction - a parallel map task

uchain.ParallelObjectFilter(task) ⇒ taskFunction

Similar to ParallelFilter, but instead of running on an array of arguments, it runs a filter on every key-value pair in an object.

Kind: static method of uchain
Returns: taskFunction - a parallel filter task

uchain.ParallelObjectMap(task) ⇒ taskFunction

Similar to ParallelMap, but instead of running on an array of arguments, it runs a filter on every key-value pair in an object.

Kind: static method of uchain
Returns: taskFunction - a parallel map task

uchain.PassThrough()

Sometimes, you need to pass previous arguments along with a new result. The easiest way to do this is to use PassThrough, which is a convenience method for:

 (next, ...args) => next(null, ...args),

Kind: static method of uchain

uchain.PromiseWrapper(generator) ⇒ taskFunction

  let chain = InSeries(
    function(next, ...args) {...},
    PromiseWrapper(
      (...args) => new Promise((resolve, reject) => resolve(...args))
    ),
    function(next, ...args) {},
    ...
  );

  chain(next, ...args);

Wraps around a promise generator function, to make it easier to integrate with task functions.

Kind: static method of uchain
Returns: taskFunction - a task that wraps around the promise

uchain.Promisify(task) ⇒ function

  let chain = InSeries(
    function(next, ...args) {...},
    function(next, ...args) {...},
    ...
  );

 new Promise()
   .then(
     Promisify(chain)
   );

Wraps around a task function and greates a promise generator, to make it easier to integrate task functions and promises.

NOTE: uchain does not come bundled with a promise library, it expects Promise to already exists in the global namespace.

NOTE: because uchain can 'return' multiple values through the next callback, Promisify always resolves to an array of the results returned.

Kind: static method of uchain
Returns: function - a function that generates a Promise when called

uchain.Race(...tasks) ⇒ taskFunction

  let chain = Race(
    function(next, ...args) {},
    function(next, ...args) {},
    ...
  );

  chain(next, ...args);

Race accepts a number of functions, and returns a task function that executes all of its child tasks simultaneously. The first result (or error) is returned, and the remaining results (or errors) are ignored.

  let chain = Race(
    (next) => next(null, 1),
    (next) => setTimeout(next, 100, null, 2),
    (next) => { throw new Error(); } ,
  );

  let onDone = (err, ...results) => console.log(results);

  chain(onDone); // prints out [ 1 ], eventually

Kind: static method of uchain
Returns: taskFunction - a task

uchain.Retry(task, options) ⇒ taskFunction

Wraps a task and attempts to retry if it throws an error, with an exponential backoff.

Kind: static method of uchain
Returns: taskFunction - a task

uchain.Throttle(task, limit) ⇒ taskFunction

Wraps a task and ensures that only X number of instances of the task can be run in parallel. Requests are queued up in an unbounded FIFO queue until they can be run.

Kind: static method of uchain
Returns: taskFunction - a task

uchain.TimeIn(task, ms) ⇒ taskFunction

  let chain = TimeIn(
    function(next, ...args) {},
			1000
  );

  chain(next, ...args);

TimeIn wraps a single task function, and returns a function that only returns after X ms.

Kind: static method of uchain
Returns: taskFunction - a task

uchain.TimeOut(task, ms) ⇒ taskFunction

  let chain = TimeOut(
    function(next, ...args) {},
			1000
  );

  chain(next, ...args);

TimeOut wraps a single task function, and returns a function that returns early if the task fails to complete before the timeout triggers.

NOTE: no error is thrown on a timeout, the result is merely undefined.

NOTE: the timeout being triggered will not cancel the original task.

Kind: static method of uchain
Returns: taskFunction - a task

uchain.Timer(task, label) ⇒ taskFunction

Wraps a task and logs how long it takes to finish, or fail.

Kind: static method of uchain
Returns: taskFunction - a task

uchain.While(conditionTask, loopTask) ⇒ taskFunction

  let task = While(
    function(next, ...args) {},
    function(next, ...args) {},
  );

  chain(next, ...args);

While accepts two tasks and returns a task that conditionally executes some.

  let incUntil10 = While(
    (next, num) => next(null, num < 10),
    (next, num) => { console.log('num', nul); next(null, num + 1); },
  );

  let onDone = (err, ...results) => console.log(results);

  incUntil10(null, 1); // prints 1, 2, ... 9

note: the results of the loop task are saved to pass into the conditionTask, and the loopTask note: when the condition task returns false, those results are passed down the chain

Kind: static method of uchain

nextFunction : function

An async callback function.

Kind: global typedef

taskFunction : function

An async task function.

Kind: global typedef

stringBuilder ⇒ string

A string building function.

Kind: global typedef
Returns: string - the string