@duyquangnvx/state-machine 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# state-machine
+
+A generic, type-safe finite state machine library for TypeScript with synchronous lifecycle hooks, transition guards, hierarchical states, event history, and a tick-based update loop.
+
+## Features
+
+- **Fully generic** — `StateMachine<TContext, TStateId>` works with any context and state ID types
+- **Synchronous lifecycle** — `onEnter` / `onExit` / `onUpdate` are all sync for deterministic state at every moment
+- **Transition guards** — `canTransitionTo(target, ctx)` lets each state control allowed transitions
+- **Tick-based updates** — `onUpdate(ctx, dt)` runs every frame/tick; return a state ID to auto-transition
+- **Hierarchical states** — `HierarchicalState` embeds a nested state machine inside a parent state
+- **Event system** — Subscribe to state changes with `on(listener)`, unsubscribe with the returned function
+- **Bounded history** — Configurable history buffer for debugging and replay
+
+## Quick start
+
+```bash
+npm install
+npm run build
+```
+
+### Define states
+
+```ts
+import { BaseState } from "state-machine";
+
+type MyStateId = "idle" | "loading" | "ready";
+
+interface MyContext {
+  data: string | null;
+}
+
+class IdleState extends BaseState<MyContext, MyStateId> {
+  readonly id = "idle" as const;
+
+  override onEnter(ctx: MyContext, prevState: MyStateId | null): void {
+    console.log("Entered idle");
+  }
+
+  override onUpdate(ctx: MyContext, dt: number): MyStateId | undefined {
+    return "loading"; // auto-transition on next tick
+  }
+}
+
+class LoadingState extends BaseState<MyContext, MyStateId> {
+  readonly id = "loading" as const;
+
+  override onUpdate(): MyStateId | undefined {
+    return "ready";
+  }
+}
+
+class ReadyState extends BaseState<MyContext, MyStateId> {
+  readonly id = "ready" as const;
+}
+```
+
+### Create and run the machine
+
+```ts
+import { StateMachine } from "state-machine";
+
+const sm = new StateMachine<MyContext, MyStateId>({
+  states: [new IdleState(), new LoadingState(), new ReadyState()],
+  initialState: "idle",
+  context: { data: null },
+  historySize: 50, // optional, defaults to 100
+});
+
+sm.start();            // enters "idle", calls onEnter
+sm.update(0.016);      // calls onUpdate, may auto-transition
+sm.transitionTo("ready"); // explicit transition
+sm.stop();             // exits current state, calls onExit
+```
+
+### Transition guards
+
+Override `canTransitionTo` to block transitions conditionally:
+
+```ts
+class IdleState extends BaseState<MyContext, MyStateId> {
+  readonly id = "idle" as const;
+
+  override canTransitionTo(target: MyStateId, ctx: MyContext): boolean {
+    return ctx.data !== null; // only allow transitions when data is loaded
+  }
+}
+```
+
+Blocked transitions throw `TransitionDeniedError`.
+
+### Events and history
+
+```ts
+const unsub = sm.on((event) => {
+  console.log(`${event.from} -> ${event.to} at ${event.timestamp}`);
+});
+
+sm.getHistory(); // ReadonlyArray<StateChangeEvent<MyStateId>>
+unsub();         // stop listening
+```
+
+### Async work as a state
+
+The state machine is fully synchronous — `onEnter`, `onExit`, and `onUpdate` all return `void`. This ensures the machine is always in exactly one definite state at any moment, which is critical for game loops and real-time systems.
+
+To handle async operations (API calls, loading, etc.), **model the async work as its own state** that polls for completion:
+
+```ts
+type MyStateId = "IDLE" | "LOADING" | "READY";
+
+interface MyContext {
+  loading: boolean;
+  data: string | null;
+  fetchData: () => Promise<string>;
+}
+
+class LoadingState extends BaseState<MyContext, MyStateId> {
+  readonly id = "LOADING" as const;
+
+  override onEnter(ctx: MyContext): void {
+    ctx.loading = true;
+    ctx.fetchData().then((data) => {
+      ctx.data = data;
+      ctx.loading = false;
+    });
+  }
+
+  override onUpdate(ctx: MyContext): MyStateId | undefined {
+    if (!ctx.loading) return "READY";
+    return undefined;
+  }
+}
+```
+
+This pattern keeps the state machine synchronous while still supporting async operations. The state machine ticks on each frame/update, and the loading state simply polls until the async work completes.
+
+## API
+
+### `StateMachine<TContext, TStateId>`
+
+| Method / Property | Description |
+|---|---|
+| `start(): void` | Enter the initial state. Idempotent. |
+| `stop(): void` | Exit the current state and shut down. |
+| `transitionTo(stateId): void` | Transition to a specific state (checks guard). |
+| `update(dt): void` | Tick the current state; auto-transitions if `onUpdate` returns a state ID. |
+| `on(listener)` | Subscribe to state changes. Returns unsubscribe function. |
+| `getHistory()` | Get the bounded transition history. |
+| `currentStateId` | The active state's ID. Throws if not started. |
+| `isStarted` | Whether the machine is running. |
+| `context` | The shared mutable context object. |
+
+### `BaseState<TContext, TStateId>` (lifecycle hooks)
+
+| Hook | Signature | Notes |
+|---|---|---|
+| `canTransitionTo` | `(target, ctx) => boolean` | Sync guard. Default: `true`. |
+| `onEnter` | `(ctx, prevState) => void` | Called when entering. `prevState` is `null` on `start()`. |
+| `onUpdate` | `(ctx, dt) => TStateId \| undefined` | Return a state ID to auto-transition. |
+| `onExit` | `(ctx, nextState) => void` | Called when leaving. `nextState` is `null` on `stop()`. |
+
+### `HierarchicalState<TContext, TParentId, TChildId>`
+
+A composite state that runs a nested `StateMachine`. Override `createChildConfig(ctx)` to define the child machine. The child starts/stops automatically with the parent state.
+
+### Errors
+
+| Error | Thrown when |
+|---|---|
+| `StateNotFoundError` | Transitioning to an unknown state ID. |
+| `MachineNotStartedError` | Calling `transitionTo`, `update`, or `currentStateId` before `start()`. |
+| `TransitionDeniedError` | `canTransitionTo` returns `false`. |
+
+## Demos
+
+### Tower Defense
+
+Three interlocking state machines (tower, enemy, wave) simulating a tower defense game loop.
+
+```
+Tower:  BUILDING -> IDLE -> TARGETING -> ATTACKING -> IDLE
+Enemy:  SPAWNING -> MOVING -> ATTACKING -> DYING -> DEAD
+Wave:   PREPARING -> WAVE_ACTIVE -> WAVE_COMPLETE -> ... -> GAME_OVER
+```
+
+```bash
+npm run build && npm run demo
+```
+
+### Slot Machine
+
+Demonstrates the "async work as a state" pattern — API calls (bet deduction, payout crediting) are modeled as dedicated states that poll for completion.
+
+```
+IDLE -> DEDUCTING_BET -> SPINNING -> STOPPING -> EVALUATING -> CREDITING_WIN -> IDLE
+                                                     |
+                                                     +--> IDLE (no win)
+```
+
+```bash
+npm run build && npm run demo:slot
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+67 tests covering the core library (construction, start/stop, transitions, guards, updates, events, history, hierarchical states) and both demos.
+
+## Project structure
+
+```
+src/
+  lib/                    # Core library
+    State.ts              # BaseState abstract class
+    StateMachine.ts       # StateMachine engine
+    HierarchicalState.ts  # Composite state with nested machine
+    StateEvent.ts         # Event emitter with bounded history
+    interfaces.ts         # IState, IStateMachine, config types
+    errors.ts             # StateNotFoundError, MachineNotStartedError, TransitionDeniedError
+    index.ts              # Public exports
+  demo/
+    tower/                # Tower defense FSM (tower states)
+    enemy/                # Tower defense FSM (enemy states)
+    wave/                 # Tower defense FSM (wave management)
+    slot/                 # Slot machine FSM
+    main.ts               # Tower defense entry point
+    slot-main.ts          # Slot machine entry point
+    GameLoop.ts           # Tick-based game loop utility
+tests/
+  lib/                    # Core library tests
+  demo/                   # Demo-specific tests
+```
+
+## License
+
+ISC

package/dist/index.cjs

@@ -0,0 +1,202 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BaseState: () => BaseState,
+  HierarchicalState: () => HierarchicalState,
+  MachineNotStartedError: () => MachineNotStartedError,
+  StateEventEmitter: () => StateEventEmitter,
+  StateMachine: () => StateMachine,
+  StateNotFoundError: () => StateNotFoundError,
+  TransitionDeniedError: () => TransitionDeniedError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/lib/State.ts
+var BaseState = class {
+  canTransitionTo(_targetState, _ctx) {
+    return true;
+  }
+  onEnter(_ctx, _prevState) {
+  }
+  onUpdate(_ctx, _dt) {
+    return void 0;
+  }
+  onExit(_ctx, _nextState) {
+  }
+};
+
+// src/lib/StateEvent.ts
+var StateEventEmitter = class {
+  listeners = [];
+  history = [];
+  maxHistory;
+  constructor(maxHistory = 100) {
+    this.maxHistory = maxHistory;
+  }
+  on(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const idx = this.listeners.indexOf(listener);
+      if (idx !== -1) this.listeners.splice(idx, 1);
+    };
+  }
+  emit(change) {
+    this.history.push(change);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+    for (const listener of this.listeners) {
+      listener(change);
+    }
+  }
+  getHistory() {
+    return [...this.history];
+  }
+  clear() {
+    this.history.length = 0;
+    this.listeners.length = 0;
+  }
+};
+
+// src/lib/errors.ts
+var StateNotFoundError = class extends Error {
+  constructor(stateId) {
+    super(`State not found: "${stateId}"`);
+    this.name = "StateNotFoundError";
+  }
+};
+var MachineNotStartedError = class extends Error {
+  constructor() {
+    super("State machine has not been started. Call start() first.");
+    this.name = "MachineNotStartedError";
+  }
+};
+var TransitionDeniedError = class extends Error {
+  constructor(from, to) {
+    super(`Transition denied: "${from}" -> "${to}"`);
+    this.name = "TransitionDeniedError";
+  }
+};
+
+// src/lib/StateMachine.ts
+var StateMachine = class {
+  stateMap = /* @__PURE__ */ new Map();
+  emitter;
+  currentState = null;
+  initialStateId;
+  _isStarted = false;
+  context;
+  constructor(config) {
+    this.context = config.context;
+    this.initialStateId = config.initialState;
+    this.emitter = new StateEventEmitter(config.historySize ?? 100);
+    for (const state of config.states) {
+      if (this.stateMap.has(state.id)) {
+        throw new Error(`Duplicate state id: "${state.id}"`);
+      }
+      this.stateMap.set(state.id, state);
+    }
+    if (!this.stateMap.has(config.initialState)) {
+      throw new StateNotFoundError(config.initialState);
+    }
+  }
+  get currentStateId() {
+    if (!this.currentState) throw new MachineNotStartedError();
+    return this.currentState.id;
+  }
+  get isStarted() {
+    return this._isStarted;
+  }
+  start() {
+    if (this._isStarted) return;
+    const state = this.stateMap.get(this.initialStateId);
+    if (!state) throw new StateNotFoundError(this.initialStateId);
+    this.currentState = state;
+    this._isStarted = true;
+    this.currentState.onEnter(this.context, null);
+  }
+  stop() {
+    if (!this._isStarted || !this.currentState) return;
+    this.currentState.onExit(this.context, null);
+    this.currentState = null;
+    this._isStarted = false;
+  }
+  transitionTo(stateId) {
+    if (!this.currentState) throw new MachineNotStartedError();
+    const to = this.stateMap.get(stateId);
+    if (!to) throw new StateNotFoundError(stateId);
+    const from = this.currentState;
+    if (!from.canTransitionTo(stateId, this.context)) {
+      throw new TransitionDeniedError(from.id, stateId);
+    }
+    const change = {
+      from: from.id,
+      to: to.id,
+      timestamp: Date.now()
+    };
+    from.onExit(this.context, to.id);
+    this.currentState = to;
+    this.emitter.emit(change);
+    to.onEnter(this.context, from.id);
+  }
+  update(dt) {
+    if (!this.currentState) throw new MachineNotStartedError();
+    const next = this.currentState.onUpdate(this.context, dt);
+    if (next) {
+      this.transitionTo(next);
+    }
+  }
+  on(listener) {
+    return this.emitter.on(listener);
+  }
+  getHistory() {
+    return this.emitter.getHistory();
+  }
+};
+
+// src/lib/HierarchicalState.ts
+var HierarchicalState = class extends BaseState {
+  childMachine = null;
+  onEnter(ctx, _prevState) {
+    const config = this.createChildConfig(ctx);
+    this.childMachine = new StateMachine(config);
+    this.childMachine.start();
+  }
+  onUpdate(_ctx, _dt) {
+    return void 0;
+  }
+  onExit(_ctx, _nextState) {
+    this.childMachine?.stop();
+    this.childMachine = null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseState,
+  HierarchicalState,
+  MachineNotStartedError,
+  StateEventEmitter,
+  StateMachine,
+  StateNotFoundError,
+  TransitionDeniedError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/index.ts","../src/lib/State.ts","../src/lib/StateEvent.ts","../src/lib/errors.ts","../src/lib/StateMachine.ts","../src/lib/HierarchicalState.ts"],"sourcesContent":["export { BaseState } from \"./State.js\";\nexport { StateMachine } from \"./StateMachine.js\";\nexport { StateEventEmitter } from \"./StateEvent.js\";\nexport { HierarchicalState } from \"./HierarchicalState.js\";\nexport {\n  StateNotFoundError,\n  MachineNotStartedError,\n  TransitionDeniedError,\n} from \"./errors.js\";\nexport type {\n  IState,\n  IStateMachine,\n  StateChangeEvent,\n  StateMachineConfig,\n} from \"./interfaces.js\";\nexport type { StateEventListener } from \"./StateEvent.js\";\n","import type { IState } from \"./interfaces.js\";\n\n/**\n * Abstract base class providing default no-op lifecycle hooks.\n * Concrete states override only what they need.\n *\n * All hooks are synchronous. Model async work as its own state\n * that polls for completion in onUpdate.\n */\nexport abstract class BaseState<TContext, TStateId extends string>\n  implements IState<TContext, TStateId>\n{\n  abstract readonly id: TStateId;\n\n  canTransitionTo(_targetState: TStateId, _ctx: TContext): boolean {\n    return true;\n  }\n\n  onEnter(_ctx: TContext, _prevState: TStateId | null): void {\n    // no-op\n  }\n\n  onUpdate(_ctx: TContext, _dt: number): TStateId | undefined {\n    return undefined;\n  }\n\n  onExit(_ctx: TContext, _nextState: TStateId | null): void {\n    // no-op\n  }\n}\n","import type { StateChangeEvent } from \"./interfaces.js\";\n\nexport type StateEventListener<TStateId extends string> = (\n  event: StateChangeEvent<TStateId>,\n) => void;\n\n/**\n * Typed event emitter for state changes with bounded history.\n */\nexport class StateEventEmitter<TStateId extends string> {\n  private readonly listeners: StateEventListener<TStateId>[] = [];\n  private readonly history: StateChangeEvent<TStateId>[] = [];\n  private readonly maxHistory: number;\n\n  constructor(maxHistory: number = 100) {\n    this.maxHistory = maxHistory;\n  }\n\n  on(listener: StateEventListener<TStateId>): () => void {\n    this.listeners.push(listener);\n    return () => {\n      const idx = this.listeners.indexOf(listener);\n      if (idx !== -1) this.listeners.splice(idx, 1);\n    };\n  }\n\n  emit(change: StateChangeEvent<TStateId>): void {\n    this.history.push(change);\n    if (this.history.length > this.maxHistory) {\n      this.history.shift();\n    }\n    for (const listener of this.listeners) {\n      listener(change);\n    }\n  }\n\n  getHistory(): ReadonlyArray<StateChangeEvent<TStateId>> {\n    return [...this.history];\n  }\n\n  clear(): void {\n    this.history.length = 0;\n    this.listeners.length = 0;\n  }\n}\n","export class StateNotFoundError extends Error {\n  constructor(stateId: string) {\n    super(`State not found: \"${stateId}\"`);\n    this.name = \"StateNotFoundError\";\n  }\n}\n\nexport class MachineNotStartedError extends Error {\n  constructor() {\n    super(\"State machine has not been started. Call start() first.\");\n    this.name = \"MachineNotStartedError\";\n  }\n}\n\nexport class TransitionDeniedError extends Error {\n  constructor(from: string, to: string) {\n    super(`Transition denied: \"${from}\" -> \"${to}\"`);\n    this.name = \"TransitionDeniedError\";\n  }\n}\n","import type {\n  IState,\n  IStateMachine,\n  StateMachineConfig,\n  StateChangeEvent,\n} from \"./interfaces.js\";\nimport { StateEventEmitter, type StateEventListener } from \"./StateEvent.js\";\nimport {\n  StateNotFoundError,\n  MachineNotStartedError,\n  TransitionDeniedError,\n} from \"./errors.js\";\n\nexport class StateMachine<TContext, TStateId extends string>\n  implements IStateMachine<TContext, TStateId>\n{\n  private readonly stateMap = new Map<TStateId, IState<TContext, TStateId>>();\n  private readonly emitter: StateEventEmitter<TStateId>;\n  private currentState: IState<TContext, TStateId> | null = null;\n  private readonly initialStateId: TStateId;\n  private _isStarted = false;\n\n  readonly context: TContext;\n\n  constructor(config: StateMachineConfig<TContext, TStateId>) {\n    this.context = config.context;\n    this.initialStateId = config.initialState;\n    this.emitter = new StateEventEmitter(config.historySize ?? 100);\n\n    for (const state of config.states) {\n      if (this.stateMap.has(state.id)) {\n        throw new Error(`Duplicate state id: \"${state.id}\"`);\n      }\n      this.stateMap.set(state.id, state);\n    }\n\n    if (!this.stateMap.has(config.initialState)) {\n      throw new StateNotFoundError(config.initialState);\n    }\n  }\n\n  get currentStateId(): TStateId {\n    if (!this.currentState) throw new MachineNotStartedError();\n    return this.currentState.id;\n  }\n\n  get isStarted(): boolean {\n    return this._isStarted;\n  }\n\n  start(): void {\n    if (this._isStarted) return;\n    const state = this.stateMap.get(this.initialStateId);\n    if (!state) throw new StateNotFoundError(this.initialStateId);\n    this.currentState = state;\n    this._isStarted = true;\n    this.currentState.onEnter(this.context, null);\n  }\n\n  stop(): void {\n    if (!this._isStarted || !this.currentState) return;\n    this.currentState.onExit(this.context, null);\n    this.currentState = null;\n    this._isStarted = false;\n  }\n\n  transitionTo(stateId: TStateId): void {\n    if (!this.currentState) throw new MachineNotStartedError();\n    const to = this.stateMap.get(stateId);\n    if (!to) throw new StateNotFoundError(stateId);\n\n    const from = this.currentState;\n    if (!from.canTransitionTo(stateId, this.context)) {\n      throw new TransitionDeniedError(from.id, stateId);\n    }\n\n    const change: StateChangeEvent<TStateId> = {\n      from: from.id,\n      to: to.id,\n      timestamp: Date.now(),\n    };\n\n    from.onExit(this.context, to.id);\n    this.currentState = to;\n    this.emitter.emit(change);\n    to.onEnter(this.context, from.id);\n  }\n\n  update(dt: number): void {\n    if (!this.currentState) throw new MachineNotStartedError();\n    const next = this.currentState.onUpdate(this.context, dt);\n    if (next) {\n      this.transitionTo(next);\n    }\n  }\n\n  on(listener: StateEventListener<TStateId>): () => void {\n    return this.emitter.on(listener);\n  }\n\n  getHistory(): ReadonlyArray<StateChangeEvent<TStateId>> {\n    return this.emitter.getHistory();\n  }\n}\n","import { BaseState } from \"./State.js\";\nimport { StateMachine } from \"./StateMachine.js\";\nimport type { StateMachineConfig } from \"./interfaces.js\";\n\n/**\n * A composite state that contains a nested StateMachine.\n * When this state is entered, the nested machine starts.\n * When this state is exited, the nested machine stops.\n * On update, the nested machine is updated.\n */\nexport abstract class HierarchicalState<\n  TContext,\n  TStateId extends string,\n  TChildStateId extends string,\n> extends BaseState<TContext, TStateId> {\n  protected childMachine: StateMachine<TContext, TChildStateId> | null = null;\n\n  protected abstract createChildConfig(\n    ctx: TContext,\n  ): StateMachineConfig<TContext, TChildStateId>;\n\n  override onEnter(ctx: TContext, _prevState: TStateId | null): void {\n    const config = this.createChildConfig(ctx);\n    this.childMachine = new StateMachine(config);\n    this.childMachine.start();\n  }\n\n  override onUpdate(_ctx: TContext, _dt: number): TStateId | undefined {\n    // Child machine update must be called separately by the consumer\n    // or override this method to call this.childMachine.update(dt).\n    return undefined;\n  }\n\n  override onExit(_ctx: TContext, _nextState: TStateId | null): void {\n    this.childMachine?.stop();\n    this.childMachine = null;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+/**
+ * A single state in the machine.
+ * TContext is shared mutable data, TStateId identifies states.
+ *
+ * All lifecycle hooks are synchronous. Model async work as its own
+ * state that polls for completion in onUpdate.
+ */
+interface IState<TContext, TStateId extends string> {
+    readonly id: TStateId;
+    canTransitionTo(targetState: TStateId, ctx: TContext): boolean;
+    onEnter(ctx: TContext, prevState: TStateId | null): void;
+    onUpdate(ctx: TContext, dt: number): TStateId | undefined;
+    onExit(ctx: TContext, nextState: TStateId | null): void;
+}
+/**
+ * Recorded state change for history / debugging.
+ */
+interface StateChangeEvent<TStateId extends string> {
+    from: TStateId;
+    to: TStateId;
+    timestamp: number;
+}
+/**
+ * Configuration to construct a StateMachine.
+ */
+interface StateMachineConfig<TContext, TStateId extends string> {
+    states: IState<TContext, TStateId>[];
+    initialState: TStateId;
+    context: TContext;
+    historySize?: number;
+}
+/**
+ * Public interface for a state machine.
+ */
+interface IStateMachine<TContext, TStateId extends string> {
+    readonly currentStateId: TStateId;
+    readonly context: TContext;
+    readonly isStarted: boolean;
+    start(): void;
+    stop(): void;
+    transitionTo(stateId: TStateId): void;
+    update(dt: number): void;
+    getHistory(): ReadonlyArray<StateChangeEvent<TStateId>>;
+}
+
+/**
+ * Abstract base class providing default no-op lifecycle hooks.
+ * Concrete states override only what they need.
+ *
+ * All hooks are synchronous. Model async work as its own state
+ * that polls for completion in onUpdate.
+ */
+declare abstract class BaseState<TContext, TStateId extends string> implements IState<TContext, TStateId> {
+    abstract readonly id: TStateId;
+    canTransitionTo(_targetState: TStateId, _ctx: TContext): boolean;
+    onEnter(_ctx: TContext, _prevState: TStateId | null): void;
+    onUpdate(_ctx: TContext, _dt: number): TStateId | undefined;
+    onExit(_ctx: TContext, _nextState: TStateId | null): void;
+}
+
+type StateEventListener<TStateId extends string> = (event: StateChangeEvent<TStateId>) => void;
+/**
+ * Typed event emitter for state changes with bounded history.
+ */
+declare class StateEventEmitter<TStateId extends string> {
+    private readonly listeners;
+    private readonly history;
+    private readonly maxHistory;
+    constructor(maxHistory?: number);
+    on(listener: StateEventListener<TStateId>): () => void;
+    emit(change: StateChangeEvent<TStateId>): void;
+    getHistory(): ReadonlyArray<StateChangeEvent<TStateId>>;
+    clear(): void;
+}
+
+declare class StateMachine<TContext, TStateId extends string> implements IStateMachine<TContext, TStateId> {
+    private readonly stateMap;
+    private readonly emitter;
+    private currentState;
+    private readonly initialStateId;
+    private _isStarted;
+    readonly context: TContext;
+    constructor(config: StateMachineConfig<TContext, TStateId>);
+    get currentStateId(): TStateId;
+    get isStarted(): boolean;
+    start(): void;
+    stop(): void;
+    transitionTo(stateId: TStateId): void;
+    update(dt: number): void;
+    on(listener: StateEventListener<TStateId>): () => void;
+    getHistory(): ReadonlyArray<StateChangeEvent<TStateId>>;
+}
+
+/**
+ * A composite state that contains a nested StateMachine.
+ * When this state is entered, the nested machine starts.
+ * When this state is exited, the nested machine stops.
+ * On update, the nested machine is updated.
+ */
+declare abstract class HierarchicalState<TContext, TStateId extends string, TChildStateId extends string> extends BaseState<TContext, TStateId> {
+    protected childMachine: StateMachine<TContext, TChildStateId> | null;
+    protected abstract createChildConfig(ctx: TContext): StateMachineConfig<TContext, TChildStateId>;
+    onEnter(ctx: TContext, _prevState: TStateId | null): void;
+    onUpdate(_ctx: TContext, _dt: number): TStateId | undefined;
+    onExit(_ctx: TContext, _nextState: TStateId | null): void;
+}
+
+declare class StateNotFoundError extends Error {
+    constructor(stateId: string);
+}
+declare class MachineNotStartedError extends Error {
+    constructor();
+}
+declare class TransitionDeniedError extends Error {
+    constructor(from: string, to: string);
+}
+
+export { BaseState, HierarchicalState, type IState, type IStateMachine, MachineNotStartedError, type StateChangeEvent, StateEventEmitter, type StateEventListener, StateMachine, type StateMachineConfig, StateNotFoundError, TransitionDeniedError };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A single state in the machine.
+ * TContext is shared mutable data, TStateId identifies states.
+ *
+ * All lifecycle hooks are synchronous. Model async work as its own
+ * state that polls for completion in onUpdate.
+ */
+interface IState<TContext, TStateId extends string> {
+    readonly id: TStateId;
+    canTransitionTo(targetState: TStateId, ctx: TContext): boolean;
+    onEnter(ctx: TContext, prevState: TStateId | null): void;
+    onUpdate(ctx: TContext, dt: number): TStateId | undefined;
+    onExit(ctx: TContext, nextState: TStateId | null): void;
+}
+/**
+ * Recorded state change for history / debugging.
+ */
+interface StateChangeEvent<TStateId extends string> {
+    from: TStateId;
+    to: TStateId;
+    timestamp: number;
+}
+/**
+ * Configuration to construct a StateMachine.
+ */
+interface StateMachineConfig<TContext, TStateId extends string> {
+    states: IState<TContext, TStateId>[];
+    initialState: TStateId;
+    context: TContext;
+    historySize?: number;
+}
+/**
+ * Public interface for a state machine.
+ */
+interface IStateMachine<TContext, TStateId extends string> {
+    readonly currentStateId: TStateId;
+    readonly context: TContext;
+    readonly isStarted: boolean;
+    start(): void;
+    stop(): void;
+    transitionTo(stateId: TStateId): void;
+    update(dt: number): void;
+    getHistory(): ReadonlyArray<StateChangeEvent<TStateId>>;
+}
+
+/**
+ * Abstract base class providing default no-op lifecycle hooks.
+ * Concrete states override only what they need.
+ *
+ * All hooks are synchronous. Model async work as its own state
+ * that polls for completion in onUpdate.
+ */
+declare abstract class BaseState<TContext, TStateId extends string> implements IState<TContext, TStateId> {
+    abstract readonly id: TStateId;
+    canTransitionTo(_targetState: TStateId, _ctx: TContext): boolean;
+    onEnter(_ctx: TContext, _prevState: TStateId | null): void;
+    onUpdate(_ctx: TContext, _dt: number): TStateId | undefined;
+    onExit(_ctx: TContext, _nextState: TStateId | null): void;
+}
+
+type StateEventListener<TStateId extends string> = (event: StateChangeEvent<TStateId>) => void;
+/**
+ * Typed event emitter for state changes with bounded history.
+ */
+declare class StateEventEmitter<TStateId extends string> {
+    private readonly listeners;
+    private readonly history;
+    private readonly maxHistory;
+    constructor(maxHistory?: number);
+    on(listener: StateEventListener<TStateId>): () => void;
+    emit(change: StateChangeEvent<TStateId>): void;
+    getHistory(): ReadonlyArray<StateChangeEvent<TStateId>>;
+    clear(): void;
+}
+
+declare class StateMachine<TContext, TStateId extends string> implements IStateMachine<TContext, TStateId> {
+    private readonly stateMap;
+    private readonly emitter;
+    private currentState;
+    private readonly initialStateId;
+    private _isStarted;
+    readonly context: TContext;
+    constructor(config: StateMachineConfig<TContext, TStateId>);
+    get currentStateId(): TStateId;
+    get isStarted(): boolean;
+    start(): void;
+    stop(): void;
+    transitionTo(stateId: TStateId): void;
+    update(dt: number): void;
+    on(listener: StateEventListener<TStateId>): () => void;
+    getHistory(): ReadonlyArray<StateChangeEvent<TStateId>>;
+}
+
+/**
+ * A composite state that contains a nested StateMachine.
+ * When this state is entered, the nested machine starts.
+ * When this state is exited, the nested machine stops.
+ * On update, the nested machine is updated.
+ */
+declare abstract class HierarchicalState<TContext, TStateId extends string, TChildStateId extends string> extends BaseState<TContext, TStateId> {
+    protected childMachine: StateMachine<TContext, TChildStateId> | null;
+    protected abstract createChildConfig(ctx: TContext): StateMachineConfig<TContext, TChildStateId>;
+    onEnter(ctx: TContext, _prevState: TStateId | null): void;
+    onUpdate(_ctx: TContext, _dt: number): TStateId | undefined;
+    onExit(_ctx: TContext, _nextState: TStateId | null): void;
+}
+
+declare class StateNotFoundError extends Error {
+    constructor(stateId: string);
+}
+declare class MachineNotStartedError extends Error {
+    constructor();
+}
+declare class TransitionDeniedError extends Error {
+    constructor(from: string, to: string);
+}
+
+export { BaseState, HierarchicalState, type IState, type IStateMachine, MachineNotStartedError, type StateChangeEvent, StateEventEmitter, type StateEventListener, StateMachine, type StateMachineConfig, StateNotFoundError, TransitionDeniedError };

package/dist/index.js

@@ -0,0 +1,169 @@
+// src/lib/State.ts
+var BaseState = class {
+  canTransitionTo(_targetState, _ctx) {
+    return true;
+  }
+  onEnter(_ctx, _prevState) {
+  }
+  onUpdate(_ctx, _dt) {
+    return void 0;
+  }
+  onExit(_ctx, _nextState) {
+  }
+};
+
+// src/lib/StateEvent.ts
+var StateEventEmitter = class {
+  listeners = [];
+  history = [];
+  maxHistory;
+  constructor(maxHistory = 100) {
+    this.maxHistory = maxHistory;
+  }
+  on(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const idx = this.listeners.indexOf(listener);
+      if (idx !== -1) this.listeners.splice(idx, 1);
+    };
+  }
+  emit(change) {
+    this.history.push(change);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+    for (const listener of this.listeners) {
+      listener(change);
+    }
+  }
+  getHistory() {
+    return [...this.history];
+  }
+  clear() {
+    this.history.length = 0;
+    this.listeners.length = 0;
+  }
+};
+
+// src/lib/errors.ts
+var StateNotFoundError = class extends Error {
+  constructor(stateId) {
+    super(`State not found: "${stateId}"`);
+    this.name = "StateNotFoundError";
+  }
+};
+var MachineNotStartedError = class extends Error {
+  constructor() {
+    super("State machine has not been started. Call start() first.");
+    this.name = "MachineNotStartedError";
+  }
+};
+var TransitionDeniedError = class extends Error {
+  constructor(from, to) {
+    super(`Transition denied: "${from}" -> "${to}"`);
+    this.name = "TransitionDeniedError";
+  }
+};
+
+// src/lib/StateMachine.ts
+var StateMachine = class {
+  stateMap = /* @__PURE__ */ new Map();
+  emitter;
+  currentState = null;
+  initialStateId;
+  _isStarted = false;
+  context;
+  constructor(config) {
+    this.context = config.context;
+    this.initialStateId = config.initialState;
+    this.emitter = new StateEventEmitter(config.historySize ?? 100);
+    for (const state of config.states) {
+      if (this.stateMap.has(state.id)) {
+        throw new Error(`Duplicate state id: "${state.id}"`);
+      }
+      this.stateMap.set(state.id, state);
+    }
+    if (!this.stateMap.has(config.initialState)) {
+      throw new StateNotFoundError(config.initialState);
+    }
+  }
+  get currentStateId() {
+    if (!this.currentState) throw new MachineNotStartedError();
+    return this.currentState.id;
+  }
+  get isStarted() {
+    return this._isStarted;
+  }
+  start() {
+    if (this._isStarted) return;
+    const state = this.stateMap.get(this.initialStateId);
+    if (!state) throw new StateNotFoundError(this.initialStateId);
+    this.currentState = state;
+    this._isStarted = true;
+    this.currentState.onEnter(this.context, null);
+  }
+  stop() {
+    if (!this._isStarted || !this.currentState) return;
+    this.currentState.onExit(this.context, null);
+    this.currentState = null;
+    this._isStarted = false;
+  }
+  transitionTo(stateId) {
+    if (!this.currentState) throw new MachineNotStartedError();
+    const to = this.stateMap.get(stateId);
+    if (!to) throw new StateNotFoundError(stateId);
+    const from = this.currentState;
+    if (!from.canTransitionTo(stateId, this.context)) {
+      throw new TransitionDeniedError(from.id, stateId);
+    }
+    const change = {
+      from: from.id,
+      to: to.id,
+      timestamp: Date.now()
+    };
+    from.onExit(this.context, to.id);
+    this.currentState = to;
+    this.emitter.emit(change);
+    to.onEnter(this.context, from.id);
+  }
+  update(dt) {
+    if (!this.currentState) throw new MachineNotStartedError();
+    const next = this.currentState.onUpdate(this.context, dt);
+    if (next) {
+      this.transitionTo(next);
+    }
+  }
+  on(listener) {
+    return this.emitter.on(listener);
+  }
+  getHistory() {
+    return this.emitter.getHistory();
+  }
+};
+
+// src/lib/HierarchicalState.ts
+var HierarchicalState = class extends BaseState {
+  childMachine = null;
+  onEnter(ctx, _prevState) {
+    const config = this.createChildConfig(ctx);
+    this.childMachine = new StateMachine(config);
+    this.childMachine.start();
+  }
+  onUpdate(_ctx, _dt) {
+    return void 0;
+  }
+  onExit(_ctx, _nextState) {
+    this.childMachine?.stop();
+    this.childMachine = null;
+  }
+};
+export {
+  BaseState,
+  HierarchicalState,
+  MachineNotStartedError,
+  StateEventEmitter,
+  StateMachine,
+  StateNotFoundError,
+  TransitionDeniedError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/State.ts","../src/lib/StateEvent.ts","../src/lib/errors.ts","../src/lib/StateMachine.ts","../src/lib/HierarchicalState.ts"],"sourcesContent":["import type { IState } from \"./interfaces.js\";\n\n/**\n * Abstract base class providing default no-op lifecycle hooks.\n * Concrete states override only what they need.\n *\n * All hooks are synchronous. Model async work as its own state\n * that polls for completion in onUpdate.\n */\nexport abstract class BaseState<TContext, TStateId extends string>\n  implements IState<TContext, TStateId>\n{\n  abstract readonly id: TStateId;\n\n  canTransitionTo(_targetState: TStateId, _ctx: TContext): boolean {\n    return true;\n  }\n\n  onEnter(_ctx: TContext, _prevState: TStateId | null): void {\n    // no-op\n  }\n\n  onUpdate(_ctx: TContext, _dt: number): TStateId | undefined {\n    return undefined;\n  }\n\n  onExit(_ctx: TContext, _nextState: TStateId | null): void {\n    // no-op\n  }\n}\n","import type { StateChangeEvent } from \"./interfaces.js\";\n\nexport type StateEventListener<TStateId extends string> = (\n  event: StateChangeEvent<TStateId>,\n) => void;\n\n/**\n * Typed event emitter for state changes with bounded history.\n */\nexport class StateEventEmitter<TStateId extends string> {\n  private readonly listeners: StateEventListener<TStateId>[] = [];\n  private readonly history: StateChangeEvent<TStateId>[] = [];\n  private readonly maxHistory: number;\n\n  constructor(maxHistory: number = 100) {\n    this.maxHistory = maxHistory;\n  }\n\n  on(listener: StateEventListener<TStateId>): () => void {\n    this.listeners.push(listener);\n    return () => {\n      const idx = this.listeners.indexOf(listener);\n      if (idx !== -1) this.listeners.splice(idx, 1);\n    };\n  }\n\n  emit(change: StateChangeEvent<TStateId>): void {\n    this.history.push(change);\n    if (this.history.length > this.maxHistory) {\n      this.history.shift();\n    }\n    for (const listener of this.listeners) {\n      listener(change);\n    }\n  }\n\n  getHistory(): ReadonlyArray<StateChangeEvent<TStateId>> {\n    return [...this.history];\n  }\n\n  clear(): void {\n    this.history.length = 0;\n    this.listeners.length = 0;\n  }\n}\n","export class StateNotFoundError extends Error {\n  constructor(stateId: string) {\n    super(`State not found: \"${stateId}\"`);\n    this.name = \"StateNotFoundError\";\n  }\n}\n\nexport class MachineNotStartedError extends Error {\n  constructor() {\n    super(\"State machine has not been started. Call start() first.\");\n    this.name = \"MachineNotStartedError\";\n  }\n}\n\nexport class TransitionDeniedError extends Error {\n  constructor(from: string, to: string) {\n    super(`Transition denied: \"${from}\" -> \"${to}\"`);\n    this.name = \"TransitionDeniedError\";\n  }\n}\n","import type {\n  IState,\n  IStateMachine,\n  StateMachineConfig,\n  StateChangeEvent,\n} from \"./interfaces.js\";\nimport { StateEventEmitter, type StateEventListener } from \"./StateEvent.js\";\nimport {\n  StateNotFoundError,\n  MachineNotStartedError,\n  TransitionDeniedError,\n} from \"./errors.js\";\n\nexport class StateMachine<TContext, TStateId extends string>\n  implements IStateMachine<TContext, TStateId>\n{\n  private readonly stateMap = new Map<TStateId, IState<TContext, TStateId>>();\n  private readonly emitter: StateEventEmitter<TStateId>;\n  private currentState: IState<TContext, TStateId> | null = null;\n  private readonly initialStateId: TStateId;\n  private _isStarted = false;\n\n  readonly context: TContext;\n\n  constructor(config: StateMachineConfig<TContext, TStateId>) {\n    this.context = config.context;\n    this.initialStateId = config.initialState;\n    this.emitter = new StateEventEmitter(config.historySize ?? 100);\n\n    for (const state of config.states) {\n      if (this.stateMap.has(state.id)) {\n        throw new Error(`Duplicate state id: \"${state.id}\"`);\n      }\n      this.stateMap.set(state.id, state);\n    }\n\n    if (!this.stateMap.has(config.initialState)) {\n      throw new StateNotFoundError(config.initialState);\n    }\n  }\n\n  get currentStateId(): TStateId {\n    if (!this.currentState) throw new MachineNotStartedError();\n    return this.currentState.id;\n  }\n\n  get isStarted(): boolean {\n    return this._isStarted;\n  }\n\n  start(): void {\n    if (this._isStarted) return;\n    const state = this.stateMap.get(this.initialStateId);\n    if (!state) throw new StateNotFoundError(this.initialStateId);\n    this.currentState = state;\n    this._isStarted = true;\n    this.currentState.onEnter(this.context, null);\n  }\n\n  stop(): void {\n    if (!this._isStarted || !this.currentState) return;\n    this.currentState.onExit(this.context, null);\n    this.currentState = null;\n    this._isStarted = false;\n  }\n\n  transitionTo(stateId: TStateId): void {\n    if (!this.currentState) throw new MachineNotStartedError();\n    const to = this.stateMap.get(stateId);\n    if (!to) throw new StateNotFoundError(stateId);\n\n    const from = this.currentState;\n    if (!from.canTransitionTo(stateId, this.context)) {\n      throw new TransitionDeniedError(from.id, stateId);\n    }\n\n    const change: StateChangeEvent<TStateId> = {\n      from: from.id,\n      to: to.id,\n      timestamp: Date.now(),\n    };\n\n    from.onExit(this.context, to.id);\n    this.currentState = to;\n    this.emitter.emit(change);\n    to.onEnter(this.context, from.id);\n  }\n\n  update(dt: number): void {\n    if (!this.currentState) throw new MachineNotStartedError();\n    const next = this.currentState.onUpdate(this.context, dt);\n    if (next) {\n      this.transitionTo(next);\n    }\n  }\n\n  on(listener: StateEventListener<TStateId>): () => void {\n    return this.emitter.on(listener);\n  }\n\n  getHistory(): ReadonlyArray<StateChangeEvent<TStateId>> {\n    return this.emitter.getHistory();\n  }\n}\n","import { BaseState } from \"./State.js\";\nimport { StateMachine } from \"./StateMachine.js\";\nimport type { StateMachineConfig } from \"./interfaces.js\";\n\n/**\n * A composite state that contains a nested StateMachine.\n * When this state is entered, the nested machine starts.\n * When this state is exited, the nested machine stops.\n * On update, the nested machine is updated.\n */\nexport abstract class HierarchicalState<\n  TContext,\n  TStateId extends string,\n  TChildStateId extends string,\n> extends BaseState<TContext, TStateId> {\n  protected childMachine: StateMachine<TContext, TChildStateId> | null = null;\n\n  protected abstract createChildConfig(\n    ctx: TContext,\n  ): StateMachineConfig<TContext, TChildStateId>;\n\n  override onEnter(ctx: TContext, _prevState: TStateId | null): void {\n    const config = this.createChildConfig(ctx);\n    this.childMachine = new StateMachine(config);\n    this.childMachine.start();\n  }\n\n  override onUpdate(_ctx: TContext, _dt: number): TStateId | undefined {\n    // Child machine update must be called separately by the consumer\n    // or override this method to call this.childMachine.update(dt).\n    return undefined;\n  }\n\n  override onExit(_ctx: TContext, _nextState: TStateId | null): void {\n    this.childMachine?.stop();\n    this.childMachine = null;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@duyquangnvx/state-machine",
+  "version": "0.1.0",
+  "description": "Generic, type-safe finite state machine library for TypeScript",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "publishConfig": { "access": "public" },
+  "license": "ISC",
+  "keywords": ["state-machine", "fsm", "typescript", "game", "state"],
+  "scripts": {
+    "build": "tsup",
+    "build:demo": "tsc",
+    "demo": "npm run build:demo && node dist/demo/main.js",
+    "demo:slot": "npm run build:demo && node dist/demo/slot-main.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0"
+  }
+}