Detect

This plug-in is used to find the first element found in a specified array that returns true given an asynchronous binary function test. The test 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 pass or failure (e.g. the node.js function path.exists).

prop detectrequired

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

prop detect.fnrequired

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

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

If the parameter is undefined then the asynchronous test function argument used for each element of the array is simply that element.

prop detect.overoptional

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

The detect.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. detect.par = 1) to complete parallel processing (i.e. detect.par = size of the array) to be supported.

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

event 'detect.done'

An event called 'detect.done' is generated and injected into the current state when an element of the array is found that passes the asynchronous function test or when the entire array has been tested.

The generated event is passed the first element of the array to successfully pass the test or undefined if no value was detected.

Example

In the example below the node.js asynchronous function path.exists is use the detect the first element of a array of paths (taken from the first argument of the transition arguments) that exists. The state either transitions to a state called 'FoundOne' if a good path is found, or to a state called 'FoundNothing' if none of the paths exist.

Detect: {
  detect: {
    fn: 'path.exists'
  },

  actions: {
    'detect.done': function (result) {
      if (result) {
        return 'FoundOne';
      } else {
        return 'FoundNothing';
      }
    }
  }
}

See