Core API

@lite-fsm/core — runtime без привязки к UI-фреймворкам.

Импорт


import {
  MachineManager,
  createActorMeta,
  createConfig,
  createEffect,
  createMachine,
  createReducer,
  defineMachine,
  Machine,
  LiteFsmError,
} from "@lite-fsm/core";

Machine config

Reducer в примере написан в стиле Immer: при запуске такой машины через MachineManager подключите immerMiddleware. Без middleware reducer должен вернуть новый объект { state, context }.


import { createMachine } from "@lite-fsm/core";
 
const counter = createMachine({
  config: {
    IDLE: { INC: "IDLE", RESET: null },
    "*": { BOOT: "IDLE" },
  },
  initialState: "IDLE",
  initialContext: { count: 0 },
  reducer: (slice, action, { nextState }) => {
    slice.state = nextState;
    slice.context.count = action.type === "RESET" ? 0 : slice.context.count + 1;
  },
});

Поле	Назначение
`config`	Граф `{ [state]: { [eventType]: target } }`; `"*"` задаёт резервные переходы
`initialState`	Стартовое состояние
`initialContext`	Стартовые данные машины
`reducer?`	Собирает следующий `{ state, context }`
`effects?`	Синхронные или асинхронные effects для нового state или `"*"`
`hydrate?`, `dehydrate?`	Кастомная транспортная форма snapshot
`groupTag?`	Тег actor group для actor template
`persistence?`	Actor persistence: `"runtime"` или `"snapshot"`

Targets

Target	Поведение
`"NEXT_STATE"`	Переход в указанное состояние
`null`	Переход без смены state: reducer получает action, effect для конкретного state не запускается
`undefined` или отсутствующий ключ	Action игнорируется
`"__RESOLVED"`, `"__REJECTED"`, `"__CANCELLED"`	Terminal target actor template

Явный config[state][type] имеет приоритет над wildcard "*".

Factories

API	Назначение
`createMachine(cfg)`	Типизированная фабрика полного machine config
`createConfig(cfg)`	Типизированная фабрика графа переходов
`createReducer(fn)`	Типизированная фабрика reducer-а
`createEffect(opts)`	Обёртка effect с `every` или `latest` семантикой
`createActorMeta(meta)`	Замороженный `Readonly<ActorMeta>`

createEffect:


import { createEffect } from "@lite-fsm/core";
 
const load = createEffect({
  type: "latest",
  effect: async ({ transition }) => {
    transition({ type: "DONE" });
  },
});

MachineManager


import { MachineManager } from "@lite-fsm/core";
 
const manager = MachineManager(
  { counter },
  {
    schemaVersion: 1,
    onError: console.error,
  },
);
 
manager.transition({ type: "INC" });

Опции

Опция	Назначение
`middleware?`	Цепочка middleware для пользовательских actions
`snapshot?`	Начальный snapshot
`schemaVersion?`	Версия snapshot
`onError?`	Ошибки effects и `condition`
`onUnknownMachineKey?`	Неизвестный ключ машины при hydrate/snapshot
`onSchemaVersionMismatch?`	Несовпадение schema version
`originId?`	Префикс источника id для распределённого spawn
`generateActorId?`	Функция генерации actor id
`generateGroupId?`	Функция генерации group id

Методы

Метод	Назначение
`transition(action)`	Отправить событие через middleware/reducer/effects pipeline
`getState()`	Получить состояние manager после завершённого перехода
`getSnapshot()`	Получить текущий snapshot без пользовательских `dehydrate` hooks
`onTransition(cb)`	Подписаться на успешные transitions
`setDependencies(depsOrUpdater)`	Задать effect dependencies
`replaceReducer(enhancer)`	Обернуть root reducer
`dehydrate(opts?)`	Собрать снимок для передачи или сохранения
`hydrate(snapshot, opts?)`	Применить снимок
`getHydratedState(snapshot, opts?)`	Рассчитать состояние после `hydrate` без изменения менеджера

Стратегия восстановления

hydrate(snapshot, { strategy }) не выполняет глубокое объединение поля context и не заменяет всё состояние менеджера. В обоих режимах применяются только ключи из snapshot.machines. Для доменных машин strategy передаётся в обработчик hydrate как meta.strategy; для акторов, сохраняемых в снимок, merge сохраняет акторов вне входящего набора записей, а replace удаляет отсутствующих.

Actors

Actor template определяется через __INIT в config.


const request = createMachine({
  config: {
    __INIT: { START: "PENDING" },
    PENDING: { DONE: "__RESOLVED", FAIL: "__REJECTED" },
  },
  initialState: "__INIT",
  initialContext: { id: "" },
});

Routing выполняется через action.meta.actorId, groupId, groupTag или sender meta. Подробности: Акторы.

Типы

Чаще всего используются:

FSMEvent
MachineConfig
MachineReducer
MachineEffect
MachineStore
MachinesState
MachineEvents
MachineDependencies
MachineManagerSnapshot
HydrateStrategy
Middleware

Полный список: TYPES-CHEATSHEET.md.