Filter

This plug-in is used to filter the elements of a specified array into a new array. Inclusion in the new array is determined by the return value of an asynchronous filter function which is called on each element of the array.

The filter function should return immediately and accept a callback function as its final argument. The callback function should be called on completion with a single binary argument (i.e. true or false) indicating inclusion or exclusion (e.g. the node.js function path.exists).

prop filterrequired

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

prop filter.fnrequired

The filter.fn property defines the asynchronous filter 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 filter.fnArgsoptional

A synchronous function used to produce the arguments that are passed to the asynchronous filter function. The filter.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 filter.overoptional

The 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 filter.paroptional

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

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

event: filter.done

An event called 'filter.done' is generated and injected into the current state when all the array elements have been filtered and the new array completed. The event has two arguments, the filtered array followed by the original array.

Example

In the following example a simple state called FilterDir is used to filter an array of paths (taken from the first argument of the transition arguments) to include only directories. The filtered array is then passed to a state called 'ProcessDirectories'.

FilterDir: {
  filter: {
    fn: dirFilter      
  },

  action: {
    'filter.done': function (dirsOut, pathsIn) {
      return ['ProcessDirectories', dirsOut];
    }
  }
}

The dirFilter filter function can easily be defined using the node.js asynchronous function fs.stat as follows:

var dirFilter = function (path, cb) {
  require('fs').stat(path, function (err, stat) {
    if (!err && stat.isDirectory()) {
      cb(true);
    } else {
      cb(false);
    }
  });
};

See