Nodejs State Machine

Simple state machine management in Node JS without any external dependency.

V2 moved to async transitions using promises.

Prerequisites

Works only on node >=6.1.4

Signature

StateMachine(initialState,options)

• initialState - initial state to be used when instantiating state machine
• options - options object (refer below for details)

Installing

npm install nodejs-state-machine

Usage

const StateMachine = require('nodejs-state-machine');
const { StateMachineError, errorCodes } = require('nodejs-state-machine/errors');
//trying to instantiate a state machine with a non existing initial state across transitions will throw error
const radio = new StateMachine('off', {
    transitions: [
        { name: "play song", from: "on", to: "playing" },
        { name: "turnOff", from: ["playing", "on", "paused"], to: "off" },
        { name: "turnOn", from: "off", to: "on" },
        { name: "pause", from: "playing", to: "paused" }
    ],
    handlers: {
        onPlaySong: (param) => {
            console.log('playing song');
        },
        onTurnOff: () => {
            console.log('turned off');
            return true;
        },
        onTurnOn: async (parameter) => {
            console.log('turned on');
            //returned parameter here will be the resolved value on radio.turnOn promise
            return task;
        },
        onPause: () => {
            console.log('paused')
        }
    }
});


try {
    await radio.playSong(); // notice how library automatically camel cases transition names for methods
} catch (err) {
    //will throw error invalid transition cannot play song when radio is in stopped initial state
    console.log(err);
    }
try {
    console.log(radio.can('playSong')); //false
    console.log(radio.availableTransitions());
    console.log(radio.can('turnOn')); //true
    console.log(await radio.turnOn('parameter')); // returns target state, "on"
    console.log(radio.availableTransitions());
    console.log(radio.is('on')); //check if radio is in on state, returns true
    console.log(await radio.turnOff()); // returns target state, "off"
    console.log(radio.reset('playing')); // helper method if one wants to reuse same state machine object, although not really recommended
    console.log(await radio.turnOn()); // will throw exception

} catch (err) {
    //catch turn on error
    if (err instanceof StateMachineError) {
        //you can also distinguish for StateMachineError if you only have a single error handler
        //State Machine Error contains an errorCode in addition to the core Error message and stack peroperties
        //Error codes can be accessed via errors module using errors.errorCodes 
        console.log(err);
    }
}

Available options parameters

• transitions - transitions array definition ([ { name:, from:, to: }])
• handlers - handler functions definition

API

• camel cased methods for transition names - Methods to change internal state defined by transition names : returns changed state or throws error
• is(state) - Method to check if state machine is in a certain state : boolean
• can(transitionName) - Check if a given transition can occur on the current state : boolean
• reset(state) - Method to reset state machine to a given state : returns current state or throws error
• availableTransitions() - Method to return a list of all available transition names from the current state : list of transitions

All states and transitions of the StateMachine can be retrieved by using stateMachineInstance.states or stateMachineInstance.transitions ( will return a ES6 SET ).

Events

State machine extends node's event emitter, so you can listen to events from it:

• stateChanged(from, to, transitionName) - Triggered when a transition method was executed successfully. Can be useful for logging for example.

State Management Overview

For better description about managing the state, note that we use 2 main concepts: transition and state.

• Transition is defined by a name, source state and target state.
• State is defining the state in which the state machine can be at some point.

StateMachine will be crawling through all the transition states and create a unique set of them, in order to gather all the possible states. Transition names should be unique as well, and note that for managing a transition where the target state can occur from multiple sources, you can either define multiple transitions using the SAME name, or specify from property as array.

Considerations

• Current implementation of the state machine is synchronous, so any async processing before or after changing the state should be done outside of the framework. If you need some more features, please feel free to file a feature request

Authors

• Tudor Suditu - Initial work - (https://github.com/tudor33sud)

Want to contribute?

You can send me an e-mail at [email protected]

License

This project is licensed under the MIT License