Async

The async plug-in is used as a convenient way to define a state which simply launches an asynchronous function call and waits for the reply. The function should return immediately and accept a callback function as its final argument.

prop asyncrequired

The async property is used to define how the state should use the plug-in.

If only the asynchronous function needs to be specified then an async property should be a string naming the function or a variable reference to it.

If additional context information is necessary, e.g. the specification of the arguments for the function, then the async property should be an object containing the properties fn and fnArgs described below.

prop async.fnrequired

The async.fn property is used to defined the asynchronous 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

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

prop async.fnArgsoptional

The async.fnArgs property is used to defined the arguments that are passed to the asynchronous function defined in async.fn. The property can either be a static array, or a function returning an array. If the function syntax is used, it is called using the current transition arguments as its arguments.

If the property is missing then the current transition arguments are used.

event 'async.done'

An event called 'async.done' is generated and injected into the current state when the asynchronous function completes and the first argument of the callback function is null (assumed to be the err argument). The event arguments are made up of all subsequent callback arguments together with an array containing the original asynchronous call arguments as the final argument.

event 'async.err'

An event called 'async.err' is generated and injected into the current state when the asynchronous function completes and the first argument of the callback function is not null. The event arguments are made up of all the callback arguments together with an array containing the original asynchronous call arguments as the final argument.

Example

In the following example the async plug-in is used to call an asynchronous function called 'fs.stat' (see: node.js function fs.stat).

Stat: {
  async: 'fs.stat',
  actions: {
    'async.done': function (stat, args) {
      if (stat.isFile()) {
        return ['ReadFile', args];
      } else if (stat.isDirectory()) {
        return ['ReadDir', args];
      } else {
        return ['@error', args];
      }
    },
    'async.err': function (err, stat, args) {
      return ['@error', err];
    }
  }
}

See