@basementuniverse/simple-state-machine

Simple State Machine

Define finite state machines and validate state transitions.

This library doesn't currently provide state-change events or methods for transitioning between states; all it does is provide a format for defining state machines, and a method for checking that a given transition is valid.

Installation

npm install @basementuniverse/simple-state-machine

Usage

import {
  StateMachine,
  validateTransition,
} from '@basementuniverse/simple-state-machine';

// Define a finite state machine
const myStateMachine: StateMachine = {
  open: [
    'closedAndUnlocked',
  ],
  closedAndUnlocked: [
    'open',
    'closedAndLocked',
  ],
  closedAndLocked: [
    'closedAndUnlocked',
  ],
};

// Let's validate some transitions...
let result: boolean = false;

// Test #1
result = validateTransition(
  myStateMachine,
  'open',
  'closedAndUnlocked'
);

// result will be true (this is a valid transition)
console.assert(result);


// Test #2
result = validateTransition(
  myStateMachine,
  'closedAndLocked',
  'open'
);

// result will be false (this is not a valid transition)
console.assert(!result);


// Test #3
result = validateTransition(
  myStateMachine,
  'open',
  'closedAndLocked',
  {
    throwErrors: true,
  }
);
// this will throw an error with the message:
// "Invalid state transition: unable to transition from 'open' to 'closedAndLocked'."

// Test #4
result = validateTransition(
  myStateMachine,
  'open',
  'open',
  {
    allowSelfTransition: true,
  }
);

// result will be true (this is a valid transition even though it's not explicitly defined)
console.assert(result);

Options

The validateTransition function accepts an optional options object as its fourth argument. The following options are available:

Option	Type	Default	Description
allowSelfTransition	boolean	true	If true, a transition from a state to itself will be considered valid.
throwErrors	boolean	false	If true, an error will be thrown if the transition is invalid.