Stately.js is a JavaScript based finite-state machine (FSM) engine for Node.js and the browser.
npm install stately.jsStately.js is a JavaScript based finite-state machine (FSM) engine for Node.js
and the browser.
In Node.js you can install Stately.js with npm:
$ npm install stately.js
and include it to your project by:
``js`
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:
`html`
or with Asynchronous Module Definition by e.g.:
`html`
A new state machine can be created with either the new operator:
`js`
var machine = new Stately(statesObject, initialStateName);
or the factory method:
`js`
var machine = Stately.machine(statesObject, initialStateName);
Both will return a new stateMachine object, with all events from all statesinitialStateName
attached to it. The machine will transition into the initial state
or the first attached if initialStateName is omitted. In additionstateMachine
to the events the object has a getMachineState() method, returninggetMachineEvents()
the current name of the machines state, , returning possible
events in the current state.
The statesObject is an object with stateObject objects attached asstatesObject
properties.
The property names of the are the states of the machine.stateObject
The attached objects model the machines states with the propertyevents
names as and the connected functions as actions:
`js`
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 upaction
and the machine handles calling the correct for the current state (ifevent
the 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 as string directly:
`js`
var machine = Stately.machine({
'STATE0': {
'event': / => / 'STATE1'
},
'STATE1': {
'event': / => / 'STATE2'
},
'STATE2': {
'event': / => / 'STATE0',
'anotherEvent': / => / 'STATE1'
}
});
There are several ways an action can transition the machine into anotherthis
state. The simplest form is returning the desired next state from an action.
Therefore, refers to the (internal) stateStore inside an action to
access the other states of the machine:
`js
...
'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:
`js
...
'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() andsetMachineState(nextState) accessible through the this reference of an
action:
`js
...
'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 annotification
action from another state (note: this won't trigger the s):
`js
...
'STATE1': {
doSomething: function () {
...
this.STATE2.doSomethingDifferent.call(this);
...
return this.STATE3.doSomethingCompletelyDifferent.call(this);
}
}
...
`
Once in a while, it is useful to get a notification when the machineonEnter
transitions into another state. Therefore there are some special event names
reserved for event functions, namely , onLeave (triggeredonBefore
when entering / leaving a state), and onAfter
(triggered before or after calling an event).
The event function has the following signature:
`js`
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.
`js
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;
`
`js
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
``