@real-router/fsm 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/fsm",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "commonjs",
   "description": "Universal synchronous FSM engine for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "bench": "NODE_OPTIONS='--expose-gc --max-old-space-size=4096' npx tsx tests/benchmarks/index.ts",
     "build:dist-only": "tsdown --config-loader unrun"

package/src/fsm.ts

@@ -0,0 +1,148 @@
+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);
+    }
+
+    stateActions.set(event, action as (payload: unknown) => void);
+
+    return () => {
+      this.#actions?.get(from)?.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

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

package/src/types.ts

@@ -0,0 +1,26 @@
+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;