Skip to Content
👋 Добро пожаловать в документацию lite-fsm!

lite-fsm

Build StatusBundle Sizenpm versionnpm downloadsCoverage Status

lite-fsm — легковесная TypeScript-библиотека для описания конечных автоматов. Она выносит поведение приложения в явную модель состояний, событий и переходов, связывает автоматы общей шиной событий и в той же модели описывает динамические параллельные процессы — готовая архитектура для бизнес-логики проектов разного масштаба.

Быстрые ссылки

  • Playground: демо с исходниками, UI-сценариями и DevTools
  • Visualizer: визуальная модель автоматов на базе @lite-fsm/graph, диагностика FSM-структуры и симуляция событий

О библиотеке

В основе lite-fsm лежит модель конечного автомата: система находится в одном из известных состояний и меняет его только через описанные события. Runtime библиотеки добавляет к этой модели контекст, effects, middleware, snapshots и MachineManager для координации нескольких автоматов.

С помощью lite-fsm вы сможете:

  • Структурировать сложную интерактивную логику UI-компонентов
  • Организовывать и контролировать жизненные циклы процессов
  • Упрощать тестирование и отладку кода
  • Делать потоки управления данными явными
  • Избегать ошибок, связанных с неучтёнными состояниями

Ядро не зависит от UI-фреймворков, поэтому одна и та же модель работает в React, Node.js, worker-ах, тестах и приложениях без пользовательского интерфейса.

Почему конечные автоматы?

  • Ясная логика: когда состояния и переходы описаны явно, поведение проще читать и обсуждать
  • Надёжность: явная модель состояний снижает риск неучтённых состояний и недопустимых переходов
  • Самодокументируемость: Структура автомата естественным образом документирует поведение компонента или процесса
  • Снижение сложности: бизнес-логику можно разделить на дискретные состояния и правила перехода
  • Наглядность: состояния и переходы можно экспортировать в граф и анализировать отдельно от UI
  • Тестирование: детерминированные переходы проще покрывать unit-тестами

Ключевые возможности

  • Компактный API: описание config, reducer, effects и запуск через MachineManager
  • Композиция автоматов: разделение доменной логики на несколько независимых автоматов
  • Интеграция с React: хуки, provider и hydration boundary для React-приложений
  • Расширяемость через middleware: подключение Immer, Redux DevTools и собственных обработчиков
  • Типизация TypeScript: вывод состояний, событий, контекста и зависимостей effects
  • Небольшой runtime: Минимум обязательных зависимостей для базовых сценариев
  • Расширенные паттерны: actor templates, effects, snapshots и hydration
  • Прозрачная иммутабельность: Поддержка reducer-ов в стиле Immer через middleware

Быстрый старт

Установка

Runtime-пакеты доступны через npm.

npm install @lite-fsm/core @lite-fsm/middleware immer

Старт проекта с CLI

Если нужен React-проект с готовым MachineManager, начните через CLI и добавляйте автоматы по мере роста доменной логики:

npx @lite-fsm/cli create my-app --template vite
cd my-app
npx @lite-fsm/cli add-machine user-session
npm run dev

create собирает Next.js или Vite starter с src/store, React provider-ом и базовым автоматом app. add-machine создаёт src/store/machines/user-session.ts, регистрирует userSession в store и подключает его события к общему AppEvents.

Подробности, шаблоны, опции менеджера пакетов и ограничения generated store описаны в разделе @lite-fsm/cli.

Skill для работы с lite-fsm

Если вы используете Codex или другой агентный инструмент со skills, установите project skill для lite-fsm:

npx skills add https://github.com/AlexanderGureev/lite-fsm/tree/main/.agents/skills/lite-fsm

Пример использования

import { createMachine, MachineManager } from "@lite-fsm/core";
import { immerMiddleware } from "@lite-fsm/middleware/immer";
 
const lamp = createMachine({
  config: {
    OFF: {
      TURN_ON: "ON",
      RESET: "OFF",
    },
    ON: {
      TURN_OFF: "OFF",
      RESET: "OFF",
    },
  },
  initialState: "OFF",
  initialContext: {
    toggleCount: 0,
  },
  reducer: (state, action, { nextState }) => {
    state.state = nextState;
 
    if (action.type === "RESET") {
      state.context.toggleCount = 0;
      return;
    }
 
    state.context.toggleCount += 1;
  },
});
 
const manager = MachineManager({ lamp }, { middleware: [immerMiddleware] });
 
manager.onTransition((prev, next, action) => {
  console.log("[onTransition]", action.type, next.lamp);
});
 
manager.transition({ type: "TURN_ON" });
manager.transition({ type: "TURN_OFF" });
manager.transition({ type: "RESET" });
 
const { state, context } = manager.getState().lamp;

Состояния и события рекомендуем писать в UPPER_SNAKE_CASE. Reducer выше использует immerMiddleware — это позволяет мутировать state напрямую без return. Без middleware reducer должен возвращать новый объект { state, context }.

React: Для интеграции lite-fsm с React используйте специализированные хуки и компоненты, описанные в разделе @lite-fsm/react.

TypeScript: Если вы используете TypeScript, посмотрите раздел TypeScript: там показаны типизированные фабрики, события и React-хуки.

Playground: Примеры с исходниками — sync-автоматы, async-эффекты, actor templates и SSR-streaming — доступны в playground.

Куда дальше?

После ознакомления с основами, вы можете изучить другие разделы документации:

  • Конечные автоматы: Подробное описание концепций FSM и statecharts
  • Акторы: Динамические шаблоны автоматов для параллельных процессов и задач
  • Hydration и snapshots: SSR, snapshot, hydrate/dehydrate и FSMHydrationBoundary
  • Продвинутые концепции: Углублённое изучение возможностей библиотеки
  • Лучшие практики: Практические рекомендации по проектированию автоматов
  • Пакеты: Обзор @lite-fsm/core, @lite-fsm/react, @lite-fsm/middleware, @lite-fsm/persist, @lite-fsm/graph и @lite-fsm/cli
  • @lite-fsm/react: Руководство по интеграции с React-приложениями
  • Практика: TypeScript и Next.js интеграции
  • API: Полная документация по всем функциям и параметрам
  • @lite-fsm/middleware: Расширение функциональности с помощью промежуточных обработчиков
  • @lite-fsm/persist: Долговременное хранение состояния MachineManager и синхронизация между вкладками
  • Инструменты: visualizer, CLI create/add-machine/export и @lite-fsm/graph
  • Сравнение: Сравнение lite-fsm с другими решениями для управления состоянием
  • Примеры: Готовые решения типовых задач и паттерны использования
  • Playground: Демо-площадка на Next.js с подсветкой переходов FSM
Last updated on