Home

Awesome

henderson

A tiny event emitter-based finite state machine, with promises

Build Status Uncompressed size minfied+gzipped size

A tiny finite state machine library with asynchronous state transfers, based on an event-emitter. henderson is the promise-based version of pastafarian.

Features
<br>

Example

var state = new StateMachine({
  initial : 'start',
  states  : {
    start : ['end', 'start'],
    end   : ['start']
  }
});

state.on('*', function(prev, next) {
  console.log('State changed from ' + prev + ' to ' + next);
});

state
  .on('before:start', function(prev, param) {
    console.log('Reset with param === "foo": ' + param === 'foo');
  })
  .on('after:start', function(next) {
    console.log('Going to ' + next);
  })
  .on('end', function(prev, param) {
    return new Promise(function(resolve) {
      setTimeout(function() {
        console.log('Now at end, 2 + 2 = ' + param);
        resolve();
      }, 1500);
    });
  });

state.go('end', 2 + 2)
  .then(function() {
    console.log('Transition finished!');
  });

state.reset = state.go.bind(state, 'start');
state.reset('foo');

Installation

Right click to save or use the URLs in your script tags

or use

$ npm install henderson
$ bower install henderson

If you're using henderson in a browser environment, the constructor is attached to the StateMachine global.

<br>

Usage

henderson is very similar in usage to pastafarian and most of the documentation in that project can be directly applied to henderson as well.

Differences to pastafarian

Given var fsm = new StateMachine(config),

featurepastafarianhendersoncomment
config.initialYYidentical
config.statesYYidentical
config.errorYNuse the error callback on the promise returned from fsm.go
fsm.bindYYidentical
fsm.onYYidentical
fsm.unbindYYidentical
fsm.goYYreturns a promise, which is resolved when all callbacks have finished
fsm.currentYYidentical
fsm.transitionsYYidentical
fsm.errorYNuse the error callback on the promise returned from fsm.go

fsm.go(state /* ...args */) ⇒ Promise

Transitions the state machine to state and causes any registered callbacks for this transition (including before:, after: and wildcard callbacks) to be triggered. All parameters after state are passed on to each callback along with the states involved in the transition, see the Event callback API for the exact signatures.

fsm.go returns a promise that will be resolved when all the callbacks registered for the transition have finished. All registered functions will run in strict order, if a callback returns a promise the subsequent callback will not be run before the previous promise is resolved. If a callback returns a rejected promise, the subsequent registered functions will not be called. The statemachine may however have already transitioned to the new state, depending on which transition event the callbacks have been registered to, and state rollback should be taken care of by library users as appropriate.

<br>
Error handling

fsm.go will return a Promise, and the transition promise will reject if any of the transition callbacks either return a rejected promise or an uncaught exception is thrown. In the case that an illegal transition is attempted, the .catch error callback will be called with an IllegalTransitionException:

IllegalTransitionException

henderson defines a custom exception which is generated when the transitions array of the current state doesn't contain the state (next) passed to fsm.go:

The exception is generated inside the library, but in modern environments it should contain a stacktrace that allows you to track which line caused the exception.

<br>

Requirements

henderson internally uses promises and expects an implementation to be available with new Promise(function(resolve, reject) { ... }). Otherwise, an environment providing ES5-support is enough (Array.indexOf and Array.reduce are used internally).

<br>

Changelog

2.0.0

1.0.0

<br>

Colophon

The event emitter pattern that henderson uses at its core is based on microevent.js.

<br>

License

henderson is ISC licensed.

<br>

Development

A basic development workflow is defined using npm run scripts. Get started with

$ git clone https://github.com/orbitbot/henderson
$ npm install
$ npm run develop

Bugfixes and improvements are welcome, however, please open an Issue to discuss any larger changes beforehand, and consider if functionality can be implemented with a simple monkey-patching extension script. Useful extensions are more than welcome!