State Machine

Overview

State Machine is a powerful yet simply-configured state machine.

Its intuitive yet powerful DSL can describe states and transitions succinctly whilst its JavaScript API hooks into transitions with a rich event syntax to build complex application flows:

const transitions = [
  'warn  : green > yellow',
  'panic : green   yellow > red',
  'calm  :         yellow < red',
  'clear : green < yellow   red'
]

The interactive demo above shows-off many of StateMachine's features. Visit the site itself and view the source code directly in the page, or open the console here to see the application log updates as it transitions between states and fires events.

Implementation

The library itself is built as a stand-alone library with two component parts:

• the DSL lexer and parser
• the state machine engine

The syntax of the library consists of the transition setup (text or object format) and optional handlers:

const config = {

  transitions: [
    'warn  : green > yellow',
    'panic : green   yellow > red',
    'calm  :         yellow < red',
    'clear : green < yellow   red',
  ],

  handlers: {
    'action:end': function (event) {
      console.info(event.transition)
    },
    'red:leave': function (event, fsm) {
      console.log(event)
      fsm.pause()
      setTimeout(function () {
        fsm.resume()
      }, 1000)
    },
  },

}

const fsm = new StateMachine(config)

The above is the classic traffic light example, with some additional handlers to show off the API.

The library can be used standalone (as per the examples) or with helpers to power jQuery, Angular or Vue.

Reflection

At the time of writing

I built State Machine after becoming interested in state machines as a potential solution to complex user flows such as checkouts or multi-step forms.

As it happens, I've never used it in production, and it's just ended up as a cool technology investigation.

If I had the time and inclination to continue this project, the main aims would be:

• decouple the notation DSL from the core library
• add support for nested state machines

In 2026

I would imagine these days if you wanted to use state machines, you would look at X State.

A fun next step for this library would be enabling the DSL to build state machines for that library, however, I recently learned that Mermaid supports state diagrams, so perhaps the next step would be to build a Mermaid plugin to generate X State machines from Mermaid state diagrams:

stateDiagram-v2
  [*] --> Green

  Green --> Yellow : warn
  Green --> Red : panic
  Yellow --> Red : panic

  Red --> Yellow : calm

  Yellow --> Green : clear
  Red --> Green : clear

Check out the visualisation for this state tree on Graphlet.

Links

• statemachine.netlify.app
• GitHub