@urbn/state-machine

state-machine

• Description
• Usage
• Why use a State Machine?
• Prior Art
• Other Libraries
• Diagrams
• API Documentation
• Packaged Module Format

Description

state-machine is a Javascript Finite State Machine implementation with the following design goals:

• Minimal in size
• Enforces a static and explicit configuration. This means two things:
  • All possible states/transitions must be defined upon machine creation
  • A given transition from a state goes to a single deterministic destination state

Usage

Install and save the library:

npm install --save @urbn/state-machine

Use the library in your application:

const stopLight = new StateMachine({
    states: {
        green: {
            transitions: { 
                change: 'yellow',
            },
        },
        yellow: {
            transitions: { 
                change: 'red',
            },
        },
        red: {
            transitions: { 
                change: 'green',
            },
        },
    },
    onEnter(data, newState, oldState) {
        console.log(`Transitioned from ${oldState} -> ${newState}`);
    },
}, 'red');
 
setInterval(() => stopLight.transition('change'), 3000);

Why use a State Machine?

It can be advantageous in user-interface development to think of your interface as a Finite State Machine. When implemented correctly, this can have a number of benefits over simply representing application "state" as a combination of local application data or fields in a shared Redux/Vuex store.

A few of these benefits are:

• Ability to visualize the various states and transitions of the UI
• Common language in which to communicate between developers, QA engineers, interface designers, business analysts, etc.
• Enforced coverage and consideration of error states and edge cases

Prior Art

State Machines are nothing new in Computer Science - they are known to be incredibly robust, and are often chosen to control mission critical systems. However, what is relatively new as of ~2018 is the concept of representing front end application state as a state machine. There are plenty of great articles/videos on the subject, so we'll just link to them and won't bother to re-hash them all here.

• Our specific use-case is a Finite State Machine, also known as a Mealy Machine - initially conceived in 1955 😮
• Video: Infinitely Better UIs with Finite Automata
• The Rise of State Machines
• Upgrade your React UI with state machines
• Restate Your UI: Using State Machines to Simplify User Interface Development

Other Libraries

state-machine was born after a quick evaluation of a few other open-source libraries. All of these other libraries have merit, they just weren't quite the right fit for our needs.

• xstate - Seemingly the most robust library which goes well beyond simple FSM, but quite large in size (9Kb gzipped)
• javascript-state-machine - Uses a transition-first machine definition, as compared to our preferred state-first definition
• Stately.js - Very similar in implementation to this library, but with 2 small issues:
  • The usage of action functions to determine destination state went against our design goal of explicit/deterministic state transitions
  • The current state is private and thus hard to wire up to Vue's reactivity

Diagrams

state-machine is capable of automatically generating diagrams of a given State Machine that can be opened with the GraphViz tool. The tool can be installed with brew install graphviz --with-app, and then used via the command line dot tool, or opened from /usr/local/Cellar/graphviz/[version]/GraphViz.app.

To generate your state-machine diagrams, simply call the .getDotFile() method on an instantiated StateMachine instance and print it out to the console, and save it in a .dot file. Notre that this only works when NODE_ENV !== 'production'.

API Documentation

Constructor

The constructor requires both the machine configuration and the initial state for the machine, and will throw an error if either are invalid.

const machine = new StateMachine(configuration, initialState, initialStateErrorHandler?);

The full structure of the configuration object is as follows:

{
    // The `states` field is an object with keys for every possible state
    states: {
        STATE1: {
            // The `transitions` object lists all possible transitions out of 
            // STATE1 and their destination states
            transitions: {
                GO_TO_STATE2: 'STATE2',
            },
            // Callback function fired anytime STATE1 is entered
            onEnter(data, newState, oldState, transition) { ... }
        },
        // If a state is a terminal state, it doesn't need to provide any transitions
        STATE2: null,
        ...
    },
    // Callback function anytime the state changes
    onEnter(data, newState, oldState, transition) { ... }
}

Asyncronous onEnter functions

onEnter functions can return promises if they need to handle asynchronous actions, and these promises will be proxied back as the return value for the .transition() call that entered the state. See the .transition documentation below for examples.

initialStateErrorHandler

Because of the async nature of state onEnter functions, initialStateErrorHandler can be passed to handle promise rejections from the initialState's onEnter function that will be executed on the initial transition.

currentState

Returns the current machine state name

const machine = new StateMachine({ 
    states: { 
        purgatory: null,
    },
}, 'purgatory');

console.log(machine.currentState);
// -> 'purgatory'

getDotFile()

In development mode only (NODE_ENV !== 'production'), returns a string of the machine diagram as a DOT file. See the Diagrams section for more information.

const machine = new StateMachine({
    states: {
        off: {
            transitions: {
                start: 'on',
            },
        },
        on: {
            transitions: {
                stop: 'off',
            },
        },
    },
}, 'off');

console.log(machine.getDotFile());
// -> 'digraph "fsm" {
//       "off";
//       "on";
//       "off" -> "on" [label="start"];
//       "on" -> "off" [label="stop"];
//     }'

transition(transitionName, payload)

Transitions the machine from a current state to a new state, returning a resolved promise when the transition is complete, or a rejected promise if the transition is invalid or of the destination state onEnter function rejects.

Synchronous Transitions

const machine = new StateMachine({
    states: {
        off: {
            transitions: {
                start: 'on',
            },
        },
        on: {
            transitions: {
                stop: 'off',
            },
            onEnter() {
                console.log('Entered the on state');
            },
        },
    },
}, 'off');

console.log(machine.currentState);
// -> 'off'

machine.transition('start');
// -> 'Entered the on state'

console.log(machine.currentState);
// -> 'on'

Asynchronous Transitions

Asyncronous onEnter functions can be used along with promise-based transitions as follows:

const machine = new StateMachine({
    states: {
        empty: {
            transitions: {
                fetchData: 'fetching',
            },
        },
        fetching: {
            transitions: {
                doneFetching: 'showData',
            },
            async onEnter(userId) {
                const data = await fetchSomeData(userId);
                machine.transition('doneFetching', data);
                return data;
            }
        },
        showData: null,
    },
}, 'empty');

console.log(machine.currentState);
// -> 'empty'

const user1 = await machine.transition('fetchData', 'user-1')
// user1 will contain the fetched data from the onEnter return value

console.log(machine.currentState);
// -> 'showData'

Packaged Module Format

This library currently makes a few assumptions about the consuming client applications, however these may be removed in future versions.

• You are transpiling to ES5 code as necessary for your Node/Browser versions - this library uses ES6 features such as const, let, Object.entries, etc.
• You can support CommonJS modules - this library is not distributed in ESM or UMD module formats
• You are minifying your bundled code - this library is not distributed in a minified form