@billdaddy/hsmkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trananhtung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# hsmkit
+
+[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
+
+> Zero-dependency TypeScript hierarchical state machine (HSM/statecharts). Compound states, entry/exit actions, guards, shallow history, internal transitions. Port of Python `pytransitions` / C# `Stateless` / Ruby `AASM` — lighter than XState.
+
+[![npm](https://img.shields.io/npm/v/@billdaddy/hsmkit)](https://www.npmjs.com/package/@billdaddy/hsmkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Install
+
+```bash
+npm install @billdaddy/hsmkit
+```
+
+## Quick start
+
+```typescript
+import { createHSM } from "@billdaddy/hsmkit";
+
+const machine = createHSM({
+  initial: "idle",
+  context: { count: 0 },
+  states: {
+    idle: {
+      on: { START: "active" },
+    },
+    active: {
+      initial: "running",           // compound state
+      entry: (ctx) => { console.log("entered active"); return ctx; },
+      exit:  (ctx) => { console.log("exited active");  return ctx; },
+      states: {
+        running: {
+          on: {
+            PAUSE: "active.paused", // transition within compound state
+            STOP:  "idle",          // exit compound state
+          },
+        },
+        paused: {
+          on: {
+            RESUME: "active.running",
+            STOP:   "idle",
+          },
+        },
+      },
+    },
+  },
+});
+
+const service = machine.start();
+service.state;              // "idle"
+service.send("START");
+service.state;              // "active.running"
+service.send("PAUSE");
+service.state;              // "active.paused"
+service.matches("active");  // true — prefix match
+service.send("STOP");
+service.state;              // "idle"
+```
+
+## Why hsmkit?
+
+| Library | Download/week | Last updated | Hierarchical? | Zero-dep? |
+|---|---|---|---|---|
+| XState | ~3M | Active | ✅ statecharts | ❌ (actor model) |
+| `@steelbreeze/state` | ~344 | **March 2022** | ✅ | ✅ |
+| `javascript-state-machine` | ~1.8M | **2021** | ❌ flat only | ✅ |
+| **hsmkit** | — | **Active** | ✅ | ✅ |
+
+XState is excellent but its v5 abstraction is the **actor model** — the right tool for distributed systems, not for a simple UI component or protocol parser. `hsmkit` gives you the core of Harel statecharts (the part that matters for most uses) in 0 dependencies.
+
+## Features
+
+- **Compound states** — states that contain child states (hierarchical nesting)
+- **Entry/exit actions** — called at LCA-correct depth on every transition
+- **Guards** — conditional transitions with fallthrough to next candidate
+- **Shallow history** — remember last active substate across interruptions
+- **Internal transitions** — actions without exit/entry (via `target: undefined`)
+- **Event payload** — pass data with `service.send("EVT", { value: 42 })`
+- **Mutable context** — return new context from actions
+- **subscribe()** — listen to every state change; returns an unsubscribe function
+
+## API
+
+### `createHSM(config)`
+
+```typescript
+const machine = createHSM({
+  initial: "idle",         // required: initial state (dot-notation for nested)
+  context: { count: 0 },  // optional: initial context
+  states: {               // state definitions
+    idle: { ... },
+    active: { ... },
+  },
+});
+```
+
+### `StateConfig`
+
+```typescript
+interface StateConfig<Ctx> {
+  initial?: string;          // required for compound states
+  states?: Record<string, StateConfig<Ctx>>;  // child states
+  history?: boolean;         // shallow history (default: false)
+  entry?: ActionFn<Ctx> | ActionFn<Ctx>[];
+  exit?:  ActionFn<Ctx> | ActionFn<Ctx>[];
+  on?: Record<string, TransitionTarget>;
+}
+
+// Transition targets:
+"stateName"                          // simple target
+"parent.child"                       // nested target (dot-notation)
+{ target: "stateName", guard, actions }  // with guard/actions
+[{ target, guard }, { target }]      // multiple candidates (fallthrough)
+{ target: undefined, actions: [...] } // internal (no exit/entry)
+```
+
+### `HSMService`
+
+```typescript
+service.state         // string — e.g. "active.running"
+service.stateValue    // string[] — e.g. ["active", "running"]
+service.context       // current context
+service.send(type, payload?)   // fire an event, returns this
+service.matches(state)         // true if state is prefix of current path
+service.subscribe(fn)          // returns unsub function
+```
+
+## Examples
+
+### Guards with fallthrough
+
+```typescript
+const machine = createHSM({
+  initial: "idle",
+  context: { role: "guest" },
+  states: {
+    idle: {
+      on: {
+        ENTER: [
+          { target: "admin",  guard: (ctx) => ctx.role === "admin" },
+          { target: "user",   guard: (ctx) => ctx.role === "user"  },
+          { target: "guest" },     // default — no guard
+        ],
+      },
+    },
+    admin: {}, user: {}, guest: {},
+  },
+});
+```
+
+### Shallow history — audio player
+
+```typescript
+const player = createHSM({
+  initial: "idle",
+  states: {
+    idle: { on: { PLAY: "playing" } },
+    playing: {
+      history: true,         // remember last substate
+      initial: "normal",
+      on: { PAUSE_ALL: "idle" },
+      states: {
+        normal:  { on: { SHUFFLE: "playing.shuffle" } },
+        shuffle: { on: { NORMAL: "playing.normal"  } },
+      },
+    },
+  },
+});
+
+const s = player.start();
+s.send("PLAY").send("SHUFFLE");  // playing.shuffle
+s.send("PAUSE_ALL").send("PLAY"); // returns to playing.shuffle (history!)
+```
+
+### Internal transitions (no exit/entry)
+
+```typescript
+const machine = createHSM({
+  initial: "active",
+  context: { ticks: 0 },
+  states: {
+    active: {
+      on: {
+        TICK: [{
+          // target: undefined — internal transition
+          actions: [(ctx) => ({ ...ctx, ticks: ctx.ticks + 1 })],
+        }],
+      },
+    },
+  },
+});
+```
+
+### Traffic light
+
+```typescript
+const light = createHSM({
+  initial: "green",
+  states: {
+    green:  { on: { NEXT: "yellow" } },
+    yellow: { on: { NEXT: "red"    } },
+    red:    { on: { NEXT: "green"  } },
+  },
+});
+const s = light.start();
+s.send("NEXT").send("NEXT").send("NEXT");
+s.state; // "green"
+```
+
+## Comparison
+
+| Feature | `pytransitions` | C# `Stateless` | XState v5 | `hsmkit` |
+|---|---|---|---|---|
+| Compound states | ✅ | ✅ | ✅ | ✅ |
+| Entry/exit actions | ✅ | ✅ | ✅ | ✅ |
+| Guards | ✅ | ✅ | ✅ | ✅ |
+| History | ✅ | ✅ | ✅ | ✅ (shallow) |
+| Parallel regions | ✅ | ✅ | ✅ | ❌ (future) |
+| Actor model | ❌ | ❌ | ✅ (v5) | ❌ |
+| Zero dependencies | ✅ | ✅ | ❌ | ✅ |
+
+## Contributors ✨
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome — code, docs, bug reports, ideas, reviews! See the [emoji key](https://allcontributors.org/docs/en/emoji-key) for how each contribution is recognized, and open a PR or issue to get involved.
+
+Thanks goes to these wonderful people:
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/trananhtung"><img src="https://avatars.githubusercontent.com/u/30992229?v=4?s=100" width="100px;" alt="Tung Tran"/><br /><sub><b>Tung Tran</b></sub></a><br /><a href="https://github.com/trananhtung/hsmkit/commits?author=trananhtung" title="Code">💻</a> <a href="#maintenance-trananhtung" title="Maintenance">🚧</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+## License
+
+MIT © [trananhtung](https://github.com/trananhtung)

package/dist/index.cjs

@@ -0,0 +1,236 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HSM: () => HSM,
+  HSMError: () => HSMError,
+  HSMService: () => HSMService,
+  createHSM: () => createHSM
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hsm.ts
+function buildNode(id, config, parent) {
+  const node = {
+    id,
+    initial: config.initial,
+    children: /* @__PURE__ */ new Map(),
+    parent,
+    transitions: /* @__PURE__ */ new Map(),
+    entry: config.entry ? Array.isArray(config.entry) ? config.entry : [config.entry] : [],
+    exit: config.exit ? Array.isArray(config.exit) ? config.exit : [config.exit] : [],
+    history: config.history ?? false
+  };
+  if (config.states) {
+    for (const [childId, childConfig] of Object.entries(config.states)) {
+      node.children.set(childId, buildNode(childId, childConfig, node));
+    }
+  }
+  if (config.on) {
+    for (const [eventType, transConfig] of Object.entries(config.on)) {
+      const defs = parseTransitions(transConfig);
+      node.transitions.set(eventType, defs);
+    }
+  }
+  return node;
+}
+function parseTransitions(raw) {
+  if (typeof raw === "string") {
+    return [{ target: raw, actions: [] }];
+  }
+  if (Array.isArray(raw)) {
+    return raw.map((t) => ({
+      target: t.target,
+      guard: t.guard,
+      actions: t.actions ?? []
+    }));
+  }
+  return [{ target: raw.target, guard: raw.guard, actions: raw.actions ?? [] }];
+}
+function getNodeAtPath(root, path) {
+  let node = root;
+  for (const id of path) {
+    const child = node.children.get(id);
+    if (!child) throw new HSMError(`State "${id}" not found`);
+    node = child;
+  }
+  return node;
+}
+function resolvePath(target) {
+  return target.split(".");
+}
+function lcaDepth(a, b) {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+function expandToLeaf(root, path, ctx, event) {
+  let cur = getNodeAtPath(root, path);
+  let p = [...path];
+  while (cur.children.size > 0) {
+    if (!cur.initial) throw new HSMError(`Compound state "${p.join(".")}" has no initial substate`);
+    const childId = cur.history && cur.historyValue ? cur.historyValue : cur.initial;
+    cur = cur.children.get(childId);
+    for (const fn of cur.entry) ctx = fn(ctx, event) ?? ctx;
+    p.push(childId);
+  }
+  return { path: p, ctx };
+}
+var HSMError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HSMError";
+  }
+};
+var HSMService = class {
+  constructor(root, initialPath, ctx) {
+    this._listeners = /* @__PURE__ */ new Set();
+    this._root = root;
+    this._path = initialPath;
+    this._ctx = ctx;
+  }
+  /** Current state as dot-notation string, e.g. `"active.running"`. */
+  get state() {
+    return this._path.join(".");
+  }
+  /** Current context. */
+  get context() {
+    return this._ctx;
+  }
+  /** Current state as array path, e.g. `["active", "running"]`. */
+  get stateValue() {
+    return [...this._path];
+  }
+  /**
+   * Returns true if the current state matches the given prefix.
+   * `matches("active")` returns true for `"active.running"`.
+   */
+  matches(state) {
+    const parts = state.split(".");
+    return parts.every((part, i) => this._path[i] === part);
+  }
+  /**
+   * Send an event to the machine.
+   * Returns this for chaining.
+   */
+  send(eventType, payload = {}) {
+    const event = { type: eventType, ...payload };
+    for (let depth = this._path.length; depth >= 0; depth--) {
+      const nodePath = this._path.slice(0, depth);
+      const node = getNodeAtPath(this._root, nodePath);
+      const defs = node.transitions.get(eventType);
+      if (!defs) continue;
+      for (const def of defs) {
+        if (def.guard && !def.guard(this._ctx, event)) continue;
+        if (def.target === void 0) {
+          let ctx = this._ctx;
+          for (const fn of def.actions) ctx = fn(ctx, event) ?? ctx;
+          this._ctx = ctx;
+        } else {
+          const targetPath = resolvePath(def.target);
+          this._doTransition(this._path, nodePath, targetPath, def.actions, event);
+        }
+        this._notify(event);
+        return this;
+      }
+    }
+    return this;
+  }
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+  _notify(event) {
+    for (const fn of this._listeners) fn(this.state, this._ctx, event);
+  }
+  _doTransition(currentPath, sourcePath, targetPath, transActions, event) {
+    const lca = lcaDepth(currentPath, targetPath);
+    let ctx = this._ctx;
+    for (let i = currentPath.length - 1; i >= lca; i--) {
+      const node = getNodeAtPath(this._root, currentPath.slice(0, i + 1));
+      for (const fn of node.exit) ctx = fn(ctx, event) ?? ctx;
+      if (i > 0) {
+        const parent = getNodeAtPath(this._root, currentPath.slice(0, i));
+        if (parent.history) parent.historyValue = currentPath[i];
+      }
+    }
+    for (const fn of transActions) ctx = fn(ctx, event) ?? ctx;
+    for (let i = lca; i < targetPath.length; i++) {
+      const node = getNodeAtPath(this._root, targetPath.slice(0, i + 1));
+      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;
+    }
+    this._ctx = ctx;
+    const { path, ctx: finalCtx } = expandToLeaf(this._root, targetPath, ctx, event);
+    this._path = path;
+    this._ctx = finalCtx;
+  }
+};
+var HSM = class {
+  constructor(config) {
+    this._root = buildNode("__root__", { states: config.states });
+    this._initialCtx = config.context ?? {};
+    this._initial = config.initial;
+  }
+  _resolveInitialPath(root, initial) {
+    const basePath = resolvePath(initial);
+    let p = [];
+    let node = root;
+    for (const id of basePath) {
+      const child = node.children.get(id);
+      if (!child) throw new HSMError(`Initial state "${id}" not found`);
+      node = child;
+      p.push(id);
+    }
+    while (node.children.size > 0) {
+      if (!node.initial) throw new HSMError(`Compound state "${p.join(".")}" has no initial substate`);
+      const childId = node.initial;
+      node = node.children.get(childId);
+      p.push(childId);
+    }
+    return p;
+  }
+  /**
+   * Start the machine and run entry actions for the initial state path.
+   * Returns the running service.
+   */
+  start() {
+    const initialPath = this._resolveInitialPath(this._root, this._initial);
+    let ctx = this._initialCtx;
+    const event = { type: "__init__" };
+    for (let i = 0; i < initialPath.length; i++) {
+      const node = getNodeAtPath(this._root, initialPath.slice(0, i + 1));
+      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;
+    }
+    return new HSMService(this._root, [...initialPath], ctx);
+  }
+};
+function createHSM(config) {
+  return new HSM(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HSM,
+  HSMError,
+  HSMService,
+  createHSM
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hsm.ts"],"sourcesContent":["export type {\n  EventType,\n  StateId,\n  HSMEvent,\n  ActionFn,\n  GuardFn,\n  TransitionConfig,\n  StateConfig,\n  HSMConfig,\n  StateListener,\n} from \"./types.js\";\n\nexport { HSM, HSMService, HSMError, createHSM } from \"./hsm.js\";\n","import type {\n  ActionFn,\n  GuardFn,\n  HSMConfig,\n  HSMEvent,\n  StateConfig,\n  StateId,\n  StateListener,\n  TransitionConfig,\n} from \"./types.js\";\n\n// ── Internal state node ──────────────────────────────────────────────────────\n\ninterface StateNode<Ctx> {\n  id: string;\n  initial?: string;\n  children: Map<string, StateNode<Ctx>>;\n  parent?: StateNode<Ctx>;\n  transitions: Map<string, TransitionDef<Ctx>[]>;\n  entry: ActionFn<Ctx>[];\n  exit: ActionFn<Ctx>[];\n  history: boolean;\n  historyValue?: string;\n}\n\ninterface TransitionDef<Ctx> {\n  target?: string;\n  guard?: GuardFn<Ctx>;\n  actions: ActionFn<Ctx>[];\n}\n\n// ── Builder ──────────────────────────────────────────────────────────────────\n\nfunction buildNode<Ctx>(\n  id: string,\n  config: StateConfig<Ctx>,\n  parent?: StateNode<Ctx>,\n): StateNode<Ctx> {\n  const node: StateNode<Ctx> = {\n    id,\n    initial: config.initial,\n    children: new Map(),\n    parent,\n    transitions: new Map(),\n    entry: config.entry\n      ? Array.isArray(config.entry) ? config.entry : [config.entry]\n      : [],\n    exit: config.exit\n      ? Array.isArray(config.exit) ? config.exit : [config.exit]\n      : [],\n    history: config.history ?? false,\n  };\n\n  // Build child states\n  if (config.states) {\n    for (const [childId, childConfig] of Object.entries(config.states)) {\n      node.children.set(childId, buildNode(childId, childConfig, node));\n    }\n  }\n\n  // Parse transitions\n  if (config.on) {\n    for (const [eventType, transConfig] of Object.entries(config.on)) {\n      const defs = parseTransitions(transConfig as string | TransitionConfig<Ctx> | Array<TransitionConfig<Ctx>>);\n      node.transitions.set(eventType, defs);\n    }\n  }\n\n  return node;\n}\n\nfunction parseTransitions<Ctx>(\n  raw: string | TransitionConfig<Ctx> | Array<TransitionConfig<Ctx>>,\n): TransitionDef<Ctx>[] {\n  if (typeof raw === \"string\") {\n    return [{ target: raw, actions: [] }];\n  }\n  if (Array.isArray(raw)) {\n    return raw.map((t) => ({\n      target: t.target,\n      guard: t.guard,\n      actions: t.actions ?? [],\n    }));\n  }\n  return [{ target: raw.target, guard: raw.guard, actions: raw.actions ?? [] }];\n}\n\n// ── Path utilities ───────────────────────────────────────────────────────────\n\nfunction getNodeAtPath<Ctx>(root: StateNode<Ctx>, path: string[]): StateNode<Ctx> {\n  let node = root;\n  for (const id of path) {\n    const child = node.children.get(id);\n    if (!child) throw new HSMError(`State \"${id}\" not found`);\n    node = child;\n  }\n  return node;\n}\n\n/** Resolve a dotted target string to a path array from the virtual root. */\nfunction resolvePath(target: string): string[] {\n  return target.split(\".\");\n}\n\n/** LCA index: length of longest common prefix of two paths. */\nfunction lcaDepth(a: string[], b: string[]): number {\n  let i = 0;\n  while (i < a.length && i < b.length && a[i] === b[i]) i++;\n  return i;\n}\n\n/** Enter compound state to leaf following initial/history chain. */\nfunction expandToLeaf<Ctx>(\n  root: StateNode<Ctx>,\n  path: string[],\n  ctx: Ctx,\n  event: HSMEvent,\n): { path: string[]; ctx: Ctx } {\n  let cur = getNodeAtPath(root, path);\n  let p = [...path];\n\n  while (cur.children.size > 0) {\n    if (!cur.initial) throw new HSMError(`Compound state \"${p.join(\".\")}\" has no initial substate`);\n    const childId = cur.history && cur.historyValue ? cur.historyValue : cur.initial;\n    cur = cur.children.get(childId)!;\n    for (const fn of cur.entry) ctx = fn(ctx, event) ?? ctx;\n    p.push(childId);\n  }\n\n  return { path: p, ctx };\n}\n\n// ── HSMService ───────────────────────────────────────────────────────────────\n\nexport class HSMError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"HSMError\";\n  }\n}\n\nexport class HSMService<Ctx> {\n  private _path: string[];\n  private _ctx: Ctx;\n  private readonly _root: StateNode<Ctx>;\n  private readonly _listeners = new Set<StateListener<Ctx>>();\n\n  constructor(root: StateNode<Ctx>, initialPath: string[], ctx: Ctx) {\n    this._root = root;\n    this._path = initialPath;\n    this._ctx = ctx;\n  }\n\n  /** Current state as dot-notation string, e.g. `\"active.running\"`. */\n  get state(): string {\n    return this._path.join(\".\");\n  }\n\n  /** Current context. */\n  get context(): Ctx {\n    return this._ctx;\n  }\n\n  /** Current state as array path, e.g. `[\"active\", \"running\"]`. */\n  get stateValue(): string[] {\n    return [...this._path];\n  }\n\n  /**\n   * Returns true if the current state matches the given prefix.\n   * `matches(\"active\")` returns true for `\"active.running\"`.\n   */\n  matches(state: string): boolean {\n    const parts = state.split(\".\");\n    return parts.every((part, i) => this._path[i] === part);\n  }\n\n  /**\n   * Send an event to the machine.\n   * Returns this for chaining.\n   */\n  send(eventType: string, payload: Record<string, unknown> = {}): this {\n    const event: HSMEvent = { type: eventType, ...payload };\n\n    // Walk up from current leaf to root looking for applicable transition\n    for (let depth = this._path.length; depth >= 0; depth--) {\n      const nodePath = this._path.slice(0, depth);\n      const node = getNodeAtPath(this._root, nodePath);\n      const defs = node.transitions.get(eventType);\n      if (!defs) continue;\n\n      for (const def of defs) {\n        if (def.guard && !def.guard(this._ctx, event)) continue;\n\n        if (def.target === undefined) {\n          // Internal transition — run actions, no exit/entry\n          let ctx = this._ctx;\n          for (const fn of def.actions) ctx = fn(ctx, event) ?? ctx;\n          this._ctx = ctx;\n        } else {\n          const targetPath = resolvePath(def.target);\n          this._doTransition(this._path, nodePath, targetPath, def.actions, event);\n        }\n\n        this._notify(event);\n        return this;\n      }\n    }\n\n    return this;\n  }\n\n  /** Subscribe to state changes. Returns an unsubscribe function. */\n  subscribe(listener: StateListener<Ctx>): () => void {\n    this._listeners.add(listener);\n    return () => this._listeners.delete(listener);\n  }\n\n  private _notify(event: HSMEvent): void {\n    for (const fn of this._listeners) fn(this.state, this._ctx, event);\n  }\n\n  private _doTransition(\n    currentPath: string[],\n    sourcePath: string[],\n    targetPath: string[],\n    transActions: ActionFn<Ctx>[],\n    event: HSMEvent,\n  ): void {\n    const lca = lcaDepth(currentPath, targetPath);\n    let ctx = this._ctx;\n\n    // Exit from current leaf up to (not including) LCA\n    for (let i = currentPath.length - 1; i >= lca; i--) {\n      const node = getNodeAtPath(this._root, currentPath.slice(0, i + 1));\n      for (const fn of node.exit) ctx = fn(ctx, event) ?? ctx;\n\n      // Record history in parent\n      if (i > 0) {\n        const parent = getNodeAtPath(this._root, currentPath.slice(0, i));\n        if (parent.history) parent.historyValue = currentPath[i];\n      }\n    }\n\n    // Transition actions\n    for (const fn of transActions) ctx = fn(ctx, event) ?? ctx;\n\n    // Entry from LCA down to target\n    for (let i = lca; i < targetPath.length; i++) {\n      const node = getNodeAtPath(this._root, targetPath.slice(0, i + 1));\n      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;\n    }\n\n    this._ctx = ctx;\n\n    // Expand target compound state to leaf\n    const { path, ctx: finalCtx } = expandToLeaf(this._root, targetPath, ctx, event);\n    this._path = path;\n    this._ctx = finalCtx;\n  }\n}\n\n// ── HSM factory ───────────────────────────────────────────────────────────────\n\nexport class HSM<Ctx> {\n  private readonly _root: StateNode<Ctx>;\n  private readonly _initial: string;\n  private readonly _initialCtx: Ctx;\n\n  constructor(config: HSMConfig<Ctx>) {\n    this._root = buildNode<Ctx>(\"__root__\", { states: config.states } as StateConfig<Ctx>);\n    this._initialCtx = (config.context ?? ({} as unknown as Ctx));\n    this._initial = config.initial;\n  }\n\n  private _resolveInitialPath(root: StateNode<Ctx>, initial: string): string[] {\n    const basePath = resolvePath(initial);\n    let p: string[] = [];\n    let node = root;\n    for (const id of basePath) {\n      const child = node.children.get(id);\n      if (!child) throw new HSMError(`Initial state \"${id}\" not found`);\n      node = child;\n      p.push(id);\n    }\n    // Expand to leaf via initial chain\n    while (node.children.size > 0) {\n      if (!node.initial) throw new HSMError(`Compound state \"${p.join(\".\")}\" has no initial substate`);\n      const childId = node.initial;\n      node = node.children.get(childId)!;\n      p.push(childId);\n    }\n    return p;\n  }\n\n  /**\n   * Start the machine and run entry actions for the initial state path.\n   * Returns the running service.\n   */\n  start(): HSMService<Ctx> {\n    const initialPath = this._resolveInitialPath(this._root, this._initial);\n    let ctx = this._initialCtx;\n    const event: HSMEvent = { type: \"__init__\" };\n\n    // Run entry actions down to initial leaf\n    for (let i = 0; i < initialPath.length; i++) {\n      const node = getNodeAtPath(this._root, initialPath.slice(0, i + 1));\n      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;\n    }\n\n    return new HSMService<Ctx>(this._root, [...initialPath], ctx);\n  }\n}\n\n/**\n * Create a hierarchical state machine.\n *\n * @example\n * const machine = createHSM({\n *   initial: 'idle',\n *   context: { count: 0 },\n *   states: {\n *     idle: { on: { START: 'active' } },\n *     active: {\n *       initial: 'running',\n *       states: {\n *         running: { on: { PAUSE: 'active.paused', STOP: 'idle' } },\n *         paused:  { on: { RESUME: 'active.running', STOP: 'idle' } },\n *       },\n *     },\n *   },\n * });\n * const service = machine.start();\n */\nexport function createHSM<Ctx = Record<string, unknown>>(config: HSMConfig<Ctx>): HSM<Ctx> {\n  return new HSM(config);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,110 @@
+type EventType = string;
+type StateId = string;
+interface HSMEvent {
+    type: EventType;
+    [key: string]: unknown;
+}
+type ActionFn<Ctx> = (ctx: Ctx, event: HSMEvent) => Ctx | void;
+type GuardFn<Ctx> = (ctx: Ctx, event: HSMEvent) => boolean;
+interface TransitionConfig<Ctx> {
+    target?: string;
+    guard?: GuardFn<Ctx>;
+    actions?: ActionFn<Ctx>[];
+}
+interface StateConfig<Ctx> {
+    initial?: string;
+    type?: "compound" | "atomic";
+    states?: Record<string, StateConfig<Ctx>>;
+    on?: Record<string, string | TransitionConfig<Ctx> | Array<TransitionConfig<Ctx>>>;
+    entry?: ActionFn<Ctx> | ActionFn<Ctx>[];
+    exit?: ActionFn<Ctx> | ActionFn<Ctx>[];
+    history?: boolean;
+}
+interface HSMConfig<Ctx> {
+    initial: string;
+    context?: Ctx;
+    states: Record<string, StateConfig<Ctx>>;
+}
+type StateListener<Ctx> = (state: string, ctx: Ctx, event: HSMEvent) => void;
+
+interface StateNode<Ctx> {
+    id: string;
+    initial?: string;
+    children: Map<string, StateNode<Ctx>>;
+    parent?: StateNode<Ctx>;
+    transitions: Map<string, TransitionDef<Ctx>[]>;
+    entry: ActionFn<Ctx>[];
+    exit: ActionFn<Ctx>[];
+    history: boolean;
+    historyValue?: string;
+}
+interface TransitionDef<Ctx> {
+    target?: string;
+    guard?: GuardFn<Ctx>;
+    actions: ActionFn<Ctx>[];
+}
+declare class HSMError extends Error {
+    constructor(message: string);
+}
+declare class HSMService<Ctx> {
+    private _path;
+    private _ctx;
+    private readonly _root;
+    private readonly _listeners;
+    constructor(root: StateNode<Ctx>, initialPath: string[], ctx: Ctx);
+    /** Current state as dot-notation string, e.g. `"active.running"`. */
+    get state(): string;
+    /** Current context. */
+    get context(): Ctx;
+    /** Current state as array path, e.g. `["active", "running"]`. */
+    get stateValue(): string[];
+    /**
+     * Returns true if the current state matches the given prefix.
+     * `matches("active")` returns true for `"active.running"`.
+     */
+    matches(state: string): boolean;
+    /**
+     * Send an event to the machine.
+     * Returns this for chaining.
+     */
+    send(eventType: string, payload?: Record<string, unknown>): this;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: StateListener<Ctx>): () => void;
+    private _notify;
+    private _doTransition;
+}
+declare class HSM<Ctx> {
+    private readonly _root;
+    private readonly _initial;
+    private readonly _initialCtx;
+    constructor(config: HSMConfig<Ctx>);
+    private _resolveInitialPath;
+    /**
+     * Start the machine and run entry actions for the initial state path.
+     * Returns the running service.
+     */
+    start(): HSMService<Ctx>;
+}
+/**
+ * Create a hierarchical state machine.
+ *
+ * @example
+ * const machine = createHSM({
+ *   initial: 'idle',
+ *   context: { count: 0 },
+ *   states: {
+ *     idle: { on: { START: 'active' } },
+ *     active: {
+ *       initial: 'running',
+ *       states: {
+ *         running: { on: { PAUSE: 'active.paused', STOP: 'idle' } },
+ *         paused:  { on: { RESUME: 'active.running', STOP: 'idle' } },
+ *       },
+ *     },
+ *   },
+ * });
+ * const service = machine.start();
+ */
+declare function createHSM<Ctx = Record<string, unknown>>(config: HSMConfig<Ctx>): HSM<Ctx>;
+
+export { type ActionFn, type EventType, type GuardFn, HSM, type HSMConfig, HSMError, type HSMEvent, HSMService, type StateConfig, type StateId, type StateListener, type TransitionConfig, createHSM };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+type EventType = string;
+type StateId = string;
+interface HSMEvent {
+    type: EventType;
+    [key: string]: unknown;
+}
+type ActionFn<Ctx> = (ctx: Ctx, event: HSMEvent) => Ctx | void;
+type GuardFn<Ctx> = (ctx: Ctx, event: HSMEvent) => boolean;
+interface TransitionConfig<Ctx> {
+    target?: string;
+    guard?: GuardFn<Ctx>;
+    actions?: ActionFn<Ctx>[];
+}
+interface StateConfig<Ctx> {
+    initial?: string;
+    type?: "compound" | "atomic";
+    states?: Record<string, StateConfig<Ctx>>;
+    on?: Record<string, string | TransitionConfig<Ctx> | Array<TransitionConfig<Ctx>>>;
+    entry?: ActionFn<Ctx> | ActionFn<Ctx>[];
+    exit?: ActionFn<Ctx> | ActionFn<Ctx>[];
+    history?: boolean;
+}
+interface HSMConfig<Ctx> {
+    initial: string;
+    context?: Ctx;
+    states: Record<string, StateConfig<Ctx>>;
+}
+type StateListener<Ctx> = (state: string, ctx: Ctx, event: HSMEvent) => void;
+
+interface StateNode<Ctx> {
+    id: string;
+    initial?: string;
+    children: Map<string, StateNode<Ctx>>;
+    parent?: StateNode<Ctx>;
+    transitions: Map<string, TransitionDef<Ctx>[]>;
+    entry: ActionFn<Ctx>[];
+    exit: ActionFn<Ctx>[];
+    history: boolean;
+    historyValue?: string;
+}
+interface TransitionDef<Ctx> {
+    target?: string;
+    guard?: GuardFn<Ctx>;
+    actions: ActionFn<Ctx>[];
+}
+declare class HSMError extends Error {
+    constructor(message: string);
+}
+declare class HSMService<Ctx> {
+    private _path;
+    private _ctx;
+    private readonly _root;
+    private readonly _listeners;
+    constructor(root: StateNode<Ctx>, initialPath: string[], ctx: Ctx);
+    /** Current state as dot-notation string, e.g. `"active.running"`. */
+    get state(): string;
+    /** Current context. */
+    get context(): Ctx;
+    /** Current state as array path, e.g. `["active", "running"]`. */
+    get stateValue(): string[];
+    /**
+     * Returns true if the current state matches the given prefix.
+     * `matches("active")` returns true for `"active.running"`.
+     */
+    matches(state: string): boolean;
+    /**
+     * Send an event to the machine.
+     * Returns this for chaining.
+     */
+    send(eventType: string, payload?: Record<string, unknown>): this;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: StateListener<Ctx>): () => void;
+    private _notify;
+    private _doTransition;
+}
+declare class HSM<Ctx> {
+    private readonly _root;
+    private readonly _initial;
+    private readonly _initialCtx;
+    constructor(config: HSMConfig<Ctx>);
+    private _resolveInitialPath;
+    /**
+     * Start the machine and run entry actions for the initial state path.
+     * Returns the running service.
+     */
+    start(): HSMService<Ctx>;
+}
+/**
+ * Create a hierarchical state machine.
+ *
+ * @example
+ * const machine = createHSM({
+ *   initial: 'idle',
+ *   context: { count: 0 },
+ *   states: {
+ *     idle: { on: { START: 'active' } },
+ *     active: {
+ *       initial: 'running',
+ *       states: {
+ *         running: { on: { PAUSE: 'active.paused', STOP: 'idle' } },
+ *         paused:  { on: { RESUME: 'active.running', STOP: 'idle' } },
+ *       },
+ *     },
+ *   },
+ * });
+ * const service = machine.start();
+ */
+declare function createHSM<Ctx = Record<string, unknown>>(config: HSMConfig<Ctx>): HSM<Ctx>;
+
+export { type ActionFn, type EventType, type GuardFn, HSM, type HSMConfig, HSMError, type HSMEvent, HSMService, type StateConfig, type StateId, type StateListener, type TransitionConfig, createHSM };

package/dist/index.js

@@ -0,0 +1,206 @@
+// src/hsm.ts
+function buildNode(id, config, parent) {
+  const node = {
+    id,
+    initial: config.initial,
+    children: /* @__PURE__ */ new Map(),
+    parent,
+    transitions: /* @__PURE__ */ new Map(),
+    entry: config.entry ? Array.isArray(config.entry) ? config.entry : [config.entry] : [],
+    exit: config.exit ? Array.isArray(config.exit) ? config.exit : [config.exit] : [],
+    history: config.history ?? false
+  };
+  if (config.states) {
+    for (const [childId, childConfig] of Object.entries(config.states)) {
+      node.children.set(childId, buildNode(childId, childConfig, node));
+    }
+  }
+  if (config.on) {
+    for (const [eventType, transConfig] of Object.entries(config.on)) {
+      const defs = parseTransitions(transConfig);
+      node.transitions.set(eventType, defs);
+    }
+  }
+  return node;
+}
+function parseTransitions(raw) {
+  if (typeof raw === "string") {
+    return [{ target: raw, actions: [] }];
+  }
+  if (Array.isArray(raw)) {
+    return raw.map((t) => ({
+      target: t.target,
+      guard: t.guard,
+      actions: t.actions ?? []
+    }));
+  }
+  return [{ target: raw.target, guard: raw.guard, actions: raw.actions ?? [] }];
+}
+function getNodeAtPath(root, path) {
+  let node = root;
+  for (const id of path) {
+    const child = node.children.get(id);
+    if (!child) throw new HSMError(`State "${id}" not found`);
+    node = child;
+  }
+  return node;
+}
+function resolvePath(target) {
+  return target.split(".");
+}
+function lcaDepth(a, b) {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+function expandToLeaf(root, path, ctx, event) {
+  let cur = getNodeAtPath(root, path);
+  let p = [...path];
+  while (cur.children.size > 0) {
+    if (!cur.initial) throw new HSMError(`Compound state "${p.join(".")}" has no initial substate`);
+    const childId = cur.history && cur.historyValue ? cur.historyValue : cur.initial;
+    cur = cur.children.get(childId);
+    for (const fn of cur.entry) ctx = fn(ctx, event) ?? ctx;
+    p.push(childId);
+  }
+  return { path: p, ctx };
+}
+var HSMError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HSMError";
+  }
+};
+var HSMService = class {
+  constructor(root, initialPath, ctx) {
+    this._listeners = /* @__PURE__ */ new Set();
+    this._root = root;
+    this._path = initialPath;
+    this._ctx = ctx;
+  }
+  /** Current state as dot-notation string, e.g. `"active.running"`. */
+  get state() {
+    return this._path.join(".");
+  }
+  /** Current context. */
+  get context() {
+    return this._ctx;
+  }
+  /** Current state as array path, e.g. `["active", "running"]`. */
+  get stateValue() {
+    return [...this._path];
+  }
+  /**
+   * Returns true if the current state matches the given prefix.
+   * `matches("active")` returns true for `"active.running"`.
+   */
+  matches(state) {
+    const parts = state.split(".");
+    return parts.every((part, i) => this._path[i] === part);
+  }
+  /**
+   * Send an event to the machine.
+   * Returns this for chaining.
+   */
+  send(eventType, payload = {}) {
+    const event = { type: eventType, ...payload };
+    for (let depth = this._path.length; depth >= 0; depth--) {
+      const nodePath = this._path.slice(0, depth);
+      const node = getNodeAtPath(this._root, nodePath);
+      const defs = node.transitions.get(eventType);
+      if (!defs) continue;
+      for (const def of defs) {
+        if (def.guard && !def.guard(this._ctx, event)) continue;
+        if (def.target === void 0) {
+          let ctx = this._ctx;
+          for (const fn of def.actions) ctx = fn(ctx, event) ?? ctx;
+          this._ctx = ctx;
+        } else {
+          const targetPath = resolvePath(def.target);
+          this._doTransition(this._path, nodePath, targetPath, def.actions, event);
+        }
+        this._notify(event);
+        return this;
+      }
+    }
+    return this;
+  }
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  subscribe(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+  _notify(event) {
+    for (const fn of this._listeners) fn(this.state, this._ctx, event);
+  }
+  _doTransition(currentPath, sourcePath, targetPath, transActions, event) {
+    const lca = lcaDepth(currentPath, targetPath);
+    let ctx = this._ctx;
+    for (let i = currentPath.length - 1; i >= lca; i--) {
+      const node = getNodeAtPath(this._root, currentPath.slice(0, i + 1));
+      for (const fn of node.exit) ctx = fn(ctx, event) ?? ctx;
+      if (i > 0) {
+        const parent = getNodeAtPath(this._root, currentPath.slice(0, i));
+        if (parent.history) parent.historyValue = currentPath[i];
+      }
+    }
+    for (const fn of transActions) ctx = fn(ctx, event) ?? ctx;
+    for (let i = lca; i < targetPath.length; i++) {
+      const node = getNodeAtPath(this._root, targetPath.slice(0, i + 1));
+      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;
+    }
+    this._ctx = ctx;
+    const { path, ctx: finalCtx } = expandToLeaf(this._root, targetPath, ctx, event);
+    this._path = path;
+    this._ctx = finalCtx;
+  }
+};
+var HSM = class {
+  constructor(config) {
+    this._root = buildNode("__root__", { states: config.states });
+    this._initialCtx = config.context ?? {};
+    this._initial = config.initial;
+  }
+  _resolveInitialPath(root, initial) {
+    const basePath = resolvePath(initial);
+    let p = [];
+    let node = root;
+    for (const id of basePath) {
+      const child = node.children.get(id);
+      if (!child) throw new HSMError(`Initial state "${id}" not found`);
+      node = child;
+      p.push(id);
+    }
+    while (node.children.size > 0) {
+      if (!node.initial) throw new HSMError(`Compound state "${p.join(".")}" has no initial substate`);
+      const childId = node.initial;
+      node = node.children.get(childId);
+      p.push(childId);
+    }
+    return p;
+  }
+  /**
+   * Start the machine and run entry actions for the initial state path.
+   * Returns the running service.
+   */
+  start() {
+    const initialPath = this._resolveInitialPath(this._root, this._initial);
+    let ctx = this._initialCtx;
+    const event = { type: "__init__" };
+    for (let i = 0; i < initialPath.length; i++) {
+      const node = getNodeAtPath(this._root, initialPath.slice(0, i + 1));
+      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;
+    }
+    return new HSMService(this._root, [...initialPath], ctx);
+  }
+};
+function createHSM(config) {
+  return new HSM(config);
+}
+export {
+  HSM,
+  HSMError,
+  HSMService,
+  createHSM
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hsm.ts"],"sourcesContent":["import type {\n  ActionFn,\n  GuardFn,\n  HSMConfig,\n  HSMEvent,\n  StateConfig,\n  StateId,\n  StateListener,\n  TransitionConfig,\n} from \"./types.js\";\n\n// ── Internal state node ──────────────────────────────────────────────────────\n\ninterface StateNode<Ctx> {\n  id: string;\n  initial?: string;\n  children: Map<string, StateNode<Ctx>>;\n  parent?: StateNode<Ctx>;\n  transitions: Map<string, TransitionDef<Ctx>[]>;\n  entry: ActionFn<Ctx>[];\n  exit: ActionFn<Ctx>[];\n  history: boolean;\n  historyValue?: string;\n}\n\ninterface TransitionDef<Ctx> {\n  target?: string;\n  guard?: GuardFn<Ctx>;\n  actions: ActionFn<Ctx>[];\n}\n\n// ── Builder ──────────────────────────────────────────────────────────────────\n\nfunction buildNode<Ctx>(\n  id: string,\n  config: StateConfig<Ctx>,\n  parent?: StateNode<Ctx>,\n): StateNode<Ctx> {\n  const node: StateNode<Ctx> = {\n    id,\n    initial: config.initial,\n    children: new Map(),\n    parent,\n    transitions: new Map(),\n    entry: config.entry\n      ? Array.isArray(config.entry) ? config.entry : [config.entry]\n      : [],\n    exit: config.exit\n      ? Array.isArray(config.exit) ? config.exit : [config.exit]\n      : [],\n    history: config.history ?? false,\n  };\n\n  // Build child states\n  if (config.states) {\n    for (const [childId, childConfig] of Object.entries(config.states)) {\n      node.children.set(childId, buildNode(childId, childConfig, node));\n    }\n  }\n\n  // Parse transitions\n  if (config.on) {\n    for (const [eventType, transConfig] of Object.entries(config.on)) {\n      const defs = parseTransitions(transConfig as string | TransitionConfig<Ctx> | Array<TransitionConfig<Ctx>>);\n      node.transitions.set(eventType, defs);\n    }\n  }\n\n  return node;\n}\n\nfunction parseTransitions<Ctx>(\n  raw: string | TransitionConfig<Ctx> | Array<TransitionConfig<Ctx>>,\n): TransitionDef<Ctx>[] {\n  if (typeof raw === \"string\") {\n    return [{ target: raw, actions: [] }];\n  }\n  if (Array.isArray(raw)) {\n    return raw.map((t) => ({\n      target: t.target,\n      guard: t.guard,\n      actions: t.actions ?? [],\n    }));\n  }\n  return [{ target: raw.target, guard: raw.guard, actions: raw.actions ?? [] }];\n}\n\n// ── Path utilities ───────────────────────────────────────────────────────────\n\nfunction getNodeAtPath<Ctx>(root: StateNode<Ctx>, path: string[]): StateNode<Ctx> {\n  let node = root;\n  for (const id of path) {\n    const child = node.children.get(id);\n    if (!child) throw new HSMError(`State \"${id}\" not found`);\n    node = child;\n  }\n  return node;\n}\n\n/** Resolve a dotted target string to a path array from the virtual root. */\nfunction resolvePath(target: string): string[] {\n  return target.split(\".\");\n}\n\n/** LCA index: length of longest common prefix of two paths. */\nfunction lcaDepth(a: string[], b: string[]): number {\n  let i = 0;\n  while (i < a.length && i < b.length && a[i] === b[i]) i++;\n  return i;\n}\n\n/** Enter compound state to leaf following initial/history chain. */\nfunction expandToLeaf<Ctx>(\n  root: StateNode<Ctx>,\n  path: string[],\n  ctx: Ctx,\n  event: HSMEvent,\n): { path: string[]; ctx: Ctx } {\n  let cur = getNodeAtPath(root, path);\n  let p = [...path];\n\n  while (cur.children.size > 0) {\n    if (!cur.initial) throw new HSMError(`Compound state \"${p.join(\".\")}\" has no initial substate`);\n    const childId = cur.history && cur.historyValue ? cur.historyValue : cur.initial;\n    cur = cur.children.get(childId)!;\n    for (const fn of cur.entry) ctx = fn(ctx, event) ?? ctx;\n    p.push(childId);\n  }\n\n  return { path: p, ctx };\n}\n\n// ── HSMService ───────────────────────────────────────────────────────────────\n\nexport class HSMError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"HSMError\";\n  }\n}\n\nexport class HSMService<Ctx> {\n  private _path: string[];\n  private _ctx: Ctx;\n  private readonly _root: StateNode<Ctx>;\n  private readonly _listeners = new Set<StateListener<Ctx>>();\n\n  constructor(root: StateNode<Ctx>, initialPath: string[], ctx: Ctx) {\n    this._root = root;\n    this._path = initialPath;\n    this._ctx = ctx;\n  }\n\n  /** Current state as dot-notation string, e.g. `\"active.running\"`. */\n  get state(): string {\n    return this._path.join(\".\");\n  }\n\n  /** Current context. */\n  get context(): Ctx {\n    return this._ctx;\n  }\n\n  /** Current state as array path, e.g. `[\"active\", \"running\"]`. */\n  get stateValue(): string[] {\n    return [...this._path];\n  }\n\n  /**\n   * Returns true if the current state matches the given prefix.\n   * `matches(\"active\")` returns true for `\"active.running\"`.\n   */\n  matches(state: string): boolean {\n    const parts = state.split(\".\");\n    return parts.every((part, i) => this._path[i] === part);\n  }\n\n  /**\n   * Send an event to the machine.\n   * Returns this for chaining.\n   */\n  send(eventType: string, payload: Record<string, unknown> = {}): this {\n    const event: HSMEvent = { type: eventType, ...payload };\n\n    // Walk up from current leaf to root looking for applicable transition\n    for (let depth = this._path.length; depth >= 0; depth--) {\n      const nodePath = this._path.slice(0, depth);\n      const node = getNodeAtPath(this._root, nodePath);\n      const defs = node.transitions.get(eventType);\n      if (!defs) continue;\n\n      for (const def of defs) {\n        if (def.guard && !def.guard(this._ctx, event)) continue;\n\n        if (def.target === undefined) {\n          // Internal transition — run actions, no exit/entry\n          let ctx = this._ctx;\n          for (const fn of def.actions) ctx = fn(ctx, event) ?? ctx;\n          this._ctx = ctx;\n        } else {\n          const targetPath = resolvePath(def.target);\n          this._doTransition(this._path, nodePath, targetPath, def.actions, event);\n        }\n\n        this._notify(event);\n        return this;\n      }\n    }\n\n    return this;\n  }\n\n  /** Subscribe to state changes. Returns an unsubscribe function. */\n  subscribe(listener: StateListener<Ctx>): () => void {\n    this._listeners.add(listener);\n    return () => this._listeners.delete(listener);\n  }\n\n  private _notify(event: HSMEvent): void {\n    for (const fn of this._listeners) fn(this.state, this._ctx, event);\n  }\n\n  private _doTransition(\n    currentPath: string[],\n    sourcePath: string[],\n    targetPath: string[],\n    transActions: ActionFn<Ctx>[],\n    event: HSMEvent,\n  ): void {\n    const lca = lcaDepth(currentPath, targetPath);\n    let ctx = this._ctx;\n\n    // Exit from current leaf up to (not including) LCA\n    for (let i = currentPath.length - 1; i >= lca; i--) {\n      const node = getNodeAtPath(this._root, currentPath.slice(0, i + 1));\n      for (const fn of node.exit) ctx = fn(ctx, event) ?? ctx;\n\n      // Record history in parent\n      if (i > 0) {\n        const parent = getNodeAtPath(this._root, currentPath.slice(0, i));\n        if (parent.history) parent.historyValue = currentPath[i];\n      }\n    }\n\n    // Transition actions\n    for (const fn of transActions) ctx = fn(ctx, event) ?? ctx;\n\n    // Entry from LCA down to target\n    for (let i = lca; i < targetPath.length; i++) {\n      const node = getNodeAtPath(this._root, targetPath.slice(0, i + 1));\n      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;\n    }\n\n    this._ctx = ctx;\n\n    // Expand target compound state to leaf\n    const { path, ctx: finalCtx } = expandToLeaf(this._root, targetPath, ctx, event);\n    this._path = path;\n    this._ctx = finalCtx;\n  }\n}\n\n// ── HSM factory ───────────────────────────────────────────────────────────────\n\nexport class HSM<Ctx> {\n  private readonly _root: StateNode<Ctx>;\n  private readonly _initial: string;\n  private readonly _initialCtx: Ctx;\n\n  constructor(config: HSMConfig<Ctx>) {\n    this._root = buildNode<Ctx>(\"__root__\", { states: config.states } as StateConfig<Ctx>);\n    this._initialCtx = (config.context ?? ({} as unknown as Ctx));\n    this._initial = config.initial;\n  }\n\n  private _resolveInitialPath(root: StateNode<Ctx>, initial: string): string[] {\n    const basePath = resolvePath(initial);\n    let p: string[] = [];\n    let node = root;\n    for (const id of basePath) {\n      const child = node.children.get(id);\n      if (!child) throw new HSMError(`Initial state \"${id}\" not found`);\n      node = child;\n      p.push(id);\n    }\n    // Expand to leaf via initial chain\n    while (node.children.size > 0) {\n      if (!node.initial) throw new HSMError(`Compound state \"${p.join(\".\")}\" has no initial substate`);\n      const childId = node.initial;\n      node = node.children.get(childId)!;\n      p.push(childId);\n    }\n    return p;\n  }\n\n  /**\n   * Start the machine and run entry actions for the initial state path.\n   * Returns the running service.\n   */\n  start(): HSMService<Ctx> {\n    const initialPath = this._resolveInitialPath(this._root, this._initial);\n    let ctx = this._initialCtx;\n    const event: HSMEvent = { type: \"__init__\" };\n\n    // Run entry actions down to initial leaf\n    for (let i = 0; i < initialPath.length; i++) {\n      const node = getNodeAtPath(this._root, initialPath.slice(0, i + 1));\n      for (const fn of node.entry) ctx = fn(ctx, event) ?? ctx;\n    }\n\n    return new HSMService<Ctx>(this._root, [...initialPath], ctx);\n  }\n}\n\n/**\n * Create a hierarchical state machine.\n *\n * @example\n * const machine = createHSM({\n *   initial: 'idle',\n *   context: { count: 0 },\n *   states: {\n *     idle: { on: { START: 'active' } },\n *     active: {\n *       initial: 'running',\n *       states: {\n *         running: { on: { PAUSE: 'active.paused', STOP: 'idle' } },\n *         paused:  { on: { RESUME: 'active.running', STOP: 'idle' } },\n *       },\n *     },\n *   },\n * });\n * const service = machine.start();\n */\nexport function createHSM<Ctx = Record<string, unknown>>(config: HSMConfig<Ctx>): HSM<Ctx> {\n  return new HSM(config);\n}\n"],"mappings":";AAiCA,SAAS,UACP,IACA,QACA,QACgB;AAChB,QAAM,OAAuB;AAAA,IAC3B;AAAA,IACA,SAAS,OAAO;AAAA,IAChB,UAAU,oBAAI,IAAI;AAAA,IAClB;AAAA,IACA,aAAa,oBAAI,IAAI;AAAA,IACrB,OAAO,OAAO,QACV,MAAM,QAAQ,OAAO,KAAK,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,IAC1D,CAAC;AAAA,IACL,MAAM,OAAO,OACT,MAAM,QAAQ,OAAO,IAAI,IAAI,OAAO,OAAO,CAAC,OAAO,IAAI,IACvD,CAAC;AAAA,IACL,SAAS,OAAO,WAAW;AAAA,EAC7B;AAGA,MAAI,OAAO,QAAQ;AACjB,eAAW,CAAC,SAAS,WAAW,KAAK,OAAO,QAAQ,OAAO,MAAM,GAAG;AAClE,WAAK,SAAS,IAAI,SAAS,UAAU,SAAS,aAAa,IAAI,CAAC;AAAA,IAClE;AAAA,EACF;AAGA,MAAI,OAAO,IAAI;AACb,eAAW,CAAC,WAAW,WAAW,KAAK,OAAO,QAAQ,OAAO,EAAE,GAAG;AAChE,YAAM,OAAO,iBAAiB,WAA4E;AAC1G,WAAK,YAAY,IAAI,WAAW,IAAI;AAAA,IACtC;AAAA,EACF;AAEA,SAAO;AACT;AAEA,SAAS,iBACP,KACsB;AACtB,MAAI,OAAO,QAAQ,UAAU;AAC3B,WAAO,CAAC,EAAE,QAAQ,KAAK,SAAS,CAAC,EAAE,CAAC;AAAA,EACtC;AACA,MAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,WAAO,IAAI,IAAI,CAAC,OAAO;AAAA,MACrB,QAAQ,EAAE;AAAA,MACV,OAAO,EAAE;AAAA,MACT,SAAS,EAAE,WAAW,CAAC;AAAA,IACzB,EAAE;AAAA,EACJ;AACA,SAAO,CAAC,EAAE,QAAQ,IAAI,QAAQ,OAAO,IAAI,OAAO,SAAS,IAAI,WAAW,CAAC,EAAE,CAAC;AAC9E;AAIA,SAAS,cAAmB,MAAsB,MAAgC;AAChF,MAAI,OAAO;AACX,aAAW,MAAM,MAAM;AACrB,UAAM,QAAQ,KAAK,SAAS,IAAI,EAAE;AAClC,QAAI,CAAC,MAAO,OAAM,IAAI,SAAS,UAAU,EAAE,aAAa;AACxD,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAGA,SAAS,YAAY,QAA0B;AAC7C,SAAO,OAAO,MAAM,GAAG;AACzB;AAGA,SAAS,SAAS,GAAa,GAAqB;AAClD,MAAI,IAAI;AACR,SAAO,IAAI,EAAE,UAAU,IAAI,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,EAAG;AACtD,SAAO;AACT;AAGA,SAAS,aACP,MACA,MACA,KACA,OAC8B;AAC9B,MAAI,MAAM,cAAc,MAAM,IAAI;AAClC,MAAI,IAAI,CAAC,GAAG,IAAI;AAEhB,SAAO,IAAI,SAAS,OAAO,GAAG;AAC5B,QAAI,CAAC,IAAI,QAAS,OAAM,IAAI,SAAS,mBAAmB,EAAE,KAAK,GAAG,CAAC,2BAA2B;AAC9F,UAAM,UAAU,IAAI,WAAW,IAAI,eAAe,IAAI,eAAe,IAAI;AACzE,UAAM,IAAI,SAAS,IAAI,OAAO;AAC9B,eAAW,MAAM,IAAI,MAAO,OAAM,GAAG,KAAK,KAAK,KAAK;AACpD,MAAE,KAAK,OAAO;AAAA,EAChB;AAEA,SAAO,EAAE,MAAM,GAAG,IAAI;AACxB;AAIO,IAAM,WAAN,cAAuB,MAAM;AAAA,EAClC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,aAAN,MAAsB;AAAA,EAM3B,YAAY,MAAsB,aAAuB,KAAU;AAFnE,SAAiB,aAAa,oBAAI,IAAwB;AAGxD,SAAK,QAAQ;AACb,SAAK,QAAQ;AACb,SAAK,OAAO;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAgB;AAClB,WAAO,KAAK,MAAM,KAAK,GAAG;AAAA,EAC5B;AAAA;AAAA,EAGA,IAAI,UAAe;AACjB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,aAAuB;AACzB,WAAO,CAAC,GAAG,KAAK,KAAK;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAQ,OAAwB;AAC9B,UAAM,QAAQ,MAAM,MAAM,GAAG;AAC7B,WAAO,MAAM,MAAM,CAAC,MAAM,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK,WAAmB,UAAmC,CAAC,GAAS;AACnE,UAAM,QAAkB,EAAE,MAAM,WAAW,GAAG,QAAQ;AAGtD,aAAS,QAAQ,KAAK,MAAM,QAAQ,SAAS,GAAG,SAAS;AACvD,YAAM,WAAW,KAAK,MAAM,MAAM,GAAG,KAAK;AAC1C,YAAM,OAAO,cAAc,KAAK,OAAO,QAAQ;AAC/C,YAAM,OAAO,KAAK,YAAY,IAAI,SAAS;AAC3C,UAAI,CAAC,KAAM;AAEX,iBAAW,OAAO,MAAM;AACtB,YAAI,IAAI,SAAS,CAAC,IAAI,MAAM,KAAK,MAAM,KAAK,EAAG;AAE/C,YAAI,IAAI,WAAW,QAAW;AAE5B,cAAI,MAAM,KAAK;AACf,qBAAW,MAAM,IAAI,QAAS,OAAM,GAAG,KAAK,KAAK,KAAK;AACtD,eAAK,OAAO;AAAA,QACd,OAAO;AACL,gBAAM,aAAa,YAAY,IAAI,MAAM;AACzC,eAAK,cAAc,KAAK,OAAO,UAAU,YAAY,IAAI,SAAS,KAAK;AAAA,QACzE;AAEA,aAAK,QAAQ,KAAK;AAClB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,UAAU,UAA0C;AAClD,SAAK,WAAW,IAAI,QAAQ;AAC5B,WAAO,MAAM,KAAK,WAAW,OAAO,QAAQ;AAAA,EAC9C;AAAA,EAEQ,QAAQ,OAAuB;AACrC,eAAW,MAAM,KAAK,WAAY,IAAG,KAAK,OAAO,KAAK,MAAM,KAAK;AAAA,EACnE;AAAA,EAEQ,cACN,aACA,YACA,YACA,cACA,OACM;AACN,UAAM,MAAM,SAAS,aAAa,UAAU;AAC5C,QAAI,MAAM,KAAK;AAGf,aAAS,IAAI,YAAY,SAAS,GAAG,KAAK,KAAK,KAAK;AAClD,YAAM,OAAO,cAAc,KAAK,OAAO,YAAY,MAAM,GAAG,IAAI,CAAC,CAAC;AAClE,iBAAW,MAAM,KAAK,KAAM,OAAM,GAAG,KAAK,KAAK,KAAK;AAGpD,UAAI,IAAI,GAAG;AACT,cAAM,SAAS,cAAc,KAAK,OAAO,YAAY,MAAM,GAAG,CAAC,CAAC;AAChE,YAAI,OAAO,QAAS,QAAO,eAAe,YAAY,CAAC;AAAA,MACzD;AAAA,IACF;AAGA,eAAW,MAAM,aAAc,OAAM,GAAG,KAAK,KAAK,KAAK;AAGvD,aAAS,IAAI,KAAK,IAAI,WAAW,QAAQ,KAAK;AAC5C,YAAM,OAAO,cAAc,KAAK,OAAO,WAAW,MAAM,GAAG,IAAI,CAAC,CAAC;AACjE,iBAAW,MAAM,KAAK,MAAO,OAAM,GAAG,KAAK,KAAK,KAAK;AAAA,IACvD;AAEA,SAAK,OAAO;AAGZ,UAAM,EAAE,MAAM,KAAK,SAAS,IAAI,aAAa,KAAK,OAAO,YAAY,KAAK,KAAK;AAC/E,SAAK,QAAQ;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAIO,IAAM,MAAN,MAAe;AAAA,EAKpB,YAAY,QAAwB;AAClC,SAAK,QAAQ,UAAe,YAAY,EAAE,QAAQ,OAAO,OAAO,CAAqB;AACrF,SAAK,cAAe,OAAO,WAAY,CAAC;AACxC,SAAK,WAAW,OAAO;AAAA,EACzB;AAAA,EAEQ,oBAAoB,MAAsB,SAA2B;AAC3E,UAAM,WAAW,YAAY,OAAO;AACpC,QAAI,IAAc,CAAC;AACnB,QAAI,OAAO;AACX,eAAW,MAAM,UAAU;AACzB,YAAM,QAAQ,KAAK,SAAS,IAAI,EAAE;AAClC,UAAI,CAAC,MAAO,OAAM,IAAI,SAAS,kBAAkB,EAAE,aAAa;AAChE,aAAO;AACP,QAAE,KAAK,EAAE;AAAA,IACX;AAEA,WAAO,KAAK,SAAS,OAAO,GAAG;AAC7B,UAAI,CAAC,KAAK,QAAS,OAAM,IAAI,SAAS,mBAAmB,EAAE,KAAK,GAAG,CAAC,2BAA2B;AAC/F,YAAM,UAAU,KAAK;AACrB,aAAO,KAAK,SAAS,IAAI,OAAO;AAChC,QAAE,KAAK,OAAO;AAAA,IAChB;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAyB;AACvB,UAAM,cAAc,KAAK,oBAAoB,KAAK,OAAO,KAAK,QAAQ;AACtE,QAAI,MAAM,KAAK;AACf,UAAM,QAAkB,EAAE,MAAM,WAAW;AAG3C,aAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,YAAM,OAAO,cAAc,KAAK,OAAO,YAAY,MAAM,GAAG,IAAI,CAAC,CAAC;AAClE,iBAAW,MAAM,KAAK,MAAO,OAAM,GAAG,KAAK,KAAK,KAAK;AAAA,IACvD;AAEA,WAAO,IAAI,WAAgB,KAAK,OAAO,CAAC,GAAG,WAAW,GAAG,GAAG;AAAA,EAC9D;AACF;AAsBO,SAAS,UAAyC,QAAkC;AACzF,SAAO,IAAI,IAAI,MAAM;AACvB;","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@billdaddy/hsmkit",
+  "version": "0.1.0",
+  "description": "Zero-dependency TypeScript hierarchical state machine (statecharts): compound states, entry/exit actions, guards, shallow history, internal transitions. Like Python pytransitions / C# Stateless / Ruby AASM.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --forceExit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "state-machine",
+    "hsm",
+    "statechart",
+    "hierarchical",
+    "compound-state",
+    "history-state",
+    "entry-exit",
+    "guards",
+    "typescript",
+    "zero-dependencies"
+  ],
+  "author": "trananhtung",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trananhtung/hsmkit.git"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}