object-fsm

Make any JavaScript object to be a finite state machine

Stable, production-ready and battle-tested. Supports NodeJS version 4 and later. Tested up to Node 10.

Installation

npm install object-fsm

How to use

var ObjectFsm = require('object-fsm');
 
// Any object can become an FSM
var light = {};
 
// Mix in ObjectFsm to the object
ObjectFsm(light);
 
light.addStates(['Green', 'Yellow', 'Red']);
light.setStartingState('Red'); // Current state -> Red
 
// Parameters are: eventName, stateFrom, stateTo, handlerFunc (see doc)
light.addEvent('go', 'Red', 'Green', function () {
    console.log('Let\'s go!');
});
 
light.addEvent('prepareToStop', 'Green', 'Yellow', function () {
    console.log('Prepare to stop...');
});
 
light.addEvent('stop', 'Yellow', 'Red', function () {
    console.log('Everybody stop!');
});
 
light.handleEvent('go'); // state: green
light.handleEvent('prepareToStop'); // state: yellow
light.handleEvent('stop');  // state: red

API Docs

ObjectFsm

Mixes FSM into the object.

Parameters

• obj The object that will become an FSM

addState

Adds a state to FSM Note that FSM automatically enters the state added first

Parameters

• state string State name

Returns boolean result Whether adding a state succeeded or not

addStates

Adds a list of states to FSM

Parameters

• states Array<string>

setStartingState

Sets a starting state. FSM immediately moves to that state.

Parameters

• state string

hasState

Returns true if FSM has state {state}

Parameters

• state

Returns boolean

hasEvent

Checks if FSM has given event

Parameters

• event string

Returns boolean

addEvent

Adds a new event to FSM

Parameters

• eventName string Event name
• statesFrom (Array<string> | string) A one or more states in which FSM can handle this event
• stateTo string State to which the event transitions FSM
• handler [function (Any): Any] Function that is invoked upon event

handleEvent

Notifies FSM about an event

Parameters

• event string Existing event
• arguments ...Any Will be passed to event handler

Returns Any Return value of the event handler

canHandleEvent

Returns true if FSM is able to handle event right now

Parameters

• event

Returns boolean

deferTransition

Defers an ongoing transition until future call to finalizeTransition. Use for any asynchronous event hanling. NOTE: this function can be called only in event handler (during an event), or in willTransition event handler.

finalizeTransition

Finalizes a deferred transition.

Testing

npm test

Runs tests of the source code located in src directory. Tests are located in test directory.

License

MIT