@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

_{XState for Finite State Machines}

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

• Read the full documentation in the XState docs.
• Read our contribution guidelines.

Features

	@xstate/fsm	XState
Finite states	✅	✅
Initial state	✅	✅
Transitions (object)	✅	✅
Transitions (string target)	✅	✅
Delayed transitions	❌	✅
Eventless transitions	❌	✅
Nested states	❌	✅
Parallel states	❌	✅
History states	❌	✅
Final states	❌	✅
Context	✅	✅
Entry actions	✅	✅
Exit actions	✅	✅
Transition actions	✅	✅
Parameterized actions	❌	✅
Transition guards	✅	✅
Parameterized guards	❌	✅
Spawned actors	❌	✅
Invoked actors	❌	✅

• 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.

Quick start

Installation

npm i @xstate/fsm

Usage (machine)

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

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

const { initialState } = toggleMachine;

const toggledState = toggleMachine.transition(initialState, { type: 'TOGGLE' });
toggledState.value;
const untoggledState = toggleMachine.transition(toggledState, {
  type: 'TOGGLE'
});
untoggledState.value;
// => 'inactive'

Usage (service)

import { createMachine, interpret } from '@xstate/fsm';

const toggleMachine = createMachine({});

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

toggleService.subscribe((state) => {
  console.log(state.value);
});

toggleService.send({ type: 'TOGGLE' });
toggleService.send({ type: 'TOGGLE' });
toggleService.stop();