Persist API

@lite-fsm/persist сохраняет снимок MachineManager в произвольное хранилище и восстанавливает его.

Импорт


import { createJsonStorage, persistManager } from "@lite-fsm/persist";
import type {
  PersistController,
  PersistManagerOptions,
  PersistStatus,
  PersistStorage,
  PersistedRecord,
} from "@lite-fsm/persist";
 
import { useIsPersistRestoring, usePersistStatuses } from "@lite-fsm/persist/react";

`persistManager(manager, options)`


const persist = persistManager(manager, {
  storage: createJsonStorage({
    key: "app:state:v1",
    storage: () => window.localStorage,
  }),
  storageVersion: 1,
  machines: ["counter"],
  throttleMs: 500,
});

Опции

Опция	Назначение
`storage`	Адаптер `{ get, set, remove, subscribe? }`
`machines?`	Какие машины попадают в снимок
`strategy?`	Режим `hydrate`; по умолчанию `"merge"`
`storageVersion?`	Версия записи
`maxAge?`	TTL записи в миллисекундах
`throttleMs?`	Минимальный интервал между сохранениями
`shouldSave?`	Фильтр transitions перед сохранением
`migrate?`	Миграция старой записи
`onRestoreSettled?`	Колбэк результата восстановления
`onError?`	Колбэк ошибок `restore`, `save`, `clear`

strategy не объединяет поля context автоматически и не заменяет всё состояние менеджера. Она передаётся в manager.hydrate(); для акторов, сохраняемых в снимок, "merge" сохраняет акторов вне входящего набора записей, а "replace" удаляет отсутствующих.

Контроллер

Метод	Назначение
`start()`	Подписаться на manager/storage и восстановить запись
`restore()`	Прочитать хранилище и применить снимок
`save()`	Сразу записать текущий снимок
`flush()`	Дописать отложенное сохранение
`clear()`	Удалить запись и сбросить статус
`getStatus()`	Вернуть текущий `PersistStatus`
`subscribeStatus(cb)`	Подписка на изменение статуса

Хранилище


type PersistStorage<S> = {
  get(): MaybePromise<PersistedRecord<S> | undefined>;
  set(record: PersistedRecord<S>): MaybePromise<void>;
  remove(): MaybePromise<void>;
  subscribe?(cb: () => void): () => void;
};

createJsonStorage подходит для синхронных storage API с getItem, setItem, removeItem. storage принимает только функцию: она не вызывается при создании адаптера, вызывается заново на каждом get, set, remove и не кешируется. subscribe добавляйте вручную через расширение PersistStorage.

React-хуки


const [status] = usePersistStatuses();
const restoring = useIsPersistRestoring();

Хуки работают через ближайший FSMContextProvider и вне него бросают ошибку провайдера. usePersistStatuses() возвращает массив той же длины и в том же порядке, что persist; элемент без getStatus() и subscribeStatus() возвращается как null. Если persist не передан или равен [], возвращается [].

useIsPersistRestoring возвращает true, если хотя бы один статус, отличный от null, имеет phase === "restoring"; для блокировки интерфейса до первого восстановления проверяйте также "idle" у нужного статуса.

Подробное руководство: @lite-fsm/persist.