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 = require('stately.js');
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:
<script type="text/javascript" src="https://raw.github.com/fschaefer/Stately.js/master/Stately.js"></script>
<script type="text/javascript">
// use Stately
</script>
or with Asynchronous Module Definition by e.g.:
<script type="text/javascript" src="https://raw.github.com/jrburke/requirejs/master/require.js"></script>
<script type="text/javascript">
require(['https://raw.github.com/fschaefer/Stately.js/master/Stately.js'], function (Stately) {
// use Stately
});
</script>
Usage
Creating a new machine
A new state machine can be created with either the new operator:
var machine = new Stately(statesObject, initialStateName);
or the factory method:
var machine = Stately.machine(statesObject, initialStateName);
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.machine({
'STATE0': {
event: function () {
...
}
},
'STATE1': {
event: function () {
...
}
},
'STATE2':{
event: function () {
...
},
anotherEvent: function () {
...
}
}
});
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.machine({
'STATE0': {
'event': /* => */ 'STATE1'
},
'STATE1': {
'event': /* => */ 'STATE2'
},
'STATE2': {
'event': /* => */ 'STATE0',
'anotherEvent': /* => */ 'STATE1'
}
});
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': {
doSomething: function () {
...
//transition from STATE1 to STATE2
return this.STATE2;
// 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': {
doSomething: function () {
...
//transition from STATE1 to STATE2 and return a string
return [this.STATE2, 'this is a return value'];
}
}
...
For asynchronous actions there are getMachineState() and
setMachineState(nextState) accessible through the this reference of an
action:
...
'STATE1': {
doSomething: function () {
var self = this;
setTimeout(function () {
...
self.setMachineState(self.STATE2);
}, 5000);
...
}
}
...
Because this refers to the stateStore, it is also possible to call an
action from another state (note: this won't trigger the notifications):
...
'STATE1': {
doSomething: function () {
...
this.STATE2.doSomethingDifferent.call(this);
...
return this.STATE3.doSomethingCompletelyDifferent.call(this);
}
}
...
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:
function (event, oldState, newState) {
...
}
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.machine({
'OPEN': {
'close': /* => */ 'CLOSED'
},
'CLOSED': {
'open': /* => */ 'OPEN',
'lock': /* => */ 'LOCKED'
},
'LOCKED': {
'unlock': /* => */ 'CLOSED',
'break': /* => */ 'BROKEN'
},
'BROKEN': {
'fix': function () {
this.fixed = (this.fixed === undefined ? 1 : ++this.fixed);
return this.fixed < 3 ? this.OPEN : this.BROKEN;
}
}
});
//the initial state of the door is open (it's the first state object)
console.log(door.getMachineState() === 'OPEN'); // true;
//close and lock the door
door.close().lock();
console.log(door.getMachineState() === 'LOCKED'); // true;
//try to open it
door.open();
console.log(door.getMachineState() === 'OPEN'); // false;
//unlock, open, lock (is ignored because it fails), close, and lock
door.unlock().open().lock().close().lock();
console.log(door.getMachineState() === 'LOCKED'); // true;
//the door is still locked, break it
door.break();
console.log(door.getMachineState() === 'BROKEN'); // true;
//fix opens the door, close it, lock it, break it again
door.fix().close().lock().break();
console.log(door.getMachineState() === 'BROKEN'); // true;
//and again fix opens the door, close it, lock it, break it
door.fix().close().lock().break();
console.log(door.getMachineState() === 'BROKEN'); // true;
//fixing is limited, the door stays broken
door.fix();
console.log(door.getMachineState() === 'OPEN'); // false;
console.log(door.getMachineState() === 'BROKEN'); // true;
Radio
function reporter(event, oldState, newState) {
var transition = oldState + ' => ' + newState;
switch (transition) {
/*
...
case 'STOPPED => PLAYING':
case 'PLAYING => PAUSED':
...
*/
default:
console.log(transition);
break;
}
}
var radio = Stately.machine({
'STOPPED': {
onEnter: reporter,
play: function () {
return this.PLAYING;
}
},
'PLAYING': {
onEnter: reporter,
stop: function () {
return this.STOPPED;
},
pause: function () {
return this.PAUSED;
}
},
'PAUSED': {
onEnter: reporter,
play: function () {
return this.PLAYING;
},
stop: function () {
return this.STOPPED;
}
}
});
radio.play().pause().play().pause().stop();
//STOPPED => PLAYING
//PLAYING => PAUSED
//PAUSED => PLAYING
//PLAYING => PAUSED
//PAUSED => STOPPED