@statewalker/fsm 0.36.0 → 0.38.0

package/src/core/fsm-state-descriptor.ts

@@ -5,10 +5,24 @@ import {
   STATE_FINAL,
 } from "./fsm-state-config.ts";
 
+/**
+ * The *compiled* form of an `FsmStateConfig` subtree.
+ *
+ * Resolving a transition happens on every event, so the flat `[from, event, to]`
+ * tuple list is pre-indexed once into nested maps for O(1) lookup, and the
+ * wildcard-fallback order is applied here rather than re-derived on each dispatch.
+ * The shape is `transitions[from][event] = to` plus a `states` map of child
+ * descriptors. `FsmProcess` builds one from your config in its constructor; you
+ * rarely construct a descriptor directly.
+ */
 export class FsmStateDescriptor {
   transitions: Record<string, Record<string, string>> = {};
   states: Record<string, FsmStateDescriptor> = {};
 
+  /**
+   * Recursively compile a config (and its nested `states`) into descriptors,
+   * turning the tuple list into the indexed `transitions` map.
+   */
   static build(config: FsmStateConfig) {
     const descriptor = new FsmStateDescriptor();
     for (const [from, event, to] of config.transitions || []) {
@@ -27,6 +41,13 @@ export class FsmStateDescriptor {
     return descriptor;
   }
 
+  /**
+   * Resolve the target state for a `(stateKey, eventKey)` pair. Tries the most
+   * specific match first, then falls back through the wildcards —
+   * `(state, event)` → `(*, event)` → `(state, *)` → `(*, *)` — and returns
+   * `STATE_FINAL` if nothing matches, so an unmatched event exits the state rather
+   * than silently doing nothing.
+   */
   getTargetStateKey(stateKey: string, eventKey: string) {
     const pairs = [
       [stateKey, eventKey],

package/src/core/fsm-state.ts

@@ -2,25 +2,41 @@ import { bindMethods, FsmBaseClass } from "./fsm-base-class.ts";
 import type { FsmProcess } from "./fsm-process.ts";
 import type { FsmStateDescriptor } from "./fsm-state-descriptor.ts";
 
+/** Serialized form of a single state: its `key` plus the `data` bag its `dump` hooks filled. */
 export type FsmStateDump = Record<string, unknown> & {
   key: string;
   data: Record<string, unknown>;
 };
+/** An `onEnter` / `onExit` callback; receives the state it fired on. */
 export type FsmStateHandler = (
   state: FsmState,
   ...args: unknown[]
 ) => void | Promise<void>;
 
+/** A `dump` / `restore` callback; reads or fills the mutable per-state `data` bag. */
 export type FsmStateDumpHandler = (
   state: FsmState,
   dump: FsmStateDump,
 ) => void | Promise<void>;
 
+/** An `onStateError` callback; receives the error thrown by another handler on this state. */
 export type FsmStateErrorHandler = (
   state: FsmState,
   error: unknown,
 ) => void | Promise<void>;
 
+/**
+ * One live node in a running machine's active-state stack.
+ *
+ * A state needs a place to attach behaviour and record data while it is active.
+ * `FsmState` is that handle — created by the engine each time a state is entered,
+ * discarded when it exits — so handlers can capture per-activation closures instead
+ * of sharing mutable machine-wide state. It offers lifecycle hooks `onEnter` /
+ * `onExit` / `onStateError`, serialization hooks `dump` / `restore`, and the tree
+ * links `key` / `parent` / `descriptor`; every hook method returns a disposer.
+ * Attach hooks from within `FsmProcess.onStateCreate((state) => …)`, or let
+ * `startProcess` install them for you from a `load` callback.
+ */
 export class FsmState extends FsmBaseClass {
   process: FsmProcess;
   key: string;
@@ -38,44 +54,29 @@ export class FsmState extends FsmBaseClass {
     this.key = key;
     this.parent = parent;
     this.descriptor = descriptor;
-    bindMethods(
-      this,
-      "onEnter",
-      "onExit",
-      "dump",
-      "restore",
-      "useData",
-      "onStateError",
-    );
+    bindMethods(this, "onEnter", "onExit", "dump", "restore", "onStateError");
   }
 
+  /** Run when this state is entered. */
   onEnter(handler: FsmStateHandler) {
     return this._addHandler("onEnter", handler, true);
   }
+  /** Run when this state exits — registered inner-first so unwinding is inner-to-outer. */
   onExit(handler: FsmStateHandler) {
     return this._addHandler("onExit", handler, false);
   }
+  /** Handle an error thrown by another handler on this state (also bubbles to the process). */
   onStateError(handler: FsmStateErrorHandler) {
     return this._addHandler("onStateError", handler);
   }
+  /** Contribute to this state's snapshot: fill `dump.data` when the process is dumped. */
   dump(handler: FsmStateDumpHandler) {
     return this._addHandler("dump", handler, true);
   }
+  /** Rehydrate from this state's snapshot: read `dump.data` when the process is restored. */
   restore(handler: FsmStateDumpHandler) {
     return this._addHandler("restore", handler, true);
   }
-  getData<T>(key: string, recursive: boolean = true): T | undefined {
-    return (
-      (this.data[key] as T) ??
-      (recursive ? this.parent?.getData<T>(key, recursive) : undefined)
-    );
-  }
-  useData<T>(key: string) {
-    return [
-      (recursive: boolean = true) => this.getData<T>(key, recursive),
-      (value: T) => this.setData(key, value),
-    ];
-  }
 
   async _handleError(error: Error | unknown) {
     await this._runHandler("onStateError", this, error);

package/src/core/fsm-transitions.ts

@@ -0,0 +1,72 @@
+import type { FsmProcess } from "./fsm-process.ts";
+import type { FsmState } from "./fsm-state.ts";
+import type { FsmStateDescriptor } from "./fsm-state-descriptor.ts";
+
+// ---------------------------------------------------------------------------
+// Transition introspection — read-only queries over the state/transition graph
+// ---------------------------------------------------------------------------
+
+/**
+ * List the transitions currently reachable from `state` — for a UI or viewer that
+ * needs to know which events can fire right now (e.g. to render only the enabled
+ * buttons). Collects `[from, event, to]` tuples by walking up the parent chain; the
+ * nearest state's rule for an event wins, so an outer fallback is masked by an inner
+ * override. The returned tuples are ordered outer→inner (root first).
+ */
+export function getStateTransitions(
+  state?: FsmState,
+): [from: string, event: string, to: string][] {
+  const result: [from: string, event: string, to: string][] = [];
+  const index: Record<string, boolean> = {};
+  if (state) {
+    let prevStateKey = state.key;
+    for (let parent = state.parent; parent; parent = parent.parent) {
+      if (!parent.descriptor) continue;
+      result.push(
+        ...getTransitionsFromDescriptor(parent.descriptor, prevStateKey, index),
+      );
+      prevStateKey = parent.key;
+    }
+  }
+  return result.reverse();
+}
+
+function getTransitionsFromDescriptor(
+  descriptor: FsmStateDescriptor,
+  prevStateKey: string,
+  index: Record<string, boolean>,
+): [from: string, event: string, to: string][] {
+  const result: [from: string, event: string, to: string][] = [];
+  const prevStateKeys = [prevStateKey, "*"];
+  for (const prevKey of prevStateKeys) {
+    const targets = descriptor.transitions[prevKey];
+    if (targets) {
+      for (const [event, target] of Object.entries(targets)) {
+        if (index[event]) continue;
+        // Mark the event seen regardless of target — an inner exit-to-final
+        // (`to === ""`, a falsy target) must still mask an outer rule for the
+        // same event, matching what `dispatch` actually resolves.
+        index[event] = true;
+        result.push([prevStateKey, event, target]);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Guard: would `event` trigger any transition in the process's current state? Used
+ * to avoid dispatching dead events — the runner calls it before `dispatch`, and
+ * consumers use it to enable/disable controls. Returns `true` iff `event` appears
+ * among `getStateTransitions(process.state)`.
+ */
+export function isStateTransitionEnabled(
+  process: FsmProcess,
+  event: string,
+): boolean {
+  const transitions = getStateTransitions(process.state);
+  for (const [, ev] of transitions) {
+    if (ev === event) return true;
+  }
+  return false;
+}

package/src/core/index.ts

@@ -1,5 +1,6 @@
+export * from "./fsm-base-class.ts";
 export * from "./fsm-process.ts";
 export * from "./fsm-state.ts";
 export * from "./fsm-state-config.ts";
 export * from "./fsm-state-descriptor.ts";
-export * from "./new-fsm-process.ts";
+export * from "./fsm-transitions.ts";

package/src/index.ts

@@ -1,6 +1,3 @@
 export * from "./core/index.ts";
-export * from "./orchestrator/index.ts";
-export * from "./utils/index.ts";
-
-import { startNodeProcesses } from "./orchestrator/start-node-processes.ts";
-export default startNodeProcesses;
+export * from "./start-process.ts";
+export * from "./trace/index.ts";

package/src/start-process.ts

@@ -0,0 +1,185 @@
+import { FsmProcess, type FsmProcessDump } from "./core/fsm-process.ts";
+import type { FsmState } from "./core/fsm-state.ts";
+import type { FsmStateConfig } from "./core/fsm-state-config.ts";
+import { isStateTransitionEnabled } from "./core/fsm-transitions.ts";
+
+/**
+ * Per-state behaviour contract used by `startProcess`. One function shape expresses
+ * what to do while in a state, and its *return value* wires up the rest, so a state's
+ * setup and teardown live together. The handler runs on entry with the shared
+ * `context` and may return:
+ * - nothing — no teardown;
+ * - a cleanup `function` — registered as this state's `onExit`;
+ * - an async/sync generator — run concurrently, each yielded string dispatched back
+ *   into the machine (self-driving/reactive states), auto-`return()`ed on exit.
+ */
+export type StageHandler<C = Record<string, unknown>> = (
+  context: C,
+) =>
+  | void
+  | (() => void | Promise<void>)
+  | Promise<void | (() => void | Promise<void>)>
+  | AsyncGenerator<string, void, unknown>
+  | Generator<string, void, unknown>;
+
+/**
+ * The caller's remote control returned by `startProcess`: stop the machine and
+ * snapshot/rehydrate it without holding a reference to the underlying `FsmProcess`.
+ */
+export interface ProcessHandle {
+  shutdown(): Promise<void>;
+  dump(...args: unknown[]): Promise<FsmProcessDump>;
+  restore(dump: FsmProcessDump, ...args: unknown[]): Promise<void>;
+}
+
+// Context keys under which `startProcess` binds the machine into the shared context
+// object. Why via context (not closures): handlers reach the running machine
+// uniformly — `(ctx[KEY_DISPATCH])(event)` — regardless of where they are defined.
+/** Context key: `(event) => Promise<void>` that dispatches an event (guarded). */
+export const KEY_DISPATCH = "fsm:dispatch";
+/** Context key: `() => Promise<void>` that shuts the machine down. */
+export const KEY_TERMINATE = "fsm:terminate";
+/** Context key: the current state-key stack (root→leaf), refreshed on every transition. */
+export const KEY_STATES = "fsm:states";
+/** Context key: the last dispatched event. */
+export const KEY_EVENT = "fsm:event";
+
+// ---------------------------------------------------------------------------
+// Generator detection
+// ---------------------------------------------------------------------------
+
+function isGenerator(
+  value: unknown,
+): value is
+  | Generator<string, void, unknown>
+  | AsyncGenerator<string, void, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "next" in value &&
+    typeof (value as { next: unknown }).next === "function"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// startProcess (also exported as startFsmProcess for backward compat)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ergonomic runner: build a machine, attach behaviour via one `load` callback, and
+ * bind the machine into `context`.
+ *
+ * Doing this by hand (`new FsmProcess` + `onStateCreate` + `onEnter` + a loader +
+ * context wiring) is boilerplate every consumer repeats, so `startProcess` does it
+ * once — most callers use this instead of the raw engine. It creates the process; on
+ * each state entry calls `load(stateKey, event)` and installs the returned
+ * `StageHandler`s (their return values become `onExit` cleanups or event-yielding
+ * generators — see `StageHandler`); binds `KEY_DISPATCH` / `KEY_TERMINATE` /
+ * `KEY_STATES` / `KEY_EVENT` into `context`; dispatches `startEvent` to enter the
+ * initial state; and returns a `ProcessHandle`.
+ *
+ * @param context shared object handlers read/write and the machine is bound into
+ * @param config the declarative machine definition
+ * @param load returns the handler(s) to run for a given `(stateKey, event)`
+ * @param startEvent initial event (default `""`, the eventless start)
+ */
+export async function startProcess<C = unknown>(
+  context: C,
+  config: FsmStateConfig,
+  load: (
+    state: string,
+    event: string | undefined,
+  ) => StageHandler<C>[] | Promise<StageHandler<C>[]>,
+  startEvent = "",
+): Promise<ProcessHandle> {
+  let terminated = false;
+  const ctx = context as Record<string, unknown>;
+  const process = new FsmProcess(config);
+  const statesStack: string[] = [];
+
+  process.onStateCreate((state: FsmState) => {
+    state.onEnter(async () => {
+      statesStack.push(state.key);
+      ctx[KEY_STATES] = [...statesStack];
+      ctx[KEY_EVENT] = process.event;
+
+      const modules = (await load(state.key, process.event)) ?? [];
+      for (const module of Array.isArray(modules) ? modules : [modules]) {
+        const result = await module?.(context);
+        if (isGenerator(result)) {
+          let stateExited = false;
+          state.onExit(() => {
+            stateExited = true;
+            result.return?.(undefined as never);
+          });
+          (async () => {
+            try {
+              for await (const event of result) {
+                if (stateExited || terminated) break;
+                await dispatch(event);
+                if (stateExited || terminated) break;
+              }
+            } catch (error) {
+              // A generator `return()` during state exit / termination throws an
+              // abort we intentionally swallow; a genuine error thrown by the
+              // generator body must surface through the state's error handling
+              // rather than vanish.
+              if (!stateExited && !terminated) await state._handleError(error);
+            }
+          })();
+        } else if (typeof result === "function") {
+          state.onExit(result as () => void | Promise<void>);
+        }
+      }
+    });
+    state.onExit(() => {
+      statesStack.pop();
+      ctx[KEY_STATES] = [...statesStack];
+      ctx[KEY_EVENT] = process.event;
+    });
+  });
+
+  async function dispatch(event: string): Promise<void> {
+    if (event !== undefined && isStateTransitionEnabled(process, event)) {
+      await process.dispatch(event);
+    }
+  }
+  async function terminate(): Promise<void> {
+    terminated = true;
+    await process.shutdown();
+  }
+
+  async function dumpProcess(...args: unknown[]): Promise<FsmProcessDump> {
+    return process.dump(...args);
+  }
+
+  async function restoreProcess(
+    dumpData: FsmProcessDump,
+    ...args: unknown[]
+  ): Promise<void> {
+    statesStack.length = 0;
+    terminated = false;
+    await process.restore(dumpData, ...args);
+    for (
+      let state: FsmState | undefined = process.state;
+      state;
+      state = state.parent
+    ) {
+      statesStack.unshift(state.key);
+    }
+    ctx[KEY_STATES] = [...statesStack];
+    ctx[KEY_EVENT] = process.event;
+  }
+
+  ctx[KEY_DISPATCH] = dispatch;
+  ctx[KEY_TERMINATE] = terminate;
+  await process.dispatch(startEvent);
+  return {
+    shutdown: terminate,
+    dump: dumpProcess,
+    restore: restoreProcess,
+  };
+}
+
+/** Permanent equal alias of {@link startProcess} — the name existing consumers import. */
+export const startFsmProcess = startProcess;

package/src/trace/index.ts

@@ -0,0 +1,2 @@
+export * from "./printer.ts";
+export * from "./tracer.ts";

package/src/trace/printer.ts

@@ -0,0 +1,62 @@
+import type { FsmProcess } from "../core/fsm-process.ts";
+
+/** A sink for trace output — anything shaped like `console.log`. */
+export type Printer = (...args: unknown[]) => void;
+/**
+ * Tuning for a `Printer`.
+ * - `prefix` — string prepended to every line (e.g. a process tag).
+ * - `print` — the underlying sink (defaults to `console.log`).
+ * - `lineNumbers` — prepend an incrementing `[n]` counter.
+ */
+export type PrinterConfig = {
+  prefix?: string;
+  print?: (...args: unknown[]) => void;
+  lineNumbers?: boolean;
+};
+
+const printerStore = new WeakMap<object, Printer>();
+
+/**
+ * Build a `Printer` bound to `process` that indents each line by the current state
+ * nesting depth (two spaces per level), so log output visually mirrors the state
+ * tree — hierarchical indentation makes enter/exit traces readable at a glance.
+ */
+export function preparePrinter(
+  process: FsmProcess,
+  { prefix = "", print = console.log, lineNumbers = false }: PrinterConfig,
+): Printer {
+  let lineCounter = 0;
+  const shift = () => {
+    let prefix = "";
+    for (let s = process.state?.parent; s; s = s.parent) {
+      prefix += "  ";
+    }
+    return prefix;
+  };
+  const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;
+  const printer = (...args: unknown[]) => print(prefix, getPrefix(), ...args);
+  return printer;
+}
+
+/**
+ * Attach a printer to `process` (stored in a weak map so it is GC'd with the
+ * process). Handlers/tracers then reach it via {@link getProcessPrinter} /
+ * {@link getPrinter} rather than threading a logger through every call.
+ */
+export function setProcessPrinter(
+  process: FsmProcess,
+  config: PrinterConfig = {},
+) {
+  const printer = preparePrinter(process, config);
+  printerStore.set(process, printer);
+}
+
+/** The printer attached to `process`, or `console.log` if none was set. */
+export function getProcessPrinter(process: FsmProcess): Printer {
+  return printerStore.get(process) || console.log;
+}
+
+/** The printer for a state — its own if set, else its process's (see {@link getProcessPrinter}). */
+export function getPrinter(state: { process: FsmProcess }): Printer {
+  return printerStore.get(state) || getProcessPrinter(state.process);
+}

package/src/{utils → trace}/tracer.ts

@@ -2,12 +2,23 @@ import type { FsmProcess } from "../core/fsm-process.ts";
 import type { FsmState } from "../core/fsm-state.ts";
 import { getPrinter, type Printer } from "./printer.ts";
 
+/**
+ * Trace every state of `process`: as each state is created, attach a state tracer —
+ * so you can watch the machine move as a readable stream of enter/exit markers
+ * without editing any handler. Hooks `onStateCreate` and delegates to
+ * {@link setStateTracer}; pass a `print` sink to override the process printer.
+ */
 export function setProcessTracer(process: FsmProcess, print?: Printer) {
-  return process.onStateCreate((state) => {
+  return process.onStateCreate((state: FsmState) => {
     setStateTracer(state, print);
   });
 }
 
+/**
+ * Trace one state's lifecycle: emit `<key event="…">` on enter and `</key>` on exit
+ * (XML-like, so nested states read as nested tags). Falls back to the state's
+ * printer ({@link getPrinter}) when no `print` sink is given.
+ */
 export function setStateTracer(state: FsmState, print?: Printer) {
   state.onEnter(() => {
     const printLine = print || getPrinter(state);

package/CHANGELOG.md

@@ -1,59 +0,0 @@
-# @statewalker/fsm
-
-## 0.16.0
-
-### Minor Changes
-
-- Fix logical bug in transitions loading
-
-## 0.15.2
-
-### Patch Changes
-
-- Update rollup and dependencies
-- Updated dependencies
-  - @statewalker/tree@0.10.2
-
-## 0.15.1
-
-### Patch Changes
-
-- Normalize package.json files
-- Updated dependencies
-  - @statewalker/tree@0.10.1
-
-## 0.15.0
-
-### Minor Changes
-
-- Migrage the "initAsyncProcess" method from the @statewalker/fsm to @statewalker/fsm-process package and add process utility methods
-
-## 0.14.0
-
-### Minor Changes
-
-- Update exports
-
-## 0.13.0
-
-### Minor Changes
-
-- Fix exports
-
-## 0.12.0
-
-### Minor Changes
-
-- Update version
-
-## 0.11.0
-
-### Minor Changes
-
-- Add initialization function for async processes
-
-## 0.10.1
-
-### Patch Changes
-
-- Migrate the @statewalker/fsm project from the @statewalker/statewalker monorepo

package/bin/cli.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-
-import startNodeProcesses from "../dist/index.js";
-
-startNodeProcesses();

package/src/core/new-fsm-process.ts

@@ -1,83 +0,0 @@
-import { isStateTransitionEnabled } from "../utils/transitions.ts";
-import { FsmProcess } from "./fsm-process.ts";
-import type { FsmStateConfig } from "./fsm-state-config.ts";
-
-export type Module<C = unknown> = (context: C) =>
-  | void
-  | (() => void | Promise<void>)
-  | Promise<void | (() => void | Promise<void>)>
-  // Event emitters / triggers
-  | Generator<string>
-  | AsyncGenerator<string>;
-
-export function newFsmProcess<C>(
-  context: C,
-  config: FsmStateConfig,
-  load: (
-    state: string,
-    event: undefined | string,
-  ) =>
-    | undefined
-    | Module<C>
-    | Module<C>[]
-    | Promise<undefined | Module<C> | Module<C>[]>,
-): [
-  dispatch: (event: string) => Promise<boolean>,
-  shutdown: () => Promise<void>,
-] {
-  let started = false;
-  let terminated = false;
-  const process = new FsmProcess(config);
-  async function dispatch(event: string): Promise<boolean> {
-    return terminated ||
-      (event !== undefined &&
-        (!started || isStateTransitionEnabled(process, event)))
-      ? process.dispatch(event)
-      : false;
-  }
-  process.onStateCreate((state) => {
-    started = true;
-    state.onEnter(async () => {
-      const modules = (await load(state.key, process.event)) ?? [];
-      for (const module of Array.isArray(modules) ? modules : [modules]) {
-        const result = await module?.(context);
-        if (isGenerator(result)) {
-          state.onExit(() => {
-            result.return?.(void 0);
-          });
-          (async () => {
-            for await (const event of result) {
-              if (terminated) {
-                break;
-              }
-              await dispatch(event);
-              if (terminated) {
-                break;
-              }
-            }
-          })();
-        } else if (typeof result === "function") {
-          state.onExit(result);
-        }
-      }
-    });
-  });
-  async function shutdown(): Promise<void> {
-    await process.shutdown();
-    terminated = true;
-  }
-  return [dispatch, shutdown] as const;
-
-  function isGenerator(
-    value: unknown,
-  ): value is
-    | Generator<string, void, unknown>
-    | AsyncGenerator<string, void, unknown> {
-    return (
-      typeof value === "object" &&
-      value !== null &&
-      "next" in value &&
-      typeof (value as Generator<string, void, unknown>).next === "function"
-    );
-  }
-}