@real-router/fsm 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +1,7 @@
 # @real-router/fsm
 
+[![Mutation Score](https://img.shields.io/endpoint?style=flat-square&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fgreydragon888%2Freal-router%2Fmaster%3Fmodule%3Dfsm)](https://dashboard.stryker-mutator.io/reports/github.com/greydragon888/real-router/master?module=fsm)
+
 > Synchronous finite state machine engine.
 
 **Internal package** — consumed by `@real-router/core`. Published to npm by historical accident — do not depend on it directly.
@@ -40,7 +42,6 @@ fsm.getContext();         // { count: 0 }
 | `getContext()` | Context object (same reference as config) |
 | `onTransition(listener)` | Subscribe to transitions, returns unsubscribe |
 | `on(from, event, action)` | Register action for specific `(from, event)` pair |
-| `forceState(state)` | Direct state update — no actions, no listeners; throws on an undeclared state |
 
 ### Type-Safe Payloads
 
@@ -62,7 +63,6 @@ fsm.send("FETCH");                   // TS error
 - **Zero-alloc hot path** — skips `TransitionInfo` allocation when no listeners
 - **Null-slot listener array** — reuses slots from unsubscribed listeners
 - **Reentrancy-safe** — state updated before listeners fire; callers responsible for preventing loops
-- **`forceState()`** — bypasses `send()` overhead (~30ns saved per call) for router's navigate hot path
 
 ## Dependencies
 

package/dist/cjs/index.d.ts

@@ -27,15 +27,6 @@ declare class FSM<TStates extends string, TEvents extends string, TContext, TPay
   constructor(config: FSMConfig<TStates, TEvents, TContext>);
   send<E extends TEvents>(event: E, ...args: E extends keyof TPayloadMap ? [TPayloadMap[E]] : [undefined?]): TStates;
   canSend(event: TEvents): boolean;
-  /**
-   * Directly sets FSM state without triggering actions or listeners.
-   * Use for hot-path optimizations where the caller handles side effects.
-   *
-   * Throws if `state` is not declared in `config.transitions`: an undeclared
-   * state would leave `#currentTransitions` undefined and brick the next
-   * `canSend`/`send`. The state is left unchanged when the guard rejects.
-   */
-  forceState(state: TStates): void;
   getState(): TStates;
   getContext(): TContext;
   on<E extends TEvents>(from: TStates, event: E, action: E extends keyof TPayloadMap ? (payload: TPayloadMap[E]) => void : () => void): () => void;

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/fsm.ts"],"mappings":";UAAiB,SAAA;EAKf,OAAA,EAAS,OAAA;EACT,OAAA,EAAS,QAAA;EACT,WAAA,EAAa,MAAA,CAAO,OAAA,EAAS,OAAA,CAAQ,MAAA,CAAO,OAAA,EAAS,OAAA;AAAA;AAAA,KAG3C,cAAA,qEAGU,OAAA,CAAQ,MAAA,CAAO,OAAA,eACjC,OAAA,yBAAgC,OAAA;EAE9B,IAAA,EAAM,OAAA;EACN,EAAA,EAAI,OAAA;EACJ,KAAA,EAAO,CAAA;EACP,OAAA,EAAS,CAAA,eAAgB,WAAA,GAAc,WAAA,CAAY,CAAA;AAAA;;;AAnBzD;;;;;;;;;;AAAA,cCoCa,GAAA,+EAIS,OAAA,CAAQ,MAAA,CAAO,OAAA,cAAqB,MAAA;EAAA;cAe5C,MAAA,EAAQ,SAAA,CAAU,OAAA,EAAS,OAAA,EAAS,QAAA;EAWhD,IAAA,WAAe,OAAA,EACb,KAAA,EAAO,CAAA,KACJ,IAAA,EAAM,CAAA,eAAgB,WAAA,IAAe,WAAA,CAAY,CAAA,oBACnD,OAAA;EA4CH,OAAA,CAAQ,KAAA,EAAO,OAAA;ED9Gf;;;;;;;;EC0HA,UAAA,CAAW,KAAA,EAAO,OAAA;EAOlB,QAAA,IAAY,OAAA;EAIZ,UAAA,IAAc,QAAA;EAId,EAAA,WAAa,OAAA,EACX,IAAA,EAAM,OAAA,EACN,KAAA,EAAO,CAAA,EACP,MAAA,EAAQ,CAAA,eAAgB,WAAA,IACnB,OAAA,EAAS,WAAA,CAAY,CAAA;EA2B5B,YAAA,CACE,QAAA,GAAW,IAAA,EAAM,cAAA,CAAe,OAAA,EAAS,OAAA,EAAS,WAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/fsm.ts"],"mappings":";UAAiB,SAAA;EAKf,OAAA,EAAS,OAAA;EACT,OAAA,EAAS,QAAA;EACT,WAAA,EAAa,MAAA,CAAO,OAAA,EAAS,OAAA,CAAQ,MAAA,CAAO,OAAA,EAAS,OAAA;AAAA;AAAA,KAG3C,cAAA,qEAGU,OAAA,CAAQ,MAAA,CAAO,OAAA,eACjC,OAAA,yBAAgC,OAAA;EAE9B,IAAA,EAAM,OAAA;EACN,EAAA,EAAI,OAAA;EACJ,KAAA,EAAO,CAAA;EACP,OAAA,EAAS,CAAA,eAAgB,WAAA,GAAc,WAAA,CAAY,CAAA;AAAA;;;AAnBzD;;;;;;;;;;AAAA,cCoCa,GAAA,+EAIS,OAAA,CAAQ,MAAA,CAAO,OAAA,cAAqB,MAAA;EAAA;cAe5C,MAAA,EAAQ,SAAA,CAAU,OAAA,EAAS,OAAA,EAAS,QAAA;EAWhD,IAAA,WAAe,OAAA,EACb,KAAA,EAAO,CAAA,KACJ,IAAA,EAAM,CAAA,eAAgB,WAAA,IAAe,WAAA,CAAY,CAAA,oBACnD,OAAA;EA6CH,OAAA,CAAQ,KAAA,EAAO,OAAA;EAIf,QAAA,IAAY,OAAA;EAIZ,UAAA,IAAc,QAAA;EAId,EAAA,WAAa,OAAA,EACX,IAAA,EAAM,OAAA,EACN,KAAA,EAAO,CAAA,EACP,MAAA,EAAQ,CAAA,eAAgB,WAAA,IACnB,OAAA,EAAS,WAAA,CAAY,CAAA;EA4B5B,YAAA,CACE,QAAA,GAAW,IAAA,EAAM,cAAA,CAAe,OAAA,EAAS,OAAA,EAAS,WAAA;AAAA"}

package/dist/cjs/index.js

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t,n){let r=e[t];if(r===void 0)throw Error(`[FSM.${n}] state "${t}" is not declared in config.transitions`);return r}var t=class{#e;#t;#n=0;#r=null;#i;#a;#o=[];constructor(t){this.#e=t.initial,this.#i=t.context,this.#a=t.transitions,this.#t=e(t.transitions,t.initial,`constructor`)}send(e,...t){let n=this.#t[e];if(n===void 0)return this.#e;let r=this.#e;this.#e=n,this.#t=this.#a[n];let i=t[0];if(this.#r!==null){let t=this.#r.get(r)?.get(e);t!==void 0&&t(i)}if(this.#n>0){let t={from:r,to:n,event:e,payload:i};for(let e of this.#o)e!==null&&e(t)}return this.#e}canSend(e){return this.#t[e]!==void 0}forceState(t){let n=e(this.#a,t,`forceState`);this.#e=t,this.#t=n}getState(){return this.#e}getContext(){return this.#i}on(t,n,r){e(this.#a,t,`on`),this.#r??=new Map;let i=this.#r.get(t);i||(i=new Map,this.#r.set(t,i));let a=r;return i.set(n,a),()=>{let e=this.#r?.get(t);e?.get(n)===a&&e.delete(n)}}onTransition(e){let t=this.#o.indexOf(null),n;t===-1?(n=this.#o.length,this.#o.push(e)):(this.#o[t]=e,n=t),this.#n++;let r=!0;return()=>{r&&(r=!1,this.#o[n]=null,this.#n--)}}};exports.FSM=t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t,n){let r=e[t];if(r===void 0)throw Error(`[FSM.${n}] state "${t}" is not declared in config.transitions`);return r}var t=class{#e;#t;#n=0;#r=null;#i;#a;#o=[];constructor(t){this.#e=t.initial,this.#i=t.context,this.#a=t.transitions,this.#t=e(t.transitions,t.initial,`constructor`)}send(e,...t){let n=this.#t[e];if(n===void 0)return this.#e;let r=this.#e;this.#e=n,this.#t=this.#a[n];let i=t[0];if(this.#r!==null){let t=this.#r.get(r)?.get(e);t!==void 0&&t(i)}if(this.#n>0){let t={from:r,to:n,event:e,payload:i};for(let e of this.#o)e!==null&&e(t)}return this.#e}canSend(e){return this.#t[e]!==void 0}getState(){return this.#e}getContext(){return this.#i}on(t,n,r){e(this.#a,t,`on`),this.#r??=new Map;let i=this.#r.get(t);i||(i=new Map,this.#r.set(t,i));let a=r;return i.set(n,a),()=>{let e=this.#r?.get(t);e?.get(n)===a&&e.delete(n)}}onTransition(e){let t=this.#o.indexOf(null),n;t===-1?(n=this.#o.length,this.#o.push(e)):(this.#o[t]=e,n=t),this.#n++;let r=!0;return()=>{r&&(r=!1,this.#o[n]=null,this.#n--)}}};exports.FSM=t;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#context","#transitions","#listeners","#state","#currentTransitions","#actions","#listenerCount"],"sources":["../../src/fsm.ts"],"sourcesContent":["import type { FSMConfig, TransitionInfo, TransitionListener } from \"./types\";\n\n/**\n * Shared guard for the engine-wide invariant \"the state is declared in\n * `config.transitions`\". Applied at every state-entry-point (constructor\n * `initial`, `forceState`, `on`'s `from`) so an undeclared state fails loud with\n * an explicit error instead of bricking the FSM or dead-registering an action\n * (#885). Returns the state's transition map for the caller to reuse.\n */\nfunction requireDeclared<TStates extends string, TEvents extends string>(\n  transitions: Record<TStates, Partial<Record<TEvents, TStates>>>,\n  state: TStates,\n  where: string,\n): Partial<Record<TEvents, TStates>> {\n  const stateTransitions = transitions[state];\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for JS / cast / string-typed callers passing a state outside TStates\n  if (stateTransitions === undefined) {\n    throw new Error(\n      `[FSM.${where}] state \"${state}\" is not declared in config.transitions`,\n    );\n  }\n\n  return stateTransitions;\n}\n\n/**\n * Synchronous finite state machine engine.\n *\n * Reentrancy: `send()` inside `onTransition` listener is allowed but unbounded —\n * callers are responsible for preventing infinite loops.\n *\n * Exceptions: if a listener throws, the exception propagates to the caller.\n * State is already updated before listeners fire, so `getState()` reflects the\n * new state even if the exception escapes `send()`.\n */\nexport class FSM<\n  TStates extends string,\n  TEvents extends string,\n  TContext,\n  TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>,\n> {\n  #state: TStates;\n  #currentTransitions: Partial<Record<TEvents, TStates>>;\n  #listenerCount = 0;\n  #actions: Map<TStates, Map<TEvents, (payload: unknown) => void>> | null =\n    null;\n  readonly #context: TContext;\n  readonly #transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;\n  readonly #listeners: (TransitionListener<\n    TStates,\n    TEvents,\n    TPayloadMap\n  > | null)[] = [];\n\n  constructor(config: FSMConfig<TStates, TEvents, TContext>) {\n    this.#state = config.initial;\n    this.#context = config.context;\n    this.#transitions = config.transitions;\n    this.#currentTransitions = requireDeclared(\n      config.transitions,\n      config.initial,\n      \"constructor\",\n    );\n  }\n\n  send<E extends TEvents>(\n    event: E,\n    ...args: E extends keyof TPayloadMap ? [TPayloadMap[E]] : [undefined?]\n  ): TStates {\n    const nextState = this.#currentTransitions[event];\n\n    if (nextState === undefined) {\n      return this.#state;\n    }\n\n    const from = this.#state;\n\n    this.#state = nextState;\n    this.#currentTransitions = this.#transitions[nextState];\n\n    const payload = args[0] as TPayloadMap[TEvents] | undefined;\n\n    if (this.#actions !== null) {\n      const action = this.#actions.get(from)?.get(event);\n\n      if (action !== undefined) {\n        action(payload);\n      }\n    }\n\n    if (this.#listenerCount > 0) {\n      // `info` is structurally a valid TransitionInfo, but the distributive\n      // union can't be matched to one variant while `event`/`payload` are\n      // generic here — erase through `unknown` (TS2352), same spirit as the\n      // `args[0]` cast above.\n      const info = {\n        from,\n        to: nextState,\n        event,\n        payload,\n      } as unknown as TransitionInfo<TStates, TEvents, TPayloadMap>;\n\n      for (const listener of this.#listeners) {\n        if (listener !== null) {\n          listener(info);\n        }\n      }\n    }\n\n    return this.#state;\n  }\n\n  canSend(event: TEvents): boolean {\n    return this.#currentTransitions[event] !== undefined;\n  }\n\n  /**\n   * Directly sets FSM state without triggering actions or listeners.\n   * Use for hot-path optimizations where the caller handles side effects.\n   *\n   * Throws if `state` is not declared in `config.transitions`: an undeclared\n   * state would leave `#currentTransitions` undefined and brick the next\n   * `canSend`/`send`. The state is left unchanged when the guard rejects.\n   */\n  forceState(state: TStates): void {\n    const transitions = requireDeclared(this.#transitions, state, \"forceState\");\n\n    this.#state = state;\n    this.#currentTransitions = transitions;\n  }\n\n  getState(): TStates {\n    return this.#state;\n  }\n\n  getContext(): TContext {\n    return this.#context;\n  }\n\n  on<E extends TEvents>(\n    from: TStates,\n    event: E,\n    action: E extends keyof TPayloadMap\n      ? (payload: TPayloadMap[E]) => void\n      : () => void,\n  ): () => void {\n    requireDeclared(this.#transitions, from, \"on\");\n\n    this.#actions ??= new Map();\n\n    let stateActions = this.#actions.get(from);\n\n    if (!stateActions) {\n      stateActions = new Map();\n      this.#actions.set(from, stateActions);\n    }\n\n    const capturedAction = action as (payload: unknown) => void;\n\n    stateActions.set(event, capturedAction);\n\n    return () => {\n      const stateMap = this.#actions?.get(from);\n\n      if (stateMap?.get(event) === capturedAction) {\n        stateMap.delete(event);\n      }\n    };\n  }\n\n  onTransition(\n    listener: (info: TransitionInfo<TStates, TEvents, TPayloadMap>) => void,\n  ): () => void {\n    const nullIndex = this.#listeners.indexOf(null);\n    let index: number;\n\n    if (nullIndex === -1) {\n      index = this.#listeners.length;\n      this.#listeners.push(listener);\n    } else {\n      this.#listeners[nullIndex] = listener;\n      index = nullIndex;\n    }\n\n    this.#listenerCount++;\n    let subscribed = true;\n\n    return () => {\n      if (!subscribed) {\n        return;\n      }\n\n      subscribed = false;\n      this.#listeners[index] = null;\n      this.#listenerCount--;\n    };\n  }\n}\n"],"mappings":"mEASA,SAAS,EACP,EACA,EACA,EACmC,CACnC,IAAM,EAAmB,EAAY,GAGrC,GAAI,IAAqB,IAAA,GACvB,MAAU,MACR,QAAQ,EAAM,WAAW,EAAM,wCACjC,EAGF,OAAO,CACT,CAYA,IAAa,EAAb,KAKE,CACA,GACA,GACA,GAAiB,EACjB,GACE,KACF,GACA,GACA,GAIc,CAAC,EAEf,YAAY,EAA+C,CACzD,KAAKG,GAAS,EAAO,QACrB,KAAKH,GAAW,EAAO,QACvB,KAAKC,GAAe,EAAO,YAC3B,KAAKG,GAAsB,EACzB,EAAO,YACP,EAAO,QACP,aACF,CACF,CAEA,KACE,EACA,GAAG,EACM,CACT,IAAM,EAAY,KAAKA,GAAoB,GAE3C,GAAI,IAAc,IAAA,GAChB,OAAO,KAAKD,GAGd,IAAM,EAAO,KAAKA,GAElB,KAAKA,GAAS,EACd,KAAKC,GAAsB,KAAKH,GAAa,GAE7C,IAAM,EAAU,EAAK,GAErB,GAAI,KAAKI,KAAa,KAAM,CAC1B,IAAM,EAAS,KAAKA,GAAS,IAAI,CAAI,CAAC,EAAE,IAAI,CAAK,EAE7C,IAAW,IAAA,IACb,EAAO,CAAO,CAElB,CAEA,GAAI,KAAKC,GAAiB,EAAG,CAK3B,IAAM,EAAO,CACX,OACA,GAAI,EACJ,QACA,SACF,EAEA,IAAK,IAAM,KAAY,KAAKJ,GACtB,IAAa,MACf,EAAS,CAAI,CAGnB,CAEA,OAAO,KAAKC,EACd,CAEA,QAAQ,EAAyB,CAC/B,OAAO,KAAKC,GAAoB,KAAW,IAAA,EAC7C,CAUA,WAAW,EAAsB,CAC/B,IAAM,EAAc,EAAgB,KAAKH,GAAc,EAAO,YAAY,EAE1E,KAAKE,GAAS,EACd,KAAKC,GAAsB,CAC7B,CAEA,UAAoB,CAClB,OAAO,KAAKD,EACd,CAEA,YAAuB,CACrB,OAAO,KAAKH,EACd,CAEA,GACE,EACA,EACA,EAGY,CACZ,EAAgB,KAAKC,GAAc,EAAM,IAAI,EAE7C,KAAKI,KAAa,IAAI,IAEtB,IAAI,EAAe,KAAKA,GAAS,IAAI,CAAI,EAEpC,IACH,EAAe,IAAI,IACnB,KAAKA,GAAS,IAAI,EAAM,CAAY,GAGtC,IAAM,EAAiB,EAIvB,OAFA,EAAa,IAAI,EAAO,CAAc,MAEzB,CACX,IAAM,EAAW,KAAKA,IAAU,IAAI,CAAI,EAEpC,GAAU,IAAI,CAAK,IAAM,GAC3B,EAAS,OAAO,CAAK,CAEzB,CACF,CAEA,aACE,EACY,CACZ,IAAM,EAAY,KAAKH,GAAW,QAAQ,IAAI,EAC1C,EAEA,IAAc,IAChB,EAAQ,KAAKA,GAAW,OACxB,KAAKA,GAAW,KAAK,CAAQ,IAE7B,KAAKA,GAAW,GAAa,EAC7B,EAAQ,GAGV,KAAKI,KACL,IAAI,EAAa,GAEjB,UAAa,CACN,IAIL,EAAa,GACb,KAAKJ,GAAW,GAAS,KACzB,KAAKI,KACP,CACF,CACF"}
+{"version":3,"file":"index.js","names":["#context","#transitions","#listeners","#state","#currentTransitions","#actions","#listenerCount"],"sources":["../../src/fsm.ts"],"sourcesContent":["import type { FSMConfig, TransitionInfo, TransitionListener } from \"./types\";\n\n/**\n * Shared guard for the engine-wide invariant \"the state is declared in\n * `config.transitions`\". Applied at every state-entry-point (constructor\n * `initial` and `on`'s `from`) so an undeclared state fails loud with\n * an explicit error instead of bricking the FSM or dead-registering an action\n * (#885). Returns the state's transition map for the caller to reuse.\n */\nfunction requireDeclared<TStates extends string, TEvents extends string>(\n  transitions: Record<TStates, Partial<Record<TEvents, TStates>>>,\n  state: TStates,\n  where: string,\n): Partial<Record<TEvents, TStates>> {\n  const stateTransitions = transitions[state];\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for JS / cast / string-typed callers passing a state outside TStates\n  if (stateTransitions === undefined) {\n    throw new Error(\n      `[FSM.${where}] state \"${state}\" is not declared in config.transitions`,\n    );\n  }\n\n  return stateTransitions;\n}\n\n/**\n * Synchronous finite state machine engine.\n *\n * Reentrancy: `send()` inside `onTransition` listener is allowed but unbounded —\n * callers are responsible for preventing infinite loops.\n *\n * Exceptions: if a listener throws, the exception propagates to the caller.\n * State is already updated before listeners fire, so `getState()` reflects the\n * new state even if the exception escapes `send()`.\n */\nexport class FSM<\n  TStates extends string,\n  TEvents extends string,\n  TContext,\n  TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>,\n> {\n  #state: TStates;\n  #currentTransitions: Partial<Record<TEvents, TStates>>;\n  #listenerCount = 0;\n  #actions: Map<TStates, Map<TEvents, (payload: unknown) => void>> | null =\n    null;\n  readonly #context: TContext;\n  readonly #transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;\n  readonly #listeners: (TransitionListener<\n    TStates,\n    TEvents,\n    TPayloadMap\n  > | null)[] = [];\n\n  constructor(config: FSMConfig<TStates, TEvents, TContext>) {\n    this.#state = config.initial;\n    this.#context = config.context;\n    this.#transitions = config.transitions;\n    this.#currentTransitions = requireDeclared(\n      config.transitions,\n      config.initial,\n      \"constructor\",\n    );\n  }\n\n  send<E extends TEvents>(\n    event: E,\n    ...args: E extends keyof TPayloadMap ? [TPayloadMap[E]] : [undefined?]\n  ): TStates {\n    const nextState = this.#currentTransitions[event];\n\n    if (nextState === undefined) {\n      return this.#state;\n    }\n\n    const from = this.#state;\n\n    this.#state = nextState;\n    this.#currentTransitions = this.#transitions[nextState];\n\n    const payload = args[0] as TPayloadMap[TEvents] | undefined;\n\n    if (this.#actions !== null) {\n      const action = this.#actions.get(from)?.get(event);\n\n      if (action !== undefined) {\n        action(payload);\n      }\n    }\n\n    // Stryker disable next-line ConditionalExpression: equivalent — count>0 is a perf gate to skip the dispatch loop; `true` always enters it, but with no live listener `#listeners` holds only null slots and the loop body guards `listener !== null`, so dispatch is a no-op either way. The EqualityOperator `<=0` sibling on this line stays killed (not silenced here).\n    if (this.#listenerCount > 0) {\n      // `info` is structurally a valid TransitionInfo, but the distributive\n      // union can't be matched to one variant while `event`/`payload` are\n      // generic here — erase through `unknown` (TS2352), same spirit as the\n      // `args[0]` cast above.\n      const info = {\n        from,\n        to: nextState,\n        event,\n        payload,\n      } as unknown as TransitionInfo<TStates, TEvents, TPayloadMap>;\n\n      for (const listener of this.#listeners) {\n        if (listener !== null) {\n          listener(info);\n        }\n      }\n    }\n\n    return this.#state;\n  }\n\n  canSend(event: TEvents): boolean {\n    return this.#currentTransitions[event] !== undefined;\n  }\n\n  getState(): TStates {\n    return this.#state;\n  }\n\n  getContext(): TContext {\n    return this.#context;\n  }\n\n  on<E extends TEvents>(\n    from: TStates,\n    event: E,\n    action: E extends keyof TPayloadMap\n      ? (payload: TPayloadMap[E]) => void\n      : () => void,\n  ): () => void {\n    requireDeclared(this.#transitions, from, \"on\");\n\n    this.#actions ??= new Map();\n\n    let stateActions = this.#actions.get(from);\n\n    if (!stateActions) {\n      stateActions = new Map();\n      this.#actions.set(from, stateActions);\n    }\n\n    const capturedAction = action as (payload: unknown) => void;\n\n    stateActions.set(event, capturedAction);\n\n    return () => {\n      // Stryker disable next-line OptionalChaining: equivalent — `#actions` is assigned (`??= new Map()` above) before this unsubscribe closure is created and returned, so it is never null when the closure runs; `?.` can't short-circuit and behaves identically to `.get`.\n      const stateMap = this.#actions?.get(from);\n\n      if (stateMap?.get(event) === capturedAction) {\n        stateMap.delete(event);\n      }\n    };\n  }\n\n  onTransition(\n    listener: (info: TransitionInfo<TStates, TEvents, TPayloadMap>) => void,\n  ): () => void {\n    const nullIndex = this.#listeners.indexOf(null);\n    let index: number;\n\n    if (nullIndex === -1) {\n      index = this.#listeners.length;\n      this.#listeners.push(listener);\n    } else {\n      this.#listeners[nullIndex] = listener;\n      index = nullIndex;\n    }\n\n    this.#listenerCount++;\n    let subscribed = true;\n\n    return () => {\n      if (!subscribed) {\n        return;\n      }\n\n      subscribed = false;\n      this.#listeners[index] = null;\n      // Stryker disable next-line UpdateOperator: equivalent — #listenerCount feeds only the `> 0` loop gate; `++` inflates it but the loop then iterates already-nulled slots (no-op), and no public reader exposes the count, so the miscount is unobservable.\n      this.#listenerCount--;\n    };\n  }\n}\n"],"mappings":"mEASA,SAAS,EACP,EACA,EACA,EACmC,CACnC,IAAM,EAAmB,EAAY,GAGrC,GAAI,IAAqB,IAAA,GACvB,MAAU,MACR,QAAQ,EAAM,WAAW,EAAM,wCACjC,EAGF,OAAO,CACT,CAYA,IAAa,EAAb,KAKE,CACA,GACA,GACA,GAAiB,EACjB,GACE,KACF,GACA,GACA,GAIc,CAAC,EAEf,YAAY,EAA+C,CACzD,KAAKG,GAAS,EAAO,QACrB,KAAKH,GAAW,EAAO,QACvB,KAAKC,GAAe,EAAO,YAC3B,KAAKG,GAAsB,EACzB,EAAO,YACP,EAAO,QACP,aACF,CACF,CAEA,KACE,EACA,GAAG,EACM,CACT,IAAM,EAAY,KAAKA,GAAoB,GAE3C,GAAI,IAAc,IAAA,GAChB,OAAO,KAAKD,GAGd,IAAM,EAAO,KAAKA,GAElB,KAAKA,GAAS,EACd,KAAKC,GAAsB,KAAKH,GAAa,GAE7C,IAAM,EAAU,EAAK,GAErB,GAAI,KAAKI,KAAa,KAAM,CAC1B,IAAM,EAAS,KAAKA,GAAS,IAAI,CAAI,CAAC,EAAE,IAAI,CAAK,EAE7C,IAAW,IAAA,IACb,EAAO,CAAO,CAElB,CAGA,GAAI,KAAKC,GAAiB,EAAG,CAK3B,IAAM,EAAO,CACX,OACA,GAAI,EACJ,QACA,SACF,EAEA,IAAK,IAAM,KAAY,KAAKJ,GACtB,IAAa,MACf,EAAS,CAAI,CAGnB,CAEA,OAAO,KAAKC,EACd,CAEA,QAAQ,EAAyB,CAC/B,OAAO,KAAKC,GAAoB,KAAW,IAAA,EAC7C,CAEA,UAAoB,CAClB,OAAO,KAAKD,EACd,CAEA,YAAuB,CACrB,OAAO,KAAKH,EACd,CAEA,GACE,EACA,EACA,EAGY,CACZ,EAAgB,KAAKC,GAAc,EAAM,IAAI,EAE7C,KAAKI,KAAa,IAAI,IAEtB,IAAI,EAAe,KAAKA,GAAS,IAAI,CAAI,EAEpC,IACH,EAAe,IAAI,IACnB,KAAKA,GAAS,IAAI,EAAM,CAAY,GAGtC,IAAM,EAAiB,EAIvB,OAFA,EAAa,IAAI,EAAO,CAAc,MAEzB,CAEX,IAAM,EAAW,KAAKA,IAAU,IAAI,CAAI,EAEpC,GAAU,IAAI,CAAK,IAAM,GAC3B,EAAS,OAAO,CAAK,CAEzB,CACF,CAEA,aACE,EACY,CACZ,IAAM,EAAY,KAAKH,GAAW,QAAQ,IAAI,EAC1C,EAEA,IAAc,IAChB,EAAQ,KAAKA,GAAW,OACxB,KAAKA,GAAW,KAAK,CAAQ,IAE7B,KAAKA,GAAW,GAAa,EAC7B,EAAQ,GAGV,KAAKI,KACL,IAAI,EAAa,GAEjB,UAAa,CACN,IAIL,EAAa,GACb,KAAKJ,GAAW,GAAS,KAEzB,KAAKI,KACP,CACF,CACF"}

package/dist/esm/index.d.mts

@@ -27,15 +27,6 @@ declare class FSM<TStates extends string, TEvents extends string, TContext, TPay
   constructor(config: FSMConfig<TStates, TEvents, TContext>);
   send<E extends TEvents>(event: E, ...args: E extends keyof TPayloadMap ? [TPayloadMap[E]] : [undefined?]): TStates;
   canSend(event: TEvents): boolean;
-  /**
-   * Directly sets FSM state without triggering actions or listeners.
-   * Use for hot-path optimizations where the caller handles side effects.
-   *
-   * Throws if `state` is not declared in `config.transitions`: an undeclared
-   * state would leave `#currentTransitions` undefined and brick the next
-   * `canSend`/`send`. The state is left unchanged when the guard rejects.
-   */
-  forceState(state: TStates): void;
   getState(): TStates;
   getContext(): TContext;
   on<E extends TEvents>(from: TStates, event: E, action: E extends keyof TPayloadMap ? (payload: TPayloadMap[E]) => void : () => void): () => void;

package/dist/esm/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/fsm.ts"],"mappings":";UAAiB,SAAA;EAKf,OAAA,EAAS,OAAA;EACT,OAAA,EAAS,QAAA;EACT,WAAA,EAAa,MAAA,CAAO,OAAA,EAAS,OAAA,CAAQ,MAAA,CAAO,OAAA,EAAS,OAAA;AAAA;AAAA,KAG3C,cAAA,qEAGU,OAAA,CAAQ,MAAA,CAAO,OAAA,eACjC,OAAA,yBAAgC,OAAA;EAE9B,IAAA,EAAM,OAAA;EACN,EAAA,EAAI,OAAA;EACJ,KAAA,EAAO,CAAA;EACP,OAAA,EAAS,CAAA,eAAgB,WAAA,GAAc,WAAA,CAAY,CAAA;AAAA;;;AAnBzD;;;;;;;;;;AAAA,cCoCa,GAAA,+EAIS,OAAA,CAAQ,MAAA,CAAO,OAAA,cAAqB,MAAA;EAAA;cAe5C,MAAA,EAAQ,SAAA,CAAU,OAAA,EAAS,OAAA,EAAS,QAAA;EAWhD,IAAA,WAAe,OAAA,EACb,KAAA,EAAO,CAAA,KACJ,IAAA,EAAM,CAAA,eAAgB,WAAA,IAAe,WAAA,CAAY,CAAA,oBACnD,OAAA;EA4CH,OAAA,CAAQ,KAAA,EAAO,OAAA;ED9Gf;;;;;;;;EC0HA,UAAA,CAAW,KAAA,EAAO,OAAA;EAOlB,QAAA,IAAY,OAAA;EAIZ,UAAA,IAAc,QAAA;EAId,EAAA,WAAa,OAAA,EACX,IAAA,EAAM,OAAA,EACN,KAAA,EAAO,CAAA,EACP,MAAA,EAAQ,CAAA,eAAgB,WAAA,IACnB,OAAA,EAAS,WAAA,CAAY,CAAA;EA2B5B,YAAA,CACE,QAAA,GAAW,IAAA,EAAM,cAAA,CAAe,OAAA,EAAS,OAAA,EAAS,WAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/fsm.ts"],"mappings":";UAAiB,SAAA;EAKf,OAAA,EAAS,OAAA;EACT,OAAA,EAAS,QAAA;EACT,WAAA,EAAa,MAAA,CAAO,OAAA,EAAS,OAAA,CAAQ,MAAA,CAAO,OAAA,EAAS,OAAA;AAAA;AAAA,KAG3C,cAAA,qEAGU,OAAA,CAAQ,MAAA,CAAO,OAAA,eACjC,OAAA,yBAAgC,OAAA;EAE9B,IAAA,EAAM,OAAA;EACN,EAAA,EAAI,OAAA;EACJ,KAAA,EAAO,CAAA;EACP,OAAA,EAAS,CAAA,eAAgB,WAAA,GAAc,WAAA,CAAY,CAAA;AAAA;;;AAnBzD;;;;;;;;;;AAAA,cCoCa,GAAA,+EAIS,OAAA,CAAQ,MAAA,CAAO,OAAA,cAAqB,MAAA;EAAA;cAe5C,MAAA,EAAQ,SAAA,CAAU,OAAA,EAAS,OAAA,EAAS,QAAA;EAWhD,IAAA,WAAe,OAAA,EACb,KAAA,EAAO,CAAA,KACJ,IAAA,EAAM,CAAA,eAAgB,WAAA,IAAe,WAAA,CAAY,CAAA,oBACnD,OAAA;EA6CH,OAAA,CAAQ,KAAA,EAAO,OAAA;EAIf,QAAA,IAAY,OAAA;EAIZ,UAAA,IAAc,QAAA;EAId,EAAA,WAAa,OAAA,EACX,IAAA,EAAM,OAAA,EACN,KAAA,EAAO,CAAA,EACP,MAAA,EAAQ,CAAA,eAAgB,WAAA,IACnB,OAAA,EAAS,WAAA,CAAY,CAAA;EA4B5B,YAAA,CACE,QAAA,GAAW,IAAA,EAAM,cAAA,CAAe,OAAA,EAAS,OAAA,EAAS,WAAA;AAAA"}

package/dist/esm/index.mjs

@@ -1,2 +1,2 @@
-function e(e,t,n){let r=e[t];if(r===void 0)throw Error(`[FSM.${n}] state "${t}" is not declared in config.transitions`);return r}var t=class{#e;#t;#n=0;#r=null;#i;#a;#o=[];constructor(t){this.#e=t.initial,this.#i=t.context,this.#a=t.transitions,this.#t=e(t.transitions,t.initial,`constructor`)}send(e,...t){let n=this.#t[e];if(n===void 0)return this.#e;let r=this.#e;this.#e=n,this.#t=this.#a[n];let i=t[0];if(this.#r!==null){let t=this.#r.get(r)?.get(e);t!==void 0&&t(i)}if(this.#n>0){let t={from:r,to:n,event:e,payload:i};for(let e of this.#o)e!==null&&e(t)}return this.#e}canSend(e){return this.#t[e]!==void 0}forceState(t){let n=e(this.#a,t,`forceState`);this.#e=t,this.#t=n}getState(){return this.#e}getContext(){return this.#i}on(t,n,r){e(this.#a,t,`on`),this.#r??=new Map;let i=this.#r.get(t);i||(i=new Map,this.#r.set(t,i));let a=r;return i.set(n,a),()=>{let e=this.#r?.get(t);e?.get(n)===a&&e.delete(n)}}onTransition(e){let t=this.#o.indexOf(null),n;t===-1?(n=this.#o.length,this.#o.push(e)):(this.#o[t]=e,n=t),this.#n++;let r=!0;return()=>{r&&(r=!1,this.#o[n]=null,this.#n--)}}};export{t as FSM};
+function e(e,t,n){let r=e[t];if(r===void 0)throw Error(`[FSM.${n}] state "${t}" is not declared in config.transitions`);return r}var t=class{#e;#t;#n=0;#r=null;#i;#a;#o=[];constructor(t){this.#e=t.initial,this.#i=t.context,this.#a=t.transitions,this.#t=e(t.transitions,t.initial,`constructor`)}send(e,...t){let n=this.#t[e];if(n===void 0)return this.#e;let r=this.#e;this.#e=n,this.#t=this.#a[n];let i=t[0];if(this.#r!==null){let t=this.#r.get(r)?.get(e);t!==void 0&&t(i)}if(this.#n>0){let t={from:r,to:n,event:e,payload:i};for(let e of this.#o)e!==null&&e(t)}return this.#e}canSend(e){return this.#t[e]!==void 0}getState(){return this.#e}getContext(){return this.#i}on(t,n,r){e(this.#a,t,`on`),this.#r??=new Map;let i=this.#r.get(t);i||(i=new Map,this.#r.set(t,i));let a=r;return i.set(n,a),()=>{let e=this.#r?.get(t);e?.get(n)===a&&e.delete(n)}}onTransition(e){let t=this.#o.indexOf(null),n;t===-1?(n=this.#o.length,this.#o.push(e)):(this.#o[t]=e,n=t),this.#n++;let r=!0;return()=>{r&&(r=!1,this.#o[n]=null,this.#n--)}}};export{t as FSM};
 //# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["#context","#transitions","#listeners","#state","#currentTransitions","#actions","#listenerCount"],"sources":["../../src/fsm.ts"],"sourcesContent":["import type { FSMConfig, TransitionInfo, TransitionListener } from \"./types\";\n\n/**\n * Shared guard for the engine-wide invariant \"the state is declared in\n * `config.transitions`\". Applied at every state-entry-point (constructor\n * `initial`, `forceState`, `on`'s `from`) so an undeclared state fails loud with\n * an explicit error instead of bricking the FSM or dead-registering an action\n * (#885). Returns the state's transition map for the caller to reuse.\n */\nfunction requireDeclared<TStates extends string, TEvents extends string>(\n  transitions: Record<TStates, Partial<Record<TEvents, TStates>>>,\n  state: TStates,\n  where: string,\n): Partial<Record<TEvents, TStates>> {\n  const stateTransitions = transitions[state];\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for JS / cast / string-typed callers passing a state outside TStates\n  if (stateTransitions === undefined) {\n    throw new Error(\n      `[FSM.${where}] state \"${state}\" is not declared in config.transitions`,\n    );\n  }\n\n  return stateTransitions;\n}\n\n/**\n * Synchronous finite state machine engine.\n *\n * Reentrancy: `send()` inside `onTransition` listener is allowed but unbounded —\n * callers are responsible for preventing infinite loops.\n *\n * Exceptions: if a listener throws, the exception propagates to the caller.\n * State is already updated before listeners fire, so `getState()` reflects the\n * new state even if the exception escapes `send()`.\n */\nexport class FSM<\n  TStates extends string,\n  TEvents extends string,\n  TContext,\n  TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>,\n> {\n  #state: TStates;\n  #currentTransitions: Partial<Record<TEvents, TStates>>;\n  #listenerCount = 0;\n  #actions: Map<TStates, Map<TEvents, (payload: unknown) => void>> | null =\n    null;\n  readonly #context: TContext;\n  readonly #transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;\n  readonly #listeners: (TransitionListener<\n    TStates,\n    TEvents,\n    TPayloadMap\n  > | null)[] = [];\n\n  constructor(config: FSMConfig<TStates, TEvents, TContext>) {\n    this.#state = config.initial;\n    this.#context = config.context;\n    this.#transitions = config.transitions;\n    this.#currentTransitions = requireDeclared(\n      config.transitions,\n      config.initial,\n      \"constructor\",\n    );\n  }\n\n  send<E extends TEvents>(\n    event: E,\n    ...args: E extends keyof TPayloadMap ? [TPayloadMap[E]] : [undefined?]\n  ): TStates {\n    const nextState = this.#currentTransitions[event];\n\n    if (nextState === undefined) {\n      return this.#state;\n    }\n\n    const from = this.#state;\n\n    this.#state = nextState;\n    this.#currentTransitions = this.#transitions[nextState];\n\n    const payload = args[0] as TPayloadMap[TEvents] | undefined;\n\n    if (this.#actions !== null) {\n      const action = this.#actions.get(from)?.get(event);\n\n      if (action !== undefined) {\n        action(payload);\n      }\n    }\n\n    if (this.#listenerCount > 0) {\n      // `info` is structurally a valid TransitionInfo, but the distributive\n      // union can't be matched to one variant while `event`/`payload` are\n      // generic here — erase through `unknown` (TS2352), same spirit as the\n      // `args[0]` cast above.\n      const info = {\n        from,\n        to: nextState,\n        event,\n        payload,\n      } as unknown as TransitionInfo<TStates, TEvents, TPayloadMap>;\n\n      for (const listener of this.#listeners) {\n        if (listener !== null) {\n          listener(info);\n        }\n      }\n    }\n\n    return this.#state;\n  }\n\n  canSend(event: TEvents): boolean {\n    return this.#currentTransitions[event] !== undefined;\n  }\n\n  /**\n   * Directly sets FSM state without triggering actions or listeners.\n   * Use for hot-path optimizations where the caller handles side effects.\n   *\n   * Throws if `state` is not declared in `config.transitions`: an undeclared\n   * state would leave `#currentTransitions` undefined and brick the next\n   * `canSend`/`send`. The state is left unchanged when the guard rejects.\n   */\n  forceState(state: TStates): void {\n    const transitions = requireDeclared(this.#transitions, state, \"forceState\");\n\n    this.#state = state;\n    this.#currentTransitions = transitions;\n  }\n\n  getState(): TStates {\n    return this.#state;\n  }\n\n  getContext(): TContext {\n    return this.#context;\n  }\n\n  on<E extends TEvents>(\n    from: TStates,\n    event: E,\n    action: E extends keyof TPayloadMap\n      ? (payload: TPayloadMap[E]) => void\n      : () => void,\n  ): () => void {\n    requireDeclared(this.#transitions, from, \"on\");\n\n    this.#actions ??= new Map();\n\n    let stateActions = this.#actions.get(from);\n\n    if (!stateActions) {\n      stateActions = new Map();\n      this.#actions.set(from, stateActions);\n    }\n\n    const capturedAction = action as (payload: unknown) => void;\n\n    stateActions.set(event, capturedAction);\n\n    return () => {\n      const stateMap = this.#actions?.get(from);\n\n      if (stateMap?.get(event) === capturedAction) {\n        stateMap.delete(event);\n      }\n    };\n  }\n\n  onTransition(\n    listener: (info: TransitionInfo<TStates, TEvents, TPayloadMap>) => void,\n  ): () => void {\n    const nullIndex = this.#listeners.indexOf(null);\n    let index: number;\n\n    if (nullIndex === -1) {\n      index = this.#listeners.length;\n      this.#listeners.push(listener);\n    } else {\n      this.#listeners[nullIndex] = listener;\n      index = nullIndex;\n    }\n\n    this.#listenerCount++;\n    let subscribed = true;\n\n    return () => {\n      if (!subscribed) {\n        return;\n      }\n\n      subscribed = false;\n      this.#listeners[index] = null;\n      this.#listenerCount--;\n    };\n  }\n}\n"],"mappings":"AASA,SAAS,EACP,EACA,EACA,EACmC,CACnC,IAAM,EAAmB,EAAY,GAGrC,GAAI,IAAqB,IAAA,GACvB,MAAU,MACR,QAAQ,EAAM,WAAW,EAAM,wCACjC,EAGF,OAAO,CACT,CAYA,IAAa,EAAb,KAKE,CACA,GACA,GACA,GAAiB,EACjB,GACE,KACF,GACA,GACA,GAIc,CAAC,EAEf,YAAY,EAA+C,CACzD,KAAKG,GAAS,EAAO,QACrB,KAAKH,GAAW,EAAO,QACvB,KAAKC,GAAe,EAAO,YAC3B,KAAKG,GAAsB,EACzB,EAAO,YACP,EAAO,QACP,aACF,CACF,CAEA,KACE,EACA,GAAG,EACM,CACT,IAAM,EAAY,KAAKA,GAAoB,GAE3C,GAAI,IAAc,IAAA,GAChB,OAAO,KAAKD,GAGd,IAAM,EAAO,KAAKA,GAElB,KAAKA,GAAS,EACd,KAAKC,GAAsB,KAAKH,GAAa,GAE7C,IAAM,EAAU,EAAK,GAErB,GAAI,KAAKI,KAAa,KAAM,CAC1B,IAAM,EAAS,KAAKA,GAAS,IAAI,CAAI,CAAC,EAAE,IAAI,CAAK,EAE7C,IAAW,IAAA,IACb,EAAO,CAAO,CAElB,CAEA,GAAI,KAAKC,GAAiB,EAAG,CAK3B,IAAM,EAAO,CACX,OACA,GAAI,EACJ,QACA,SACF,EAEA,IAAK,IAAM,KAAY,KAAKJ,GACtB,IAAa,MACf,EAAS,CAAI,CAGnB,CAEA,OAAO,KAAKC,EACd,CAEA,QAAQ,EAAyB,CAC/B,OAAO,KAAKC,GAAoB,KAAW,IAAA,EAC7C,CAUA,WAAW,EAAsB,CAC/B,IAAM,EAAc,EAAgB,KAAKH,GAAc,EAAO,YAAY,EAE1E,KAAKE,GAAS,EACd,KAAKC,GAAsB,CAC7B,CAEA,UAAoB,CAClB,OAAO,KAAKD,EACd,CAEA,YAAuB,CACrB,OAAO,KAAKH,EACd,CAEA,GACE,EACA,EACA,EAGY,CACZ,EAAgB,KAAKC,GAAc,EAAM,IAAI,EAE7C,KAAKI,KAAa,IAAI,IAEtB,IAAI,EAAe,KAAKA,GAAS,IAAI,CAAI,EAEpC,IACH,EAAe,IAAI,IACnB,KAAKA,GAAS,IAAI,EAAM,CAAY,GAGtC,IAAM,EAAiB,EAIvB,OAFA,EAAa,IAAI,EAAO,CAAc,MAEzB,CACX,IAAM,EAAW,KAAKA,IAAU,IAAI,CAAI,EAEpC,GAAU,IAAI,CAAK,IAAM,GAC3B,EAAS,OAAO,CAAK,CAEzB,CACF,CAEA,aACE,EACY,CACZ,IAAM,EAAY,KAAKH,GAAW,QAAQ,IAAI,EAC1C,EAEA,IAAc,IAChB,EAAQ,KAAKA,GAAW,OACxB,KAAKA,GAAW,KAAK,CAAQ,IAE7B,KAAKA,GAAW,GAAa,EAC7B,EAAQ,GAGV,KAAKI,KACL,IAAI,EAAa,GAEjB,UAAa,CACN,IAIL,EAAa,GACb,KAAKJ,GAAW,GAAS,KACzB,KAAKI,KACP,CACF,CACF"}
+{"version":3,"file":"index.mjs","names":["#context","#transitions","#listeners","#state","#currentTransitions","#actions","#listenerCount"],"sources":["../../src/fsm.ts"],"sourcesContent":["import type { FSMConfig, TransitionInfo, TransitionListener } from \"./types\";\n\n/**\n * Shared guard for the engine-wide invariant \"the state is declared in\n * `config.transitions`\". Applied at every state-entry-point (constructor\n * `initial` and `on`'s `from`) so an undeclared state fails loud with\n * an explicit error instead of bricking the FSM or dead-registering an action\n * (#885). Returns the state's transition map for the caller to reuse.\n */\nfunction requireDeclared<TStates extends string, TEvents extends string>(\n  transitions: Record<TStates, Partial<Record<TEvents, TStates>>>,\n  state: TStates,\n  where: string,\n): Partial<Record<TEvents, TStates>> {\n  const stateTransitions = transitions[state];\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for JS / cast / string-typed callers passing a state outside TStates\n  if (stateTransitions === undefined) {\n    throw new Error(\n      `[FSM.${where}] state \"${state}\" is not declared in config.transitions`,\n    );\n  }\n\n  return stateTransitions;\n}\n\n/**\n * Synchronous finite state machine engine.\n *\n * Reentrancy: `send()` inside `onTransition` listener is allowed but unbounded —\n * callers are responsible for preventing infinite loops.\n *\n * Exceptions: if a listener throws, the exception propagates to the caller.\n * State is already updated before listeners fire, so `getState()` reflects the\n * new state even if the exception escapes `send()`.\n */\nexport class FSM<\n  TStates extends string,\n  TEvents extends string,\n  TContext,\n  TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>,\n> {\n  #state: TStates;\n  #currentTransitions: Partial<Record<TEvents, TStates>>;\n  #listenerCount = 0;\n  #actions: Map<TStates, Map<TEvents, (payload: unknown) => void>> | null =\n    null;\n  readonly #context: TContext;\n  readonly #transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;\n  readonly #listeners: (TransitionListener<\n    TStates,\n    TEvents,\n    TPayloadMap\n  > | null)[] = [];\n\n  constructor(config: FSMConfig<TStates, TEvents, TContext>) {\n    this.#state = config.initial;\n    this.#context = config.context;\n    this.#transitions = config.transitions;\n    this.#currentTransitions = requireDeclared(\n      config.transitions,\n      config.initial,\n      \"constructor\",\n    );\n  }\n\n  send<E extends TEvents>(\n    event: E,\n    ...args: E extends keyof TPayloadMap ? [TPayloadMap[E]] : [undefined?]\n  ): TStates {\n    const nextState = this.#currentTransitions[event];\n\n    if (nextState === undefined) {\n      return this.#state;\n    }\n\n    const from = this.#state;\n\n    this.#state = nextState;\n    this.#currentTransitions = this.#transitions[nextState];\n\n    const payload = args[0] as TPayloadMap[TEvents] | undefined;\n\n    if (this.#actions !== null) {\n      const action = this.#actions.get(from)?.get(event);\n\n      if (action !== undefined) {\n        action(payload);\n      }\n    }\n\n    // Stryker disable next-line ConditionalExpression: equivalent — count>0 is a perf gate to skip the dispatch loop; `true` always enters it, but with no live listener `#listeners` holds only null slots and the loop body guards `listener !== null`, so dispatch is a no-op either way. The EqualityOperator `<=0` sibling on this line stays killed (not silenced here).\n    if (this.#listenerCount > 0) {\n      // `info` is structurally a valid TransitionInfo, but the distributive\n      // union can't be matched to one variant while `event`/`payload` are\n      // generic here — erase through `unknown` (TS2352), same spirit as the\n      // `args[0]` cast above.\n      const info = {\n        from,\n        to: nextState,\n        event,\n        payload,\n      } as unknown as TransitionInfo<TStates, TEvents, TPayloadMap>;\n\n      for (const listener of this.#listeners) {\n        if (listener !== null) {\n          listener(info);\n        }\n      }\n    }\n\n    return this.#state;\n  }\n\n  canSend(event: TEvents): boolean {\n    return this.#currentTransitions[event] !== undefined;\n  }\n\n  getState(): TStates {\n    return this.#state;\n  }\n\n  getContext(): TContext {\n    return this.#context;\n  }\n\n  on<E extends TEvents>(\n    from: TStates,\n    event: E,\n    action: E extends keyof TPayloadMap\n      ? (payload: TPayloadMap[E]) => void\n      : () => void,\n  ): () => void {\n    requireDeclared(this.#transitions, from, \"on\");\n\n    this.#actions ??= new Map();\n\n    let stateActions = this.#actions.get(from);\n\n    if (!stateActions) {\n      stateActions = new Map();\n      this.#actions.set(from, stateActions);\n    }\n\n    const capturedAction = action as (payload: unknown) => void;\n\n    stateActions.set(event, capturedAction);\n\n    return () => {\n      // Stryker disable next-line OptionalChaining: equivalent — `#actions` is assigned (`??= new Map()` above) before this unsubscribe closure is created and returned, so it is never null when the closure runs; `?.` can't short-circuit and behaves identically to `.get`.\n      const stateMap = this.#actions?.get(from);\n\n      if (stateMap?.get(event) === capturedAction) {\n        stateMap.delete(event);\n      }\n    };\n  }\n\n  onTransition(\n    listener: (info: TransitionInfo<TStates, TEvents, TPayloadMap>) => void,\n  ): () => void {\n    const nullIndex = this.#listeners.indexOf(null);\n    let index: number;\n\n    if (nullIndex === -1) {\n      index = this.#listeners.length;\n      this.#listeners.push(listener);\n    } else {\n      this.#listeners[nullIndex] = listener;\n      index = nullIndex;\n    }\n\n    this.#listenerCount++;\n    let subscribed = true;\n\n    return () => {\n      if (!subscribed) {\n        return;\n      }\n\n      subscribed = false;\n      this.#listeners[index] = null;\n      // Stryker disable next-line UpdateOperator: equivalent — #listenerCount feeds only the `> 0` loop gate; `++` inflates it but the loop then iterates already-nulled slots (no-op), and no public reader exposes the count, so the miscount is unobservable.\n      this.#listenerCount--;\n    };\n  }\n}\n"],"mappings":"AASA,SAAS,EACP,EACA,EACA,EACmC,CACnC,IAAM,EAAmB,EAAY,GAGrC,GAAI,IAAqB,IAAA,GACvB,MAAU,MACR,QAAQ,EAAM,WAAW,EAAM,wCACjC,EAGF,OAAO,CACT,CAYA,IAAa,EAAb,KAKE,CACA,GACA,GACA,GAAiB,EACjB,GACE,KACF,GACA,GACA,GAIc,CAAC,EAEf,YAAY,EAA+C,CACzD,KAAKG,GAAS,EAAO,QACrB,KAAKH,GAAW,EAAO,QACvB,KAAKC,GAAe,EAAO,YAC3B,KAAKG,GAAsB,EACzB,EAAO,YACP,EAAO,QACP,aACF,CACF,CAEA,KACE,EACA,GAAG,EACM,CACT,IAAM,EAAY,KAAKA,GAAoB,GAE3C,GAAI,IAAc,IAAA,GAChB,OAAO,KAAKD,GAGd,IAAM,EAAO,KAAKA,GAElB,KAAKA,GAAS,EACd,KAAKC,GAAsB,KAAKH,GAAa,GAE7C,IAAM,EAAU,EAAK,GAErB,GAAI,KAAKI,KAAa,KAAM,CAC1B,IAAM,EAAS,KAAKA,GAAS,IAAI,CAAI,CAAC,EAAE,IAAI,CAAK,EAE7C,IAAW,IAAA,IACb,EAAO,CAAO,CAElB,CAGA,GAAI,KAAKC,GAAiB,EAAG,CAK3B,IAAM,EAAO,CACX,OACA,GAAI,EACJ,QACA,SACF,EAEA,IAAK,IAAM,KAAY,KAAKJ,GACtB,IAAa,MACf,EAAS,CAAI,CAGnB,CAEA,OAAO,KAAKC,EACd,CAEA,QAAQ,EAAyB,CAC/B,OAAO,KAAKC,GAAoB,KAAW,IAAA,EAC7C,CAEA,UAAoB,CAClB,OAAO,KAAKD,EACd,CAEA,YAAuB,CACrB,OAAO,KAAKH,EACd,CAEA,GACE,EACA,EACA,EAGY,CACZ,EAAgB,KAAKC,GAAc,EAAM,IAAI,EAE7C,KAAKI,KAAa,IAAI,IAEtB,IAAI,EAAe,KAAKA,GAAS,IAAI,CAAI,EAEpC,IACH,EAAe,IAAI,IACnB,KAAKA,GAAS,IAAI,EAAM,CAAY,GAGtC,IAAM,EAAiB,EAIvB,OAFA,EAAa,IAAI,EAAO,CAAc,MAEzB,CAEX,IAAM,EAAW,KAAKA,IAAU,IAAI,CAAI,EAEpC,GAAU,IAAI,CAAK,IAAM,GAC3B,EAAS,OAAO,CAAK,CAEzB,CACF,CAEA,aACE,EACY,CACZ,IAAM,EAAY,KAAKH,GAAW,QAAQ,IAAI,EAC1C,EAEA,IAAc,IAChB,EAAQ,KAAKA,GAAW,OACxB,KAAKA,GAAW,KAAK,CAAQ,IAE7B,KAAKA,GAAW,GAAa,EAC7B,EAAQ,GAGV,KAAKI,KACL,IAAI,EAAa,GAEjB,UAAa,CACN,IAIL,EAAa,GACb,KAAKJ,GAAW,GAAS,KAEzB,KAAKI,KACP,CACF,CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/fsm",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "commonjs",
   "description": "Universal synchronous FSM engine for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -44,11 +44,10 @@
   "scripts": {
     "test": "vitest",
     "test:properties": "vitest --config vitest.config.properties.mts --run",
+    "test:mutation": "stryker run",
+    "test:mutation:report": "open reports/mutation-report.html",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
-    "lint:package": "publint",
-    "lint:types": "attw --pack .",
-    "bench": "NODE_OPTIONS='--expose-gc --max-old-space-size=4096' npx tsx tests/benchmarks/index.ts",
     "bundle": "tsdown --config-loader unrun"
   }
 }