FSM Core: Getting Started

@statewalker/fsm

This document contains a step-by-step guide on how to install the @statewalker/fsm library, create, and execute a basic process modeling the behavior of a light bulb:

The resulting working application:


  




Step 0: Installation


> npm install "@statewalker/fsm"



You can also directly include reference to the library using CDN:


import { FsmProcess } from "https://unpkg.com/@statewalker/fsm";

import { FsmProcess } from "https://cdn.jsdelivr.net/npm/@statewalker/fsm";



Step 1: Configuration


Process configuration:


const processConfig = {
  key: "LightBulb",
  transitions: [
    ["", "*", "Off"],
    ["Off", "toggle", "On"],
    ["On", "toggle", "Off"],
  ],
};



Transitions contains triples of keys:


    

  1. The previous state; empty string for initial states
    2. 

  2. The event triggering this transition
    3. 

  3. The target state; empty string for exit states
    4. 



Note: For more information see the Core Concepts section.


Step 2: Instantiate the process


import { FsmProcess, type FsmState } from "@statewalker/fsm";
const processConfig = {
  key: "LightBulb",
  transitions: [
    ["", "*", "Off"],
    ["Off", "toggle", "On"],
    ["On", "toggle", "Off"],
  ],
};
const process = new FsmProcess(processConfig);



Step 3: Associate behavior with individual states


This is the most important step – here we define specific actions for each individual step in our process.


Note: See the API section for more details.


// This method is called each time when a new state is created
process.onStateCreate((state: FsmState) => {
  // Add a handler to call when the process enters in a state
  state.onEnter(async () => {
    console.log(`<${state.key} event="${state.process.event}">`);
  });

  // Handler to call when the state is finished
  state.onEnter(async () => {
    console.log(`</${state.key}> <!-- event="${state.process.event}" -->`);
  });
});



Step 4: Start the process


To activate the initial transition we need to sent a message to our process:


process.dispatch("start");



Everything together


A short version of a processes declaration.


import { FsmProcess, type FsmState } from "@statewalker/fsm";
{
  const processConfig = {
    key: "LightBulb",
    transitions: [
      ["", "*", "Off"],
      ["Off", "toggle", "On"],
      ["On", "toggle", "Off"],
    ],
  };
  const process = new FsmProcess(processConfig);
  process.onStateCreate((state) => {
    state.onEnter(async () => {
      console.log("ENTER: ", state.key);
    });
    state.onEnter(async () => {
      console.log("EXIT: ", state.key);
    });
  });
  process.dispatch("start");
}



The example below contains a longer version with two independent states handlers. One handler performs logging and another one manipulates DOM nodes. A button event listener fires events and triggers states transitions.


import { FsmProcess, type FsmState } from "@statewalker/fsm";

// Step 1: Define the process configuration.
const processConfig = {
  key: "LightBulb",
  transitions: [
    // The initial transition; valid for all types of events
    ["", "*", "Off"],
    // A toggle will switch the light on
    ["Off", "toggle", "On"],
    // A toggle will switch the light off
    ["On", "toggle", "Off"],
  ],
};

// Step 2: Instantiate the process
// At this stage the process can not do anything.
const process = new FsmProcess(processConfig);

// Step 3: Add behavious for invdividual states.
// In this example we add two independent states handlers -
// one to log states transitions and another one for DOM manipulations.

// Add logger
{
  process.onStateCreate((state: FsmState) => {
    state.onEnter(async () => {
      console.log(`<${state.key} event="${state.process.event}">`);
    });
    state.onEnter(async () => {
      console.log(`</${state.key}> <!-- event="${state.process.event}" -->`);
    });
  });
}

// Initialize interactivity: fire transitions when user clicks on a button:
const lightBulbButton = document.querySelector(
  "#light-bulb-example .light-bulb-switch",
);
// Fire transition when the button is clicked
lightBulbButton.addEventListener("click", () => {
  process.dispatch("toggle");
});

// Add state-specific DOM manipulation methods
{
  // Example of state-specific actions
  const lightBulbContainer = document.querySelector("#light-bulb-example");
  const handlers = {
    On: () => {
      // Add a CSS class when the "On" state is activated
      lightBulbContainer.classList.add("active");
    },
    Off: () => {
      // Reset CSS when the bulb is switched off
      lightBulbContainer.classList.remove("active");
    },
  };
  // This method selects a state specific action and, if found, executes it.
  process.onStateCreate((state) => {
    const handler = handlers[state.key];
    if (!handler) return;

    let cleanup: undefined | (() => void | Promise<void>);
    state.onEnter(async () => {
      cleanup = await handler();
    });
    state.onEnter(async () => {
      cleanup?.();
    });
  });
}

// Step 4: start the process!
process.dispatch("start");