Reduce

This plug-in is used to reduce the elements of an array to a single value (the memo value). The reduction is done by calling an asynchronous function (the reduce function) on each element of the array followed by calling a synchronous function (defined in the iterator property) for each of the results.

prop reducerequired

The reduce property defines an object with properties that control how the state should use the plug-in.

prop reduce.fnrequired

The reduce.fn property defines the asynchronous reduce function used by the plug-in. This property has one of the following syntaxes:

  • A string that names an asynchronous function (contained within the imports object)
  • A variable that holds a reference to an asynchronous function
  • An inline function definition defining the asynchronous function

Using the string syntax helps to create better diagrams for very little overhead and is therefore recommended.

prop reduce.fnArgsoptional

A synchronous function used to produce the arguments that are passed to the asynchronous reduce function. The reduce.fnArgs function is called for each element of the array and is passed the current item from the array and its index. The function should return either a single argument or an array of arguments.

prop reduce.iteratorrequired

A synchronous function used to produce a new memo value. The reduce.iterator function is only called if the reduce function returns without error (i.e. if its callback function is called with null as the first argument). In this case the reduce.iterator function is called using the current memo value followed by the subsequent arguments from the reduce callback function.

prop reduce.memooptional

The original value to set the memo to (default 0).

prop reduce.overoptional

The reduce.over property sets the array which will be iterated over. This property has one of the following syntaxes:

  • An array
  • A synchronous function returning an array
  • undefined, in which case the first argument from the transition arguments (which should be an array) is used

prop reduce.paroptional

The reduce.par parameter sets the maximum number of array elements used in parallel at any one time. This allows anything from purely sequential processing (i.e. reduce.par = 1) to complete parallel processing (i.e. reduce.par = size of the array) to be supported.

If the parameter is undefined then a default value of 4 is used.

event 'reduce.done'

An event called 'reduce.done' is generated and injected into the current state when all the array elements have been reduced. The event has three arguments, the final memo value, then the original array and finally an error array.

Example

The following example uses the reduce plug-in together with the node.js asynchronous function fs.readFile to count the total number of lines in a collection of files.

CountLines: {
  reduce: {
    fn: 'fs.readFile',
    iterator: function (memo, data) {
      return memo + String(data).split('\n').length;
    }
  },

  actions: {
    'reduce.done': function (memo, paths, errs) {
      console.log('Total lines %d', memo);
      if (errs.length) {
        console.error('fs.readFile errors: %d', errs.length);
      }
    }
  }
}

See