What is it?
Stately.js is a JavaScript based finite-state machine (FSM) engine for Node.js and the browser.
Installation
In Node.js you can install Stately.js with npm
:
$ npm install stately.js
and include it to your project by:
var Stately = ;
Alternately, you can install Stately.js with bower
:
$ bower install --save Stately.js
In browsers you can include it directly by adding it to the document head section:
or with Asynchronous Module Definition by e.g.:
Usage
Creating a new machine
A new state machine can be created with either the new operator:
var machine = statesObject initialStateName;
or the factory method:
var machine = Stately;
Both will return a new stateMachine
object, with all events from all states
attached to it. The machine will transition into the initial state initialStateName
or the first attached stateObject
if initialStateName
is omitted. In addition
to the events the stateMachine
object has a getMachineState()
method, returning
the current name of the machines state, getMachineEvents()
, returning possible
events in the current state.
The statesObject
is an object with stateObject
objects attached as
properties.
The property names of the statesObject
are the states
of the machine.
The attached stateObject
objects model the machines states with the property
names as events
and the connected functions as actions
:
var machine = Stately;
If different states use the same event identifier, the events
are chained up
and the machine handles calling the correct action
for the current state (if
the event
is handled in the current state). If the event is not handled in
the current state, it is ignored.
If no immediate action
needs to be declared, the desired transition state
can be attached to the event
as string directly:
var machine = Stately;
Transitions
There are several ways an action
can transition the machine into another
state. The simplest form is returning the desired next state from an action.
Therefore, this
refers to the (internal) stateStore
inside an action
to
access the other states of the machine:
... 'STATE1': { ... //transition from STATE1 to STATE2 return thisSTATE2; // as an alternative just return the new state as string // return 'STATE2'; } ...
If an action should not transition the machine into another state, just omit the return value (or return the current state).
Sometimes it is desired to return a value from an action. In this case the return value must be an array with two elements. The first element is the next state the machine should transition into, and the second element the return value:
... 'STATE1': { ... //transition from STATE1 to STATE2 and return a string return thisSTATE2 'this is a return value'; } ...
For asynchronous actions there are getMachineState()
and
setMachineState(nextState)
accessible through the this
reference of an
action:
... 'STATE1': { var self = this; ; ... } ...
Because this
refers to the stateStore
, it is also possible to call an
action from another state (note: this won't trigger the notification
s):
... 'STATE1': { ... thisSTATE2doSomethingDifferent; ... return thisSTATE3doSomethingCompletelyDifferent; } ...
Special event hook functions
Once in a while, it is useful to get a notification
when the machine
transitions into another state. Therefore there are some special event names
reserved for event functions, namely onEnter
, onLeave
(triggered
when entering / leaving a state), onBefore<eventname>
and onAfter<eventname>
(triggered before or after calling an event).
The event function has the following signature:
{ ...}
event
- The event that triggered the transition.
oldState
- The old state the machine is transitioned from.
newState
- The new state the machine is transitioned into.
Inside these functions, this
refers to the internal stateStore
.
Examples
Door
var door = Stately; //the initial state of the door is open (it's the first state object)console; // true; //close and lock the doordoor;console; // true; //try to open itdoor;console; // false; //unlock, open, lock (is ignored because it fails), close, and lockdoor;console; // true; //the door is still locked, break itdoor;console; // true; //fix opens the door, close it, lock it, break it againdoor;console; // true; //and again fix opens the door, close it, lock it, break itdoor;console; // true; //fixing is limited, the door stays brokendoor;console; // false;console; // true;
Radio
{ var transition = oldState + ' => ' + newState; } var radio = Stately; radio;//STOPPED => PLAYING//PLAYING => PAUSED//PAUSED => PLAYING//PLAYING => PAUSED//PAUSED => STOPPED