state-machine-js
Finite State Machine
A simple utility that allows you to define states and actions to transition between them.
Installation
- npm:
npm install state-machine-js --save-dev
- bower:
bower install state-machine-js --save-dev
Usage
var stateMachine = ; var State = CLOSED: 'CLOSED' OPENED: 'OPENED' LOCKED: 'LOCKED'; var Action = CLOSE: 'CLOSE' OPEN: 'OPEN' LOCK: 'LOCK' UNLOCK: 'UNLOCK'; var config = initial: true name: StateCLOSED transitions: action: ActionOPEN target: StateOPENED action: ActionLOCK target: StateLOCKED name: StateOPENED transitions: action: ActionCLOSE target: StateCLOSED name: StateLOCKED transitions: action: ActionUNLOCK target: StateCLOSED ; // create multiple states with a config arraystateMachine; // add listener for state changestateMachineonChange; // startstateMachinestart; // state changed to 'CLOSED' because that state has 'initial' flag // state will change to 'LOCKED':stateMachineactionActionLOCK;// state won't change - no valid transition to 'CLOSED' from 'LOCKED':stateMachineactionActionCLOSE;// state will change to 'CLOSED', data payload sent through:stateMachineactionActionUNLOCK foo: 'bar' ; // debug view with info and buttons to change statevar debugView = stateMachine;documentbody;
States can be created individually:
// create a single statestateMachine; // create multiple states by chainingstateMachine;
You can add callbacks to receive notifications when the State Machine is entering or exiting a State and optionally cancel the transition:
// add listener for state enterstateMachineonEnter; // add listener for state exitstateMachineonExit;
You can also add optional callbacks to individual states:
// by retrieving individual statesvar state = stateMachine; stateonEnter; stateonChange; stateonExit; // or via config objectstateMachine;
API
Methods
create(config)
create new States
start() returns StateMachine
starts State Machine, transitioning to 'initial' State
action(action, data) returns StateMachine
initiates a State transition
cancel() returns StateMachine
cancels the current transition
getState(stateName) returns State
retrieve a State
removeState(stateName) returns State
remove a State
getTotal() returns number
total number of States defined
Getters
currentState returns State
previousState returns State
states returns Object
initial returns State
the initial State
history returns array
array of State names (strings)
Callbacks
onChange.add(callback, context)
add callback when State has changed
onEnter.add(callback, context)
add callback when entering a State
onExit.add(callback, context)
add callback when exiting a State
onChange.remove(callback, context)
remove callback
onEnter.remove(callback, context)
remove callback
onExit.remove(callback, context)
remove callback
onChange.removeAll()
remove all callbacks
onEnter.removeAll()
remove all callbacks
onExit.removeAll()
remove all callbacks
Dev Setup
To install dependencies:
$ bower install
To run tests:
$ npm install -g karma-cli
$ npm install
$ karma start