Examples

The first example shows the state Admin using a synchronous guard function to test if the appropriate validation has been acquired to enter the state. The guard function performs a simple binary test on the transition argument hasValidation and either allows entry into the state (null return) or causes a transition to a different state AquireValidation ('AquireValidation' return).

Admin: {
  guard: function (hasValidation) {
    return hasValidation ? null : 'AquireValidation';
  }
  ....
},
AquireValidation: {
  ....
}

The next example shows the state ListProcessor which uses a synchronous guard function to control entry based on the number of elements in a list (list). Notice that in this case list is not one of the guard function arguments and therefore is not being passed to the state as a transition argument. This means that list has been defined either globally, within the State Machine Generator Function closure, or within the State Behaviour Object closure.

ListProcessor: {
  guard: function () {
    if (list.length > 0) {
      // more work to be done, so entry the
      // state
      return null;
    } else {
      // no more work to be done, so move on
      return 'AnotherState';
    }
  }
  ....
}

The final example illustrates the use of an asynchronous guard function. The FileProcessor state outlined below tests a path by calling the fs.stat function, passing it the first element of the transition arguments (in this example a path). The state is only entered (null return) if stat.isFile() returns true.

FileProcessor: {
  guard: {
    async: 'fs.stat',
    actions: {
      '.done': function (stat) {
        if (stat.isFile()) {
          // path is a file so enter the state
          return null;
        } else if (stat.isDirectory()) {
          // path is a directory so transition to
          // DirectoryProcessor state
          return 'DirectoryProcessor';
        } else {
          // handle default fs case
          return 'DefaultFS';
        }
      },
      '.err': '@error'
    }
  }
  ....
}

See

• State definition API - prop: guard

Examples

The following example shows how the entry function can be used to register an EventEmitter (a fs.ReadStream object). Notice that in this example the State Behaviour Object is defined using a function to allow the fs.ReadStream object to be captured in a JavaScript closure.

StreamReader: function () {
  // @type {fs.ReadStream}
  var readStream;
  return {
    entry: function (filePath) {
      // create a new EventEmitter
      readStream = fs.createReadStream(filePath);
      // register the event emitter with the
      // state machine
      fire.$regEmitter('rs', readstream);
    },
    ....
  };
}

In the next example the entry function is used to start an asynchronous function (fs.readFile).

FileReader: {
  entry: function (filePath) {
    fire.fs.readFile(filePath);
  },
  ....
}

In the above two examples, when the asynchronous processes returns, either partially by emitting an event or fully by calling a completion callback function, then the state machine needs a way to intercept this and act accordingly. As is explained in the next section, this is what the actions object is used for.

See

• The fire object
• State definition API - prop: entry

Examples

The examples in this section relate to the examples shown above in the entry function section. First consider the StreamReader state. Adding actions to this state determines how the state should handle any data received from the stream. In this example the data is simply accumulated (using the state closure variable streamData) and then passed (using a data qualified transition, see: line 21) to another state (called ProcessData) once the stream has ended.

StreamReader: function () {
  // @type {fs.ReadStream}
  var readStream;
  // @type {Buffer|String}
  var streamData;
  return {
    entry: function (filePath) {
      // create a new EventEmitter
      readStream = fs.createReadStream(filePath);
      // register the event emitter with the
      // state machine
      fire.$regEmitter('rs', readstream);
    },
    actions: {
      'rs.data': function (data) {
        // accumulate the data
        streamData += data;
      },
      // data qualified transition to the state called 
      // 'ProcessData', passing data streamData
      'rs.end': ['ProcessData', streamData],
      // transition to the error state using the '@error' alias
      'rs.error': '@error'
    }
  };
}

The following example builds on the FileReader state from above. This state uses the asynchronous function call proxy mechanism to segregate the return behaviour of the fs.readFile asynchronous function call into events. These events are then handled by separate functions in the actions object leading to a natural isolation of the code used to handle the possible outcomes.

FileReader: {
  entry: function (filePath) {
    fire.fs.readFile(filePath);
  },
  actions: {
    'fs.readFile.done': function (data, filePathArgs) {
      // count lines and transition to the state called 'Lines'
      var numberOfLines = String(data).split('\n').length;
      return ['Lines', numberOfLines, filePathArgs[0]];
    },
    // transition to the error state using the '@error' alias
    'fs.readFile.err': '@error'
  }
}

It is worth noting a few things from the above example. First, notice that by using the fire.fs.readFile proxy to call the fs.readFile function causes an anonymous callback function to be created and used. When fs.readFile completes, this function is called causing either done or err events to be emitted. If the done event is emitted then the transition arguments are set to the function callback arguments that follow the initial null error argument (i.e. data), followed by the initial function call argument (i.e. the first element of the filePathArgs array which contains filePath). If the err event is emitted then the transition arguments are set to the first of the function callback arguments (i.e. the error variable).

Second, notice how the fs.readFile.done action function receives the current transition arguments (data followed by filePath) as its arguments. These are then modified (to numberOfLines, filePath) by making a data qualified transition to the state called Lines.

See

• The fire object
• State definition API - prop: actions

Example

In the example below the exit function is used to close the underlying file descriptor so that the stream will not emit any more events (Line 20).

StreamReader: function () {
  // @type {fs.ReadStream}
  var readStream;
  // @type {Buffer|String}
  var streamData;
  return {
    entry: function (filePath) {
      // create a new EventEmitter
      readStream = fs.createReadStream(filePath);
      // register the event emitter with the
      // state machine
      fire.$regEmitter('rs', readstream);
    },
    actions: {
      ....
    },
    exit: {
      // Close the underlying file descriptor so that 
      // the stream will not emit any more events.
      streamData.destroy();
    }
  };
}

See

• State definition API - prop: exit