js-fsm
Moore Finite State Machine (FSM)
js-fsm
is a simple javascript Moore Finite State Machine. A Moore machine is a finite-state machine whose output values are determined solely by its current state.
To use js-fsm
, define:
- the starting state,
- transitions (from state, to state, and inputs)
- outputs at each state.
Next, set your inputs and call fsm.clock()
.
Installation
Install with npm
npm install js-fsm
Example
Simple Vending Machine
A vending machine dispenses pieces of candy that cost 20 cents each. The machine accepts nickels and dimes only and does not give change. As soon as the amount deposited equals or exceeds 20 cents, the machine releases a piece of candy. The next coin deposited starts the process over again.
Our state machine has states for the each possible deposited amount: 0 for zero cents deposited, 5 cents, 10 cents, 15 cents, 20 cents and 25 cents.
Defining the FSM
fsm = require( 'js-fsm' )
initial : '0' # starting balance is zero
transitions : [
{ from : [ '0', '20' ], to : '5', inputs : 'nickle' }
{ from : [ '0', '20' ], to : '10', inputs : 'dime' }
{ from : [ '5', '25' ], to : '10', inputs : 'nickle' }
{ from : [ '5', '25' ], to : '15', inputs : 'dime' }
{ from : '10', to : '15', inputs : 'nickle' }
{ from : '10', to : '20', inputs : 'dime' }
{ from : '15', to : '20', inputs : 'nickle' }
{ from : '15', to : '25', inputs : 'dime' }
]
outputs :
'^5,25' : [ 'light5' ]
'^10' : [ 'light10' ]
'^15' : [ 'light15' ]
'^20, 25' : [ 'lightCandy' ]
Operating the vending machine
# from the example insert 'nickle'insert 'dime'insert 'dime'insert 'dime'insert 'dime'insert 'dime'insert 'nickle'
Output
coin | from | to | 5 | 10 | 15 | candy
------- + ------- + ------- + ------- + ------- + ------- + -------
#nickle | 0 | 5 | x | | |
------- + ------- + ------- + ------- + ------- + ------- + -------
#dime | 5 | 15 | | | x |
------- + ------- + ------- + ------- + ------- + ------- + -------
#dime | 15 | 25 | x | | | x
------- + ------- + ------- + ------- + ------- + ------- + -------
#dime | 25 | 15 | | | x |
------- + ------- + ------- + ------- + ------- + ------- + -------
#dime | 15 | 25 | x | | | x
------- + ------- + ------- + ------- + ------- + ------- + -------
#dime | 25 | 15 | | | x |
------- + ------- + ------- + ------- + ------- + ------- + -------
#nickle | 15 | 20 | | | | x
------- + ------- + ------- + ------- + ------- + ------- + -------
API
Create FSM
fsm(options)
options
is an {Object}
-
initial is a
{String}
with the initial state name. -
transitions is an
{Array}
of{Object}
s that specify the destination state and necessary inputs for each transition- from
{String}
is the current state - to
{String}
is the destination of the transition - inputs is an
{Array}
of signal names and their required state. A transition is possible only if all inputs are true. Asignal
prefixed with a!
is negated and so is true if it is low (false) and vice-versa. - description is an optional
{String}
which is returned inleave
andenter
callbacks.
- from
# This transition will occur only when start is true and cancelled is false from: 'initial'to: 'type'inputs: 'start''!cancelled'
- outputs
{Object}
specifies which signals are to be set (and their value) depending on the current state.
# signal 'candy' will go high only in states 20 and 25 and is low everywhere else # 'FIVE' will go high only in state 25 and is low everywhere else # Prefixing with an exclamation will set the outputs for all states other than the # specified ones outputs : '20, 25' : 'candy' '!20, 25' : '!candy' '0, 5, 10, 15, 20' : '!FIVE' '25' : 'FIVE'
Inverting States
Prefixing with an exclamation !
will set the outputs for all states other than the specified ones.
# Output 'candy' is set reset in states other than 20 and 25
'!20, 25': ['!candy']
If-and-only-if Output
Prefixing with a caret ^
sets the state/output combination as if-and-only-if
# Output 'candy' is set in states 20 and 25, and reset everywhere else
'^20, 25': ['candy']
Methods
fsm.signal([value])
Gets or sets the value of the named signal (signal must be replaced with the appropriate name above).
#set signal nickle to true and dime to false fsmnickle truedime false
fsm.clock()
Instructs the FSM to attempt a transition based on the current input values. If no transition is possible, the fsm will emit a noop
event.
# sets input values and and transitions (if possible) fsmdime falsenickle trueclock
fsm.current()
The current state's name
Events
on('noop', cb())
fsm.clock()
resulted in no state change.
on('state', cb(state, from, desc))
Fired when the FSM transitions to a state. The callback cb receives the state names state, from and a string description of why the transition occured.
on('error', cb(Error))
Fired if an error occurs. e.g. to many transitions from a state.
on('changed:signal', cb(new, old))
Fired when a signal value changes. Signal values can change either by the user by calling fsm.signal(value), or as a result of entering a new state.
Order of Events
On a state change, events are emitted in the following order:
changed:signal
for any changed output/signalsstate