FSM to mermaid

A tool to generate mermaid state diagrams from existing Finite State Machines (FSM).

Why do we need this tool? Especially if we already have awesome visual editors?

• This tool generates static mermaid state diagram for documentation purposes.

• There is no need for interactivity and two-way roundtrip synchronisation. Just one-way, cheap, fast and easy to maintain manner.

• Because it is one-way, source of truth remains with the code and we iterate from there.

• Diagram is generated from statically declared state machine objects and not from parsing code. We traverse the FSM object model to produce the mermaid script.

• Diagram could be generated from CI/CD pipeline by invocation via unit test framework like Jest or Mocha.

• The generated mermaid script could be inserted into existing markdown like README.md or any other forms of markdown based documentation and static sites.

Roadmap

Currently, this tool is at Minimum Viable Product (MVP) phase. There could be certain cases that it might not handle correctly.

Any problems and feedback, just log an issue here.

Thank you for your contributions to making things better!

For the start, only XState is supported.

• XState

Other FSM libraries to be supported.

• robot3
• machina

XState to mermaid

npm install xstate fsm2mermaid

You could test drive from Node interactive mode.

node

Welcome to Node.js v18.13.0.
Type ".help" for more information.
>

const xstate = require("xstate");
const fsm2mermaid = require("fsm2mermaid");

let simpleMachine = xstate.createMachine(
  {
    id: "simple",
    initial: "lightsOff",
    states: {
      lightsOn: {
        on: {
          toggle: {
            target: "lightsOff",
          },
        },
      },
      lightsOff: {
        on: {
          toggle: {
            target: "lightsOn",
          },
        },
      }
    }
  },
  {
    actions: {},
    actors: {},
    guards: {},
    delays: {},
  });

let simpleMermaid = generateMermaidFromXState(simpleMachine);
console.log(simpleMermaid);

stateDiagram-v2
simple : simple
state simple {
  [*] --> simple.lightsOff
  simple.lightsOn : lightsOn
  simple.lightsOn --> simple.lightsOff : toggle
  simple.lightsOff : lightsOff
  simple.lightsOff --> simple.lightsOn : toggle
}

Rendering the markdown with mermaid plugin gives us the following.

stateDiagram-v2
simple : simple
state simple {
  [*] --> simple.lightsOff
  simple.lightsOn : lightsOn
  simple.lightsOn --> simple.lightsOff : toggle
  simple.lightsOff : lightsOff
  simple.lightsOff --> simple.lightsOn : toggle
}

And the equivalent using ECMAScript Module (ESM) syntax.

import {createMachine} from "xstate"
import {generateMermaidFromXState} from "fsm2mermaid"

let simpleMachine = createMachine(
  {
    id: "simple",
    initial: "lightsOff",
    states: {
      lightsOn: {
        on: {
          toggle: {
            target: "lightsOff",
          },
        },
      },
      lightsOff: {
        on: {
          toggle: {
            target: "lightsOn",
          },
        },
      }
    }
  },
  {
    actions: {},
    actors: {},
    guards: {},
    delays: {},
  });

let simpleMermaid = generateMermaidFromXState(simpleMachine);

console.log(simpleMermaid);

stateDiagram-v2
simple : simple
state simple {
  [*] --> simple.lightsOff
  simple.lightsOn : lightsOn
  simple.lightsOn --> simple.lightsOff : toggle
  simple.lightsOff : lightsOff
  simple.lightsOff --> simple.lightsOn : toggle
}

Developer Documentation

The following are quick notes for development use.

Set npm cache to local

Docker build will rely on this to speed up

npm config set cache .npm

Install all dependencies and setup commit hook

npm install

Running linters

To perform a check

npm run lint

To Auto fix as much as possible.

npm run lint-fix

Check on commit message format

npx commitlint --from=HEAD

Running unit tests

For local run.

npm run test

For running tests in Gitlab CI.

npm run test:ci

Docker image for test and publish in Gitlab CI/CD

Building and updating image on Gitlab registry.

docker login registry.gitlab.com
docker build -t registry.gitlab.com/kaikokchew/fsm2mermaid/runner:latest --build-arg GL_PROJ_GROUP=kaikokchew --build-arg GL_PROJ_NAME=fsm2mermaid --progress=plain .
docker push registry.gitlab.com/kaikokchew/fsm2mermaid/runner:latest

Running and testing image on local.

docker run -it -v $(pwd):/builds/kaikokchew/fsm2mermaid --rm registry.gitlab.com/kaikokchew/fsm2mermaid/runner sh

Configuring pre-commit hooks

Typically this is already done as part of first time npm installation.

npm install --save-dev husky
npm pkg set scripts.commitlint="commitlint --edit"
echo "npm run commitlint \${1}" > .husky/commit-msg
npm pkg set scripts.pre-commit="npm run lint"
echo "npm run pre-commit \${1}" > .husky/pre-commit

Building your package

npm run build