Javascript State Machine

A javascript finite state machine library

State machineState management
jakesgordon/javascript-state-machinejavascript-state-machine

README

Javascript State Machine

NPM version Build Status

A library for finite state machines.

matter state machine

NOTE for existing users


VERSION 3.0 Is a significant rewrite from earlier versions.

  Existing 2.x users should be sure to read the Upgrade Guide.

Installation


In a browser:

  1. ``` html
  2.   <script src='state-machine.js'></script>
  3. ```

after downloading the source or the minified version


Using npm:

  1. ``` sh
  2.   npm install --save-dev javascript-state-machine
  3. ```

In Node.js:

  1. ``` js
  2.   var StateMachine = require('javascript-state-machine');
  3. ```

Usage


A state machine can be constructed using:

  1. ``` js
  2.   var fsm = new StateMachine({
  3.     init: 'solid',
  4.     transitions: [
  5.       { name: 'melt',     from: 'solid',  to: 'liquid' },
  6.       { name: 'freeze',   from: 'liquid', to: 'solid'  },
  7.       { name: 'vaporize', from: 'liquid', to: 'gas'    },
  8.       { name: 'condense', from: 'gas',    to: 'liquid' }
  9.     ],
  10.     methods: {
  11.       onMelt:     function() { console.log('I melted')    },
  12.       onFreeze:   function() { console.log('I froze')     },
  13.       onVaporize: function() { console.log('I vaporized') },
  14.       onCondense: function() { console.log('I condensed') }
  15.     }
  16.   });
  17. ```

... which creates an object with a current state property:

  fsm.state

... methods to transition to a different state:

  fsm.melt()
  fsm.freeze()
  fsm.vaporize()
  fsm.condense()

... observer methods called automatically during the lifecycle of a transition:

  onMelt()
  onFreeze()
  onVaporize()
  onCondense()

... along with the following helper methods:

  fsm.is(s)            - return true if state s is the current state
  fsm.can(t)           - return true if transition t can occur from the current state
  fsm.cannot(t)        - return true if transition t cannot occur from the current state
  fsm.transitions()    - return list of transitions that are allowed from the current state
  fsm.allTransitions() - return list of all possible transitions
  fsm.allStates()      - return list of all possible states

Terminology


A state machine consists of a set of [States](docs/states-and-transitions.md)

  solid
  liquid
  gas

A state machine changes state by using [Transitions](docs/states-and-transitions.md)

  melt
  freeze
  vaporize
  condense

A state machine can perform actions during a transition by observing [Lifecycle Events](docs/lifecycle-events.md)

  onBeforeMelt
  onAfterMelt
  onLeaveSolid
  onEnterLiquid
  ...

A state machine can also have arbitrary [Data and Methods](docs/data-and-methods.md).

Multiple instances of a state machine can be created using a [State Machine Factory](docs/state-machine-factory.md).

Documentation


Read more about

  States and Transitions
  Data and Methods
  Lifecycle Events
  Asynchronous Transitions
  Initialization
  Error Handling
  State History
  Visualization
  State Machine Factory
  Upgrading from 2.x

Contributing


You can Contribute to this project with issues or pull requests.

Release Notes


See RELEASE NOTES file.

License


See MIT LICENSE file.

Contact


If you have any ideas, feedback, requests or bug reports, you can reach me at
jake@codeincomplete.com, or via
my website: Code inComplete