henderson

    2.0.0 • Public • Published

    henderson

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

    Build Status Uncompressed size minfied 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
    • tiny finite state machine library, only slightly bigger than its synchronous cousin pastafarian
    • simple but powerful API
    • works without dependencies on modern browsers (see requirements)
    • well below 100 LOC, small enough to read and understand immediately

    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.


    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),

    feature pastafarian henderson comment
    config.initial Y Y identical
    config.states Y Y identical
    config.error Y N use the error callback on the promise returned from fsm.go
    fsm.bind Y Y identical
    fsm.on Y Y identical
    fsm.unbind Y Y identical
    fsm.go Y Y returns a promise, which is resolved when all callbacks have finished
    fsm.current Y Y identical
    fsm.transitions Y Y identical
    fsm.error Y N use the error callback on the promise returned from fsm.go
    • no error handling through try/catch blocks or with a defined error handler function, use .catch on individual .go calls instead

    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.


    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:

    • name : IllegalTransitionException
    • message : Transition from <current> to <next> is not allowed
    • prev : <current>
    • attempt : <next>

    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.


    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).


    Changelog

    2.0.0

    • #1 : fix buggy Promise chaining logic during state transitions, registered callbacks are run in strict order and the whole chain will be rejected if a callback returns a rejected promise
    • #2 : .on / .bind supports registering both a single callback function and an array of callbacks

    1.0.0

    • initial release

    Colophon

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


    License

    henderson is ISC licensed.


    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!

    Install

    npm i henderson

    DownloadsWeekly Downloads

    5

    Version

    2.0.0

    License

    ISC

    Last publish

    Collaborators

    • orbitbot