@alwatr/fsm 9.32.0 → 9.33.1

package/src/type.ts

@@ -1,4 +1,4 @@
-import type {Awaitable, SingleOrArray} from '@alwatr/type-helper';
+import type {JsonValue, SingleOrArray} from '@alwatr/type-helper';
 import type {SignalConfig} from '@alwatr/signal';
 
 /**
@@ -24,66 +24,90 @@ export type MachineState<TState extends string, TContext extends Record<string,
 export interface MachineEvent<TEventType extends string = string> {
   /** The unique type of the event. */
   readonly type: TEventType;
-  /** An event can carry an optional payload. */
-  [key: string]: unknown;
+  /** An event can carry an optional, serializable payload. */
+  [key: string]: JsonValue;
 }
 
 /**
- * Defines an assigner (synchronous action) that updates the context during transitions.
- * It returns the complete new context object or void/undefined if no changes are made.
+ * Defines an assigner — a **pure, synchronous context reducer** applied during transitions.
  *
- * @template TContext The type of the machine's context.
- * @template TEvent The type of the event that triggered this assigner.
- * @returns The complete next context object or void.
+ * @param event The event that triggered the transition. Readonly to prevent mutations.
+ * @param context The current context before the transition. Mutable for convenience, but treat it as immutable — return a new context object instead of mutating it.
+ * @returns The complete next context object, or void.
  */
-export type Assigner<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (params: {
-  readonly event: Readonly<TEvent>;
-  readonly context: TContext;
-}) => TContext | void;
+export type Assigner<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (
+  event: Readonly<TEvent>,
+  context: TContext,
+) => TContext | void;
 
 /**
- * Defines an effect (fire-and-forget side-effect action) executed on state entry/exit.
- * It can interact with the outside world, but does not return new events to trigger transitions.
+ * Defines an effect — a **strictly synchronous**, fire-and-forget side-effect
+ * executed on state entry/exit.
  *
- * @template TContext The type of the machine's context.
- * @template TEvent The type of the event that triggered this effect.
- * @returns void or a Promise<void>.
+ * ## Why synchronous-only? (Architectural decision)
+ *
+ * The FSM core is a deterministic, Run-to-Completion (RTC) step function:
+ * `(state, event) -> (state', effects)`. Allowing async effects inside the core
+ * creates ordering ambiguity — the continuation of an async effect may run against
+ * a state/context that no longer exists. This mirrors the design of SCXML actions,
+ * XState actions, and Erlang's gen_statem.
+ *
+ * **Any asynchronous work belongs in an {@link Actor}**, which has a proper
+ * lifecycle (spawn on entry, cleanup on exit) and communicates results back to
+ * the machine via `dispatch`, keeping the core deterministic.
+ *
+ * @param event The event that triggered the effect. Readonly to prevent mutations.
+ * @param context The current context of the machine. Readonly to prevent mutations.
  */
-export type Effect<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (params: {
-  readonly event: Readonly<TEvent>;
-  readonly context: Readonly<TContext>;
-}) => Awaitable<void>;
+export type Effect<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (
+  event: Readonly<TEvent>,
+  context: Readonly<TContext>,
+) => void;
 
 /**
  * Defines a conditional guard function for a transition.
  * The transition is only taken if this function returns true.
  *
- * @template TContext The type of the machine's context.
- * @template TEvent The type of the event.
+ * Guards MUST be pure and synchronous. A guard that throws is treated as `false`
+ * (logged, transition branch skipped) so a single faulty predicate cannot brick
+ * the machine.
+ *
+ * @param event The event that triggered the transition. Readonly to prevent mutations.
+ * @param context The current context of the machine. Readonly to prevent mutations.
  * @returns `true` if the transition should be taken, `false` otherwise.
  */
-export type Guard<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (params: {
-  readonly event: Readonly<TEvent>;
-  readonly context: Readonly<TContext>;
-}) => boolean;
+export type Guard<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (
+  event: Readonly<TEvent>,
+  context: Readonly<TContext>,
+) => boolean;
 
 /**
- * Defines an actor (asynchronous lifecycle process) invoked on state entry.
- * It starts an operation and can send events back to the parent FSM via `dispatch`.
- * It can return a cleanup function to be called when exiting the state or destroying the machine.
+ * Defines an actor — an **asynchronous lifecycle process** spawned on state entry.
+ *
+ * This is the ONLY sanctioned home for async work in the machine (network requests,
+ * polling intervals, websocket listeners, timers). An actor:
+ *
+ * 1. Is spawned when the machine enters the state.
+ * 2. Receives `dispatch` to asynchronously send events back to the parent FSM.
+ * 3. May return a synchronous cleanup function, executed automatically (in LIFO
+ *    order) when the machine exits the state or is destroyed.
  *
  * @template TEvent The union type of all events in the machine.
  * @template TContext The type of the machine's context.
  */
-export type Actor<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (params: {
-  readonly event: Readonly<TEvent>;
-  readonly context: Readonly<TContext>;
-  readonly dispatch: (event: TEvent) => void;
-}) => (() => void) | void;
+export type Actor<TEvent extends MachineEvent, TContext extends Record<string, unknown>> = (
+  context: Readonly<TContext>,
+  dispatch: (event: TEvent) => void,
+) => VoidFunction | void;
 
 /**
  * Defines a transition for a given state and event. It specifies the target state,
- * actions, and an optional guard.
+ * assigners, and an optional guard.
+ *
+ * - With `target`: an **external** transition — exit effects run, actors are cleaned
+ *   up, then entry effects run and actors are re-spawned (even on self-transitions).
+ * - Without `target`: an **internal** transition — only assigners run; entry/exit
+ *   effects and actors are untouched.
  *
  * @template TState The type of the state.
  * @template TEvent The type of the event.
@@ -98,8 +122,8 @@ export interface Transition<
   readonly target?: TState;
   /** A guard function that must return true for the transition to occur. */
   readonly guard?: Guard<TEvent, TContext>;
-  /** An array of assigners to execute. These update context synchronously. */
-  readonly assigners?: SingleOrArray<Assigner<TEvent, TContext>>;
+  /** A single assigner or an ordered chain of assigners. Applied atomically. */
+  readonly assigner?: SingleOrArray<Assigner<TEvent, TContext>>;
 }
 
 /**
@@ -123,6 +147,14 @@ export interface FsmPersistenceConfig {
  * The declarative configuration object for creating a state machine.
  * This object defines the entire behavior of the machine.
  *
+ * ## Persistence requirement
+ *
+ * When `persistent` is enabled, EVERY state — including terminal states with no
+ * transitions — MUST be declared in `states` (e.g. `success: {}`). The engine uses
+ * the presence of a state's config entry to validate rehydrated state names from
+ * storage; an undeclared state is treated as removed/renamed and the machine is
+ * reset to `initial`.
+ *
  * @template TState The union type of all possible states.
  * @template TEvent The union type of all possible events.
  * @template TContext The type of the machine's context.
@@ -135,7 +167,7 @@ export interface StateMachineConfig<
   /** The initial finite state value. */
   readonly initial: TState;
 
-  /** The initial context (extended state) of the machine. */
+  /** The initial context (extended state) of the machine. Must be serializable. */
   readonly context: TContext;
 
   /** If provided, the FSM's state will be persisted in localStorage. */
@@ -148,12 +180,12 @@ export interface StateMachineConfig<
       readonly on?: {
         readonly [E in TEvent['type']]?: SingleOrArray<Transition<TState, Extract<TEvent, {type: E}>, TContext>>;
       };
-      /** An array of side-effect effects to execute upon entering this state. */
+      /** Synchronous side-effects executed upon entering this state. */
       readonly entry?: SingleOrArray<Effect<TEvent, TContext>>;
-      /** An array of side-effect effects to execute upon exiting this state. */
+      /** Synchronous side-effects executed upon exiting this state. */
       readonly exit?: SingleOrArray<Effect<TEvent, TContext>>;
-      /** An array of actors to spawn upon entering this state, cleaned up when leaving. */
-      readonly actors?: SingleOrArray<Actor<TEvent, TContext>>;
+      /** Async lifecycle actors spawned upon entering this state, cleaned up (LIFO) when leaving. */
+      readonly actor?: SingleOrArray<Actor<TEvent, TContext>>;
     };
   };
 }