@xstate/fsm

What is @xstate/fsm?

@xstate/fsm is a lightweight finite state machine library for JavaScript and TypeScript. It allows you to model the behavior of your application in a predictable way by defining states and transitions. This can help manage complex state logic in a more maintainable and understandable manner.

What are @xstate/fsm's main functionalities?

Define a Finite State Machine

This feature allows you to define a finite state machine with states and transitions. In this example, a simple toggle machine is created with two states: 'inactive' and 'active'. The machine transitions between these states on the 'TOGGLE' event.

const { createMachine } = require('@xstate/fsm');

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

console.log(toggleMachine.initialState); // { value: 'inactive' }

Transition Between States

This feature allows you to transition between states using the 'send' method. The example demonstrates how to start the machine and transition from 'inactive' to 'active' state by sending the 'TOGGLE' event.

const { createMachine, interpret } = require('@xstate/fsm');

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

const toggleService = interpret(toggleMachine).start();

console.log(toggleService.state.value); // 'inactive'
toggleService.send('TOGGLE');
console.log(toggleService.state.value); // 'active'

State Actions

This feature allows you to define actions that should be executed when entering or exiting a state. The example shows how to log messages when entering and exiting the 'active' state.

const { createMachine, interpret } = require('@xstate/fsm');

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { 
      on: { TOGGLE: 'inactive' },
      entry: () => console.log('Entering active state'),
      exit: () => console.log('Exiting active state')
    }
  }
});

const toggleService = interpret(toggleMachine).start();
toggleService.send('TOGGLE'); // Logs: 'Entering active state'
toggleService.send('TOGGLE'); // Logs: 'Exiting active state'

Other packages similar to @xstate/fsm

robot3

robot3 is a finite state machine library for JavaScript that provides a simple API for defining states and transitions. It is similar to @xstate/fsm in that it allows you to model state logic in a predictable way, but it offers a more minimalistic approach.

javascript-state-machine

javascript-state-machine is a library for creating finite state machines in JavaScript. It provides a straightforward API for defining states and transitions, similar to @xstate/fsm. However, it is more focused on simplicity and ease of use, making it a good choice for smaller projects.

redux-saga

redux-saga is a library that aims to make application side effects (e.g., asynchronous actions) easier to manage, more efficient to execute, and better at handling failures. While it is not a finite state machine library per se, it can be used to manage complex state logic in a Redux application, similar to how @xstate/fsm can be used.

README

@xstate/fsm

This package contains a minimal implementation of XState for finite state machines.

Features:

• Finite states (non-nested)
• Initial state
• Transitions (object or strings)
• Context
• Entry actions
• Exit actions
• Transition actions
• state.changed

If you want to use statechart features such as nested states, parallel states, history states, activities, invoked services, delayed transitions, transient transitions, etc. please use XState.

Super quick start

npm i @xstate/fsm

import { FSM } from '@xstate/fsm';

// Stateless FSM definition
// machine.transition(...) is a pure function.
const toggleFSM = FSM({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
});

const { initialState } = toggleFSM;

const toggledState = toggleFSM.transition(initialState, 'TOGGLE');
toggledState.value;
// => 'active'

const untoggledState = toggleFSM.transition(toggledState, 'TOGGLE');
untoggledState.value;
// => 'inactive'

API

FSM(config)

Creates a new finite state machine (FSM) from the config, which has this schema:

Machine config

• id (string) - an identifier for the type of machine this is. Useful for debugging.
• initial (string) - the key of the initial state.
• states (object) - an object mapping state names (keys) to states

State config

• on (object) - an object mapping event types (keys) to transitions

Transition config

String syntax:

• (string) - the state name to transition to.
  • Same as { target: stateName }

Object syntax:

• target? (string) - the state name to transition to.
• actions? (Action | Action[]) - the action(s) to execute when this transition is taken.
• cond? (Guard) - the condition (predicate function) to test. If it returns true, the transition will be taken.

Action config

String syntax:

• (string) - the action type.
  • Resolves to { type: actionType, exec: undefined }

Function syntax:

• (function) - the action function to execute. Resolves to { type: actionFn.name, exec: actionFn } and the function takes the following arguments:
  1. context (any) - the machine's current context.
  2. event (object) - the event that caused the action to be executed.

Object syntax:

• type (string) - the action type.
• exec? (function) - the action function to execute.

Usage

import { FSM, assign } from '@xstate/fsm';

const lightFSM = FSM({
  id: 'light',
  initial: 'green',
  context: { redLights: 0 },
  states: {
    green: {
      on: {
        TIMER: 'yellow'
      }
    },
    yellow: {
      on: {
        TIMER: {
          target: 'red',
          actions: () => console.log('Going to red!')
        }
      }
    },
    red: {
      entry: assign({ redLights: ctx => ctx.redLights + 1 }),
      on: {
        TIMER: 'green'
      }
    }
  }
});

const { initialState } = lightFSM;
// {
//   value: 'green',
//   context: { redLights: 0 },
//   actions: [],
//   changed: undefined
// }

const yellowState = lightFSM.transition(initialState, 'TIMER');
// {
//   value: 'yellow',
//   context: { redLights: 0 },
//   actions: [
//     { type: undefined, exec: () => console.log('Going to red!') }
//   ],
//   changed: true
// }

const redState = lightFSM.transition(yellowState, 'TIMER');
// {
//   value: 'red',
//   context: { redLights: 1 },
//   actions: [],
//   changed: true
// }