Map

This plug-in is used to build a new array by calling an asynchronous map function on each element of a specified input array. The map function should return immediately and accept a callback function as its final argument.

prop maprequired

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

prop map.fnrequired

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

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

A synchronous function used to produce each new element of the mapped array given the return values of the asynchronous map function. The iterator function is only called if the map function returns without error (i.e. if its callback function is called with null as the first argument). In this case the iterator function is called using the subsequent arguments from the map callback function followed by an array containing the map functions own arguments.

If the map.iterator function is undefined then the second argument from map callback function is used (i.e. the first of the non-error arguments).

prop map.overoptional

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

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

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

event 'map.done'

An event called 'map.done' is generated and injected into the current state when all the array elements have been mapped. The event has three arguments, the new mapped array, then the original array and finally an error array.

Example

In the following example the map plug-in is used to map an array of URLs (taken from the first argument of the transition arguments) to an array of objects containing information about the current IP addresses of each URL. The map.iterator function used is the node.js asynchronous function dns.resolve. Notice that the map.par property is set, indicating that up to 6 calls to dns.resolve will be made in parallel.

The map.iterator function maps the return values from the dns.resolve function (an array of IP addresses as strings) into objects containing the URL (the url property), the first IP address in the array (the ip property) and the number of IP addresses registered (the count property).

DnsResolve: {
  map: {
    fn: 'dns.resolve',
    iterator: function (addresses, args) {
      return {
        url: args[0],
        ip: addresses[0],
        count: addresses.length
      };
    },
    par: 6  
  },

  actions: {
    'map.done': '@exit'
  }
}

See