@real-router/fsm 0.4.0 → 0.5.0

package/README.md

@@ -40,7 +40,7 @@ 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 |
+| `forceState(state)` | Direct state update — no actions, no listeners; throws on an undeclared state |
 
 ### Type-Safe Payloads
 

package/dist/cjs/index.d.ts

@@ -4,12 +4,12 @@ interface FSMConfig<TStates extends string, TEvents extends string, TContext> {
   context: TContext;
   transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;
 }
-interface TransitionInfo<TStates extends string, TEvents extends string, TPayloadMap extends Partial<Record<TEvents, unknown>>> {
+type TransitionInfo<TStates extends string, TEvents extends string, TPayloadMap extends Partial<Record<TEvents, unknown>>> = TEvents extends infer E extends TEvents ? {
   from: TStates;
   to: TStates;
-  event: TEvents;
-  payload: TPayloadMap[TEvents] | undefined;
-}
+  event: E;
+  payload: E extends keyof TPayloadMap ? TPayloadMap[E] : undefined;
+} : never;
 //#endregion
 //#region src/fsm.d.ts
 /**
@@ -25,11 +25,15 @@ interface TransitionInfo<TStates extends string, TEvents extends string, TPayloa
 declare class FSM<TStates extends string, TEvents extends string, TContext, TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>> {
   #private;
   constructor(config: FSMConfig<TStates, TEvents, TContext>);
-  send(event: TEvents, payload?: TPayloadMap[TEvents]): TStates;
+  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;

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,UAGtC,cAAA,qEAGK,OAAA,CAAQ,MAAA,CAAO,OAAA;EAEnC,IAAA,EAAM,OAAA;EACN,EAAA,EAAI,OAAA;EACJ,KAAA,EAAO,OAAA;EACP,OAAA,EAAS,WAAA,CAAY,OAAA;AAAA;;;AAlBvB;;;;;;;;;;AAAA,cCYa,GAAA,+EAIS,OAAA,CAAQ,MAAA,CAAO,OAAA,cAAqB,MAAA;EAAA;cAe5C,MAAA,EAAQ,SAAA,CAAU,OAAA,EAAS,OAAA,EAAS,QAAA;EAOhD,IAAA,CAAK,KAAA,EAAO,OAAA,EAAS,OAAA,GAAU,WAAA,CAAY,OAAA,IAAW,OAAA;EAsCtD,OAAA,CAAQ,KAAA,EAAO,OAAA;EDzEf;;;;ECiFA,UAAA,CAAW,KAAA,EAAO,OAAA;EAKlB,QAAA,CAAA,GAAY,OAAA;EAIZ,UAAA,CAAA,GAAc,QAAA;EAId,EAAA,WAAa,OAAA,CAAA,CACX,IAAA,EAAM,OAAA,EACN,KAAA,EAAO,CAAA,EACP,MAAA,EAAQ,CAAA,eAAgB,WAAA,IACnB,OAAA,EAAS,WAAA,CAAY,CAAA;EAyB5B,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;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"}

package/dist/cjs/index.js

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class{#e;#t;#n=0;#r=null;#i;#a;#o=[];constructor(e){this.#e=e.initial,this.#i=e.context,this.#a=e.transitions,this.#t=e.transitions[e.initial]}send(e,t){let n=this.#t[e];if(n===void 0)return this.#e;let r=this.#e;if(this.#e=n,this.#t=this.#a[n],this.#r!==null){let n=this.#r.get(r)?.get(e);n!==void 0&&n(t)}if(this.#n>0){let i={from:r,to:n,event:e,payload:t};for(let e of this.#o)e!==null&&e(i)}return this.#e}canSend(e){return this.#t[e]!==void 0}forceState(e){this.#e=e,this.#t=this.#a[e]}getState(){return this.#e}getContext(){return this.#i}on(e,t,n){this.#r??=new Map;let r=this.#r.get(e);r||(r=new Map,this.#r.set(e,r));let i=n;return r.set(t,i),()=>{let n=this.#r?.get(e);n?.get(t)===i&&n.delete(t)}}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=e;
+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;
 //# 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 * 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 = config.transitions[config.initial];\n  }\n\n  send(event: TEvents, payload?: TPayloadMap[TEvents]): 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    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      const info: TransitionInfo<TStates, TEvents, TPayloadMap> = {\n        from,\n        to: nextState,\n        event,\n        payload: payload,\n      };\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  forceState(state: TStates): void {\n    this.#state = state;\n    this.#currentTransitions = this.#transitions[state];\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    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":"mEAYA,IAAa,EAAb,KAKE,CACA,GACA,GACA,GAAiB,EACjB,GACE,KACF,GACA,GACA,GAIc,EAAE,CAEhB,YAAY,EAA+C,CACzD,MAAA,EAAc,EAAO,QACrB,MAAA,EAAgB,EAAO,QACvB,MAAA,EAAoB,EAAO,YAC3B,MAAA,EAA2B,EAAO,YAAY,EAAO,SAGvD,KAAK,EAAgB,EAAyC,CAC5D,IAAM,EAAY,MAAA,EAAyB,GAE3C,GAAI,IAAc,IAAA,GAChB,OAAO,MAAA,EAGT,IAAM,EAAO,MAAA,EAKb,GAHA,MAAA,EAAc,EACd,MAAA,EAA2B,MAAA,EAAkB,GAEzC,MAAA,IAAkB,KAAM,CAC1B,IAAM,EAAS,MAAA,EAAc,IAAI,EAAK,EAAE,IAAI,EAAM,CAE9C,IAAW,IAAA,IACb,EAAO,EAAQ,CAInB,GAAI,MAAA,EAAsB,EAAG,CAC3B,IAAM,EAAsD,CAC1D,OACA,GAAI,EACJ,QACS,UACV,CAED,IAAK,IAAM,KAAY,MAAA,EACjB,IAAa,MACf,EAAS,EAAK,CAKpB,OAAO,MAAA,EAGT,QAAQ,EAAyB,CAC/B,OAAO,MAAA,EAAyB,KAAW,IAAA,GAO7C,WAAW,EAAsB,CAC/B,MAAA,EAAc,EACd,MAAA,EAA2B,MAAA,EAAkB,GAG/C,UAAoB,CAClB,OAAO,MAAA,EAGT,YAAuB,CACrB,OAAO,MAAA,EAGT,GACE,EACA,EACA,EAGY,CACZ,MAAA,IAAkB,IAAI,IAEtB,IAAI,EAAe,MAAA,EAAc,IAAI,EAAK,CAErC,IACH,EAAe,IAAI,IACnB,MAAA,EAAc,IAAI,EAAM,EAAa,EAGvC,IAAM,EAAiB,EAIvB,OAFA,EAAa,IAAI,EAAO,EAAe,KAE1B,CACX,IAAM,EAAW,MAAA,GAAe,IAAI,EAAK,CAErC,GAAU,IAAI,EAAM,GAAK,GAC3B,EAAS,OAAO,EAAM,EAK5B,aACE,EACY,CACZ,IAAM,EAAY,MAAA,EAAgB,QAAQ,KAAK,CAC3C,EAEA,IAAc,IAChB,EAAQ,MAAA,EAAgB,OACxB,MAAA,EAAgB,KAAK,EAAS,GAE9B,MAAA,EAAgB,GAAa,EAC7B,EAAQ,GAGV,MAAA,IACA,IAAI,EAAa,GAEjB,UAAa,CACN,IAIL,EAAa,GACb,MAAA,EAAgB,GAAS,KACzB,MAAA"}
+{"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"}

package/dist/esm/index.d.mts

@@ -4,12 +4,12 @@ interface FSMConfig<TStates extends string, TEvents extends string, TContext> {
   context: TContext;
   transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;
 }
-interface TransitionInfo<TStates extends string, TEvents extends string, TPayloadMap extends Partial<Record<TEvents, unknown>>> {
+type TransitionInfo<TStates extends string, TEvents extends string, TPayloadMap extends Partial<Record<TEvents, unknown>>> = TEvents extends infer E extends TEvents ? {
   from: TStates;
   to: TStates;
-  event: TEvents;
-  payload: TPayloadMap[TEvents] | undefined;
-}
+  event: E;
+  payload: E extends keyof TPayloadMap ? TPayloadMap[E] : undefined;
+} : never;
 //#endregion
 //#region src/fsm.d.ts
 /**
@@ -25,11 +25,15 @@ interface TransitionInfo<TStates extends string, TEvents extends string, TPayloa
 declare class FSM<TStates extends string, TEvents extends string, TContext, TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>> {
   #private;
   constructor(config: FSMConfig<TStates, TEvents, TContext>);
-  send(event: TEvents, payload?: TPayloadMap[TEvents]): TStates;
+  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;

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,UAGtC,cAAA,qEAGK,OAAA,CAAQ,MAAA,CAAO,OAAA;EAEnC,IAAA,EAAM,OAAA;EACN,EAAA,EAAI,OAAA;EACJ,KAAA,EAAO,OAAA;EACP,OAAA,EAAS,WAAA,CAAY,OAAA;AAAA;;;AAlBvB;;;;;;;;;;AAAA,cCYa,GAAA,+EAIS,OAAA,CAAQ,MAAA,CAAO,OAAA,cAAqB,MAAA;EAAA;cAe5C,MAAA,EAAQ,SAAA,CAAU,OAAA,EAAS,OAAA,EAAS,QAAA;EAOhD,IAAA,CAAK,KAAA,EAAO,OAAA,EAAS,OAAA,GAAU,WAAA,CAAY,OAAA,IAAW,OAAA;EAsCtD,OAAA,CAAQ,KAAA,EAAO,OAAA;EDzEf;;;;ECiFA,UAAA,CAAW,KAAA,EAAO,OAAA;EAKlB,QAAA,CAAA,GAAY,OAAA;EAIZ,UAAA,CAAA,GAAc,QAAA;EAId,EAAA,WAAa,OAAA,CAAA,CACX,IAAA,EAAM,OAAA,EACN,KAAA,EAAO,CAAA,EACP,MAAA,EAAQ,CAAA,eAAgB,WAAA,IACnB,OAAA,EAAS,WAAA,CAAY,CAAA;EAyB5B,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;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"}

package/dist/esm/index.mjs

@@ -1,2 +1,2 @@
-var e=class{#e;#t;#n=0;#r=null;#i;#a;#o=[];constructor(e){this.#e=e.initial,this.#i=e.context,this.#a=e.transitions,this.#t=e.transitions[e.initial]}send(e,t){let n=this.#t[e];if(n===void 0)return this.#e;let r=this.#e;if(this.#e=n,this.#t=this.#a[n],this.#r!==null){let n=this.#r.get(r)?.get(e);n!==void 0&&n(t)}if(this.#n>0){let i={from:r,to:n,event:e,payload:t};for(let e of this.#o)e!==null&&e(i)}return this.#e}canSend(e){return this.#t[e]!==void 0}forceState(e){this.#e=e,this.#t=this.#a[e]}getState(){return this.#e}getContext(){return this.#i}on(e,t,n){this.#r??=new Map;let r=this.#r.get(e);r||(r=new Map,this.#r.set(e,r));let i=n;return r.set(t,i),()=>{let n=this.#r?.get(e);n?.get(t)===i&&n.delete(t)}}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{e 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}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};
 //# 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 * 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 = config.transitions[config.initial];\n  }\n\n  send(event: TEvents, payload?: TPayloadMap[TEvents]): 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    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      const info: TransitionInfo<TStates, TEvents, TPayloadMap> = {\n        from,\n        to: nextState,\n        event,\n        payload: payload,\n      };\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  forceState(state: TStates): void {\n    this.#state = state;\n    this.#currentTransitions = this.#transitions[state];\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    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":"AAYA,IAAa,EAAb,KAKE,CACA,GACA,GACA,GAAiB,EACjB,GACE,KACF,GACA,GACA,GAIc,EAAE,CAEhB,YAAY,EAA+C,CACzD,MAAA,EAAc,EAAO,QACrB,MAAA,EAAgB,EAAO,QACvB,MAAA,EAAoB,EAAO,YAC3B,MAAA,EAA2B,EAAO,YAAY,EAAO,SAGvD,KAAK,EAAgB,EAAyC,CAC5D,IAAM,EAAY,MAAA,EAAyB,GAE3C,GAAI,IAAc,IAAA,GAChB,OAAO,MAAA,EAGT,IAAM,EAAO,MAAA,EAKb,GAHA,MAAA,EAAc,EACd,MAAA,EAA2B,MAAA,EAAkB,GAEzC,MAAA,IAAkB,KAAM,CAC1B,IAAM,EAAS,MAAA,EAAc,IAAI,EAAK,EAAE,IAAI,EAAM,CAE9C,IAAW,IAAA,IACb,EAAO,EAAQ,CAInB,GAAI,MAAA,EAAsB,EAAG,CAC3B,IAAM,EAAsD,CAC1D,OACA,GAAI,EACJ,QACS,UACV,CAED,IAAK,IAAM,KAAY,MAAA,EACjB,IAAa,MACf,EAAS,EAAK,CAKpB,OAAO,MAAA,EAGT,QAAQ,EAAyB,CAC/B,OAAO,MAAA,EAAyB,KAAW,IAAA,GAO7C,WAAW,EAAsB,CAC/B,MAAA,EAAc,EACd,MAAA,EAA2B,MAAA,EAAkB,GAG/C,UAAoB,CAClB,OAAO,MAAA,EAGT,YAAuB,CACrB,OAAO,MAAA,EAGT,GACE,EACA,EACA,EAGY,CACZ,MAAA,IAAkB,IAAI,IAEtB,IAAI,EAAe,MAAA,EAAc,IAAI,EAAK,CAErC,IACH,EAAe,IAAI,IACnB,MAAA,EAAc,IAAI,EAAM,EAAa,EAGvC,IAAM,EAAiB,EAIvB,OAFA,EAAa,IAAI,EAAO,EAAe,KAE1B,CACX,IAAM,EAAW,MAAA,GAAe,IAAI,EAAK,CAErC,GAAU,IAAI,EAAM,GAAK,GAC3B,EAAS,OAAO,EAAM,EAK5B,aACE,EACY,CACZ,IAAM,EAAY,MAAA,EAAgB,QAAQ,KAAK,CAC3C,EAEA,IAAc,IAChB,EAAQ,MAAA,EAAgB,OACxB,MAAA,EAAgB,KAAK,EAAS,GAE9B,MAAA,EAAgB,GAAa,EAC7B,EAAQ,GAGV,MAAA,IACA,IAAI,EAAa,GAEjB,UAAa,CACN,IAIL,EAAa,GACb,MAAA,EAAgB,GAAS,KACzB,MAAA"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/fsm",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "commonjs",
   "description": "Universal synchronous FSM engine for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -45,11 +44,11 @@
   "scripts": {
     "test": "vitest",
     "test:properties": "vitest --config vitest.config.properties.mts --run",
-    "build": "tsdown --config-loader unrun",
     "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"
+    "bench": "NODE_OPTIONS='--expose-gc --max-old-space-size=4096' npx tsx tests/benchmarks/index.ts",
+    "bundle": "tsdown --config-loader unrun"
   }
 }

package/src/fsm.ts

@@ -1,154 +0,0 @@
-import type { FSMConfig, TransitionInfo, TransitionListener } from "./types";
-
-/**
- * Synchronous finite state machine engine.
- *
- * Reentrancy: `send()` inside `onTransition` listener is allowed but unbounded —
- * callers are responsible for preventing infinite loops.
- *
- * Exceptions: if a listener throws, the exception propagates to the caller.
- * State is already updated before listeners fire, so `getState()` reflects the
- * new state even if the exception escapes `send()`.
- */
-export class FSM<
-  TStates extends string,
-  TEvents extends string,
-  TContext,
-  TPayloadMap extends Partial<Record<TEvents, unknown>> = Record<never, never>,
-> {
-  #state: TStates;
-  #currentTransitions: Partial<Record<TEvents, TStates>>;
-  #listenerCount = 0;
-  #actions: Map<TStates, Map<TEvents, (payload: unknown) => void>> | null =
-    null;
-  readonly #context: TContext;
-  readonly #transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;
-  readonly #listeners: (TransitionListener<
-    TStates,
-    TEvents,
-    TPayloadMap
-  > | null)[] = [];
-
-  constructor(config: FSMConfig<TStates, TEvents, TContext>) {
-    this.#state = config.initial;
-    this.#context = config.context;
-    this.#transitions = config.transitions;
-    this.#currentTransitions = config.transitions[config.initial];
-  }
-
-  send(event: TEvents, payload?: TPayloadMap[TEvents]): TStates {
-    const nextState = this.#currentTransitions[event];
-
-    if (nextState === undefined) {
-      return this.#state;
-    }
-
-    const from = this.#state;
-
-    this.#state = nextState;
-    this.#currentTransitions = this.#transitions[nextState];
-
-    if (this.#actions !== null) {
-      const action = this.#actions.get(from)?.get(event);
-
-      if (action !== undefined) {
-        action(payload);
-      }
-    }
-
-    if (this.#listenerCount > 0) {
-      const info: TransitionInfo<TStates, TEvents, TPayloadMap> = {
-        from,
-        to: nextState,
-        event,
-        payload: payload,
-      };
-
-      for (const listener of this.#listeners) {
-        if (listener !== null) {
-          listener(info);
-        }
-      }
-    }
-
-    return this.#state;
-  }
-
-  canSend(event: TEvents): boolean {
-    return this.#currentTransitions[event] !== undefined;
-  }
-
-  /**
-   * Directly sets FSM state without triggering actions or listeners.
-   * Use for hot-path optimizations where the caller handles side effects.
-   */
-  forceState(state: TStates): void {
-    this.#state = state;
-    this.#currentTransitions = this.#transitions[state];
-  }
-
-  getState(): TStates {
-    return this.#state;
-  }
-
-  getContext(): TContext {
-    return this.#context;
-  }
-
-  on<E extends TEvents>(
-    from: TStates,
-    event: E,
-    action: E extends keyof TPayloadMap
-      ? (payload: TPayloadMap[E]) => void
-      : () => void,
-  ): () => void {
-    this.#actions ??= new Map();
-
-    let stateActions = this.#actions.get(from);
-
-    if (!stateActions) {
-      stateActions = new Map();
-      this.#actions.set(from, stateActions);
-    }
-
-    const capturedAction = action as (payload: unknown) => void;
-
-    stateActions.set(event, capturedAction);
-
-    return () => {
-      const stateMap = this.#actions?.get(from);
-
-      if (stateMap?.get(event) === capturedAction) {
-        stateMap.delete(event);
-      }
-    };
-  }
-
-  onTransition(
-    listener: (info: TransitionInfo<TStates, TEvents, TPayloadMap>) => void,
-  ): () => void {
-    const nullIndex = this.#listeners.indexOf(null);
-    let index: number;
-
-    if (nullIndex === -1) {
-      index = this.#listeners.length;
-      this.#listeners.push(listener);
-    } else {
-      this.#listeners[nullIndex] = listener;
-      index = nullIndex;
-    }
-
-    this.#listenerCount++;
-    let subscribed = true;
-
-    return () => {
-      if (!subscribed) {
-        return;
-      }
-
-      subscribed = false;
-      this.#listeners[index] = null;
-      this.#listenerCount--;
-    };
-  }
-}

package/src/index.ts

@@ -1,3 +0,0 @@
-export { FSM } from "./fsm";
-
-export type { FSMConfig, TransitionInfo } from "./types";

package/src/types.ts

@@ -1,26 +0,0 @@
-export interface FSMConfig<
-  TStates extends string,
-  TEvents extends string,
-  TContext,
-> {
-  initial: TStates;
-  context: TContext;
-  transitions: Record<TStates, Partial<Record<TEvents, TStates>>>;
-}
-
-export interface TransitionInfo<
-  TStates extends string,
-  TEvents extends string,
-  TPayloadMap extends Partial<Record<TEvents, unknown>>,
-> {
-  from: TStates;
-  to: TStates;
-  event: TEvents;
-  payload: TPayloadMap[TEvents] | undefined;
-}
-
-export type TransitionListener<
-  TStates extends string,
-  TEvents extends string,
-  TPayloadMap extends Partial<Record<TEvents, unknown>>,
-> = (info: TransitionInfo<TStates, TEvents, TPayloadMap>) => void;