Javascript State Machine

A library for finite state machines.

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<script src='https://unpkg.com/@taoqf/javascript-state-machine'></script>
2<!-- or -->
3<script src='https://unpkg.com/@taoqf/javascript-state-machine/dist/state-machine.min.js'></script>

after downloading the source or the minified version

Using npm:

1  npm install --save-dev @taoqf/javascript-state-machine

In Node.js:

1  var StateMachine = require('@taoqf/javascript-state-machine');

Usage

A state machine can be constructed using:

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

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

• solid
• liquid
• gas

A state machine changes state by using Transitions

• melt
• freeze
• vaporize
• condense

A state machine can perform actions during a transition by observing Lifecycle Events

• onBeforeMelt
• onAfterMelt
• onLeaveSolid
• onEnterLiquid
• ...

A state machine can also have arbitrary Data and Methods.

Multiple instances of a state machine can be created using a State Machine Factory.

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
• TypeScript

Contributing

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

You might also want to support this project by purchasing a commercial license.

Release Notes

See RELEASE NOTES file.

License

Dual-licensed under the LGPL for the open source community and also available with support under a commercial license.

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