Module: chopchop

chopchop

Collection of functions for dealing with asynchronous processes.

Methods

<static> filter(iterable, predicate) → {thenable}

Off-load long running work of the main event loop by processing canonical filter in small batches. This will keep the main event loop receptive, avoiding for example long-running script errors in the browser.
Parameters:
Name Type Description
iterable Array | iterator collection to filter
predicate function a function taking an element from the collection returning a boolean. true if the element should be present in the result.
Returns:
promise for the filtered collection
Type
thenable

<static> groupBy(iterable, hash) → {thenable}

Off-load long running work of the main event loop by processing canonical groupBy in small batches. This will keep the main event loop receptive, avoiding for example long-running script errors in the browser.
Parameters:
Name Type Description
iterable Array | iterator collection to group by key
hash hash a function generating the key
Returns:
promise for a POJSO. The values for the keys are arrays with elements from the collection.
Type
thenable

<static> map(iterable, map) → {thenable}

Off-load long running work of the main event loop by processing canonical map in small batches. This will keep the main event loop receptive, avoiding for example long-running script errors in the browser.
Parameters:
Name Type Description
iterable Array | iterator collection to perform the map on
map function a map function taking an element from the collection and returning an output.
Returns:
promise for an array containing the mapped values
Type
thenable
Example
cc
.map([...,...,..],function(e){
   return ...;
})
.then(function(results){
   //results is an array with the mapped collection
});

<static> mapReduce(map, fold, iterable) → {thenable}

Run a map reduce job
Parameters:
Name Type Description
map handler map function. It must return a POJSO. The keys must point to the value that must be aggregated by the reduce function.
fold function a function taking two arguments: an accumulated value, an element from the input collection. It must return the new acumulated value.
iterable Array | iterator collection of data inputs to perform map reduce on.
Returns:
promise for a POJSO. The values for the keys are the last accumulated value for that key.
Type
thenable
Example
   //word-count example.

   //Map function: map each word to the number of times it occurs in the text.
   function countWords(text) {
    var s = text.split(/[^\w]/g);
    var map = {};
    for (var i in s) {
      if (!map[s[i]]) {
        map[s[i]] = 0;
      }
      map[s[i]] += 1;
    }
    return map;
  }

   //Reduce function: aggregate the results by summing.
   function sum(a, b) {
    return a + b;
  }

   //inputs
   var data = [
   "you load sixteen tons",
   "and what do you get",
   "another day older",
   "and deeper in debt"
   ];

   cc
   .mapReduce(countWords, sum, data)
   .then(function(result){

        //  JSON.stringify(result, null, " ") === "{
        //   "and": 2,
        //   "deeper": 1,
        //   "in": 1,
        //   "debt": 1,
        //   "what": 1,
        //   "do": 1,
        //   "you": 2,
        //   "get": 1,
        //   "another": 1,
        //   "day": 1,
        //   "older": 1,
        //   "load": 1,
        //   "sixteen": 1,
        //   "tons": 1
        //  }";

   });

<static> now() → {Number}

get timestamp for the current time.
Returns:
timestamp in milliseconds.
Type
Number

<static> parallel(handler, input1, input2, varargs) → {thenable}

Process inputs in parallel.
Parameters:
Name Type Argument Description
handler handler a function to perform some work
input1 Object an input for the handler
input2 Object <optional>
an input for the handler
varargs Object <optional>
any number of inputs
Returns:
a thenable for an array with the responses for all inputs
Type
thenable
Example
cc
.parallel(cc.timeout,1,2,3)
.then(function(results){
   //results is an array, containing 3 timestamps
   //[0]: ~1 millisecond after the function was invoked
   //[1]: ~2 milliseconds after the function was invoked
   //[2]: ~3 milliseconds after the function was invoked
});

<static> pool(node1, node2, varargs) → {handler}

Create pool from one or more handlers. When all handlers in the pool are busy, inputs will be queued until. Typically, the handlers will be several instances of the same process. (e.g. different instances of different workers)
Parameters:
Name Type Argument Description
node1 handler a function performing some work
node2 handler <optional>
a function performing some work
varargs handler <optional>
any number of handlers
Returns:
a function pooling its inputs. They are distributed among the
Type
handler
Example
var worker1 = new Worker('someWorker.js');
var worker2 = new Worker('someWorker.js');
var node1 = cc.strapWorker(worker1);
var node2 = cc.strapWorker(worker2);

var pl= cc.pool(node1, node2);
pl(...).then(...);
pl(...).then(...);
pl(...).then(...);
pl(...).then(...);

<static> reduce(iterable, fold, initial) → {thenable}

Off-load long running work of the main event loop by processing canonical reduce in small batches. This will keep the main event loop receptive, avoiding for example long-running script errors in the browser.
Parameters:
Name Type Argument Description
iterable Array | iterator collection to reduce
fold function a function taking two arguments: an accumulated value, an element from the input collection. It must return the new acumulated value.
initial Object <optional>
the initial accumulator
Returns:
promise for the final accumulated value
Type
thenable
Example
cc
.reduce([...,...,..],function(acc, e){
   var newacc = ...
   return newacc;
})
.then(function(acc){
   //acc is the last accumulated value
});

<static> schedule(func) → {thenable}

Invoke the function later in the event loop.
Parameters:
Name Type Description
func function function to invoke
Returns:
promise for the return of the function
Type
thenable

<static> series(handler, input1, input2, varargs) → {thenable}

Process inputs in series.
Parameters:
Name Type Argument Description
handler handler a function to perform some work
input1 Object an input for the handler
input2 Object <optional>
an input for the handler
varargs Object <optional>
any number of inputs
Returns:
a thenable for an array with the responses for all inputs
Type
thenable
Example
var h = cc.timeout;
cc
.series(cc.timeout,1,2,3)
.then(function(results){
   //results is an array, containing 3 timestamps
   //[0]: ~1 millisecond after the function was invoked
   //[1]: ~3 milliseconds after the function was invoked (invoked when first was done)
   //[2]: ~6 milliseconds after the function was invoked (invoked when second was done)
});

<static> shard(hash, node1, node2, varargs) → {handler}

Creates a new function which will dispatch its input argument to the correct node, based on a partitioning function. The partitioning or "hash" function evaluates the input argument, and returns a number which points to the node which should perform the work. Typically, these nodes are handlers representing separate instances of the same worker.
Parameters:
Name Type Argument Description
hash hash a hash function. Has an additional constraint. The return must be an integer between 0 and the length of nodes - 1.
node1 handler <optional>
a function doing some work
node2 handler <optional>
a function doing some work
varargs handler <optional>
any number of functions
Returns:
a handler which will dispatch the argument to the appropriate node. If nodes are busy, the inputs will be queued.
Type
handler
Example
var worker1 = new Worker('someWorker.js');
var worker2 = new Worker('someWorker.js');
var node1 = cc.strapWorker(worker1);
var node2 = cc.strapWorker(worker2);

function partition(string){
 return (string < "m") ? 0: 1;
}
var sh = cc.shard(partition,node1,node2);
sh("a").then(...);//routed to node1
sh("z").then(...);//routed to node2

<static> strapAsync(Function)

Transform a "node"-style asynchronous function in a function that returns a thenable.
Parameters:
Name Type Argument Description
Function <optional>
node-style async function
Returns:
[Function] a function returning a thenable.
Example
 fs = require('fs');
 chch = require('../src/chopchop');

 read = chch.strapAsync(fs.readFile);

 read('./testWorker.js', 'utf8')
 .then(function (data) {
    //success
  }, function (err) {
    //error
  });

<static> strapWorker(worker, options) → {handler}

Create a function that provides access to the web worker. It wraps a simple postmessage/onmessage api. Calls are queued so request/responses will never cross.
Parameters:
Name Type Argument Description
worker Worker a web worker
options Object <optional>
An object with two optional functions, which can be used to intercept post and on message events. If not provided, the identity function is used.
Properties
Name Type Argument Description
mapArguments function <optional>
map input arguments to a message for the worker.
handleReceivedMessage function <optional>
handles a message from the worker.
Returns:
function which abstract communication with the worker.
Type
handler
Example
  //Consider worker 'sumWorker.js';
  onmessage = function(oEvent) {
     var dt = oEvent.data;
     var nominator = dt[0];
     var denominator = dt[1];
     if (denominator === 0){
       postMessage('divBy0');
     }else{
       postMessage(nominator/denominator);
     }
  };

   ....

  //In the browser:
  var sumWorker = new Worker('sumWorker.js');
  var div = cc.strapWorker(sumWorker, {
     mapArguments: function (a, b) {
         return [a, b];
     },
     handleReceivedMessage: function(m, promise){
       if (m === 'divBy0'){
         promise.reject(m);
       }else{
         promise.resolve(m);
       }
     }
 });

  div(1,2)
  .then(function(s){
     //s === 0.5
  });

  div(1,0)
   .then(Function.prototype,function(error){
     //error === 'divBy0'
   });

<static> timeout(delay) → {thenable}

Get a timestamp when the delay expires.
Parameters:
Name Type Description
delay Number time in milliseconds
Returns:
thenable for a timestamp.
Type
thenable
Example
cc
 .timeout(1000)
 .then(function(timestamp){
   //timestamp in milliseconds
 });

<static> waitFor(value) → {thenable}

Get the result when all inputs are available.
Parameters:
Name Type Argument Description
value Object | thenable a value (sync or async)
varargs... Object | thenable <optional>
any number of sync or async values
Returns:
a promise for an array containing the results.
Type
thenable
Example
 var a = cc.timeout(10);
 var b = cc.timeout(20);
 cc
   .waitFor(a,b)
   .then(function(timestamps){
     //timestamps is array of 2 elements
     //timestamps[0] for first arg
     //timestamps[1] for second arg
   });

<static> when(input) → {thenable}

Transparently handle a synchronous or asynchronous object.
Parameters:
Name Type Description
input Object | thenable any synchronous or asynchronous object
Returns:
the sync or async value.
Type
thenable
Example
//async
var oneSecondInTheFuture = cc.timeout(1000);
cc
 .when(oneSecondInTheFuture)
 .then(...);//invoked a second in the future

//sync
var timestamp = 123129;
cc
 .when(timestamp)
 .then(...);//invoked right a way

<static> whenAll(array) → {thenable}

Get the result when all inputs are available.
Parameters:
Name Type Description
array Array an array for any number of sync or async values
Returns:
a promise for an array containing the results.
Type
thenable
Example
 var b = cc.timeout(20);
 cc
   .whenAll([12,b])
   .then(function(results){
     //results[0] === 12
     //results[1] is timestamp
   });