@statewalker/fsm 0.36.0 → 0.37.0

package/src/orchestrator/launcher.ts

@@ -1,167 +1,68 @@
 import type { FsmStateConfig } from "../core/fsm-state-config.ts";
-import { ProcessConfigManager } from "./process-config-manager.ts";
-import { startFsmProcess } from "./start-process.ts";
-import type { StageHandler } from "./types.ts";
+import type { StageHandler } from "./handler-registry.ts";
+import { createHandlerRegistry } from "./handler-registry.ts";
+import { startProcess } from "./start-process.ts";
 
-export type ProcessConfig = {
-  name: string;
-  config?: FsmStateConfig;
-} & (
-  | {
-      handler?: StageHandler;
-    }
-  | {
-      handlers?:
-        | StageHandler
-        | (
-            | StageHandler
-            | {
-                [state: string]: StageHandler | StageHandler[];
-              }
-          )[];
-    }
-  | {
-      default?:
-        | StageHandler
-        | (
-            | StageHandler
-            | {
-                [state: string]: StageHandler | StageHandler[];
-              }
-          )[];
-    }
-);
+export const KEY_LAUNCH_PROCESS = "fsm:launch";
 
-function asArray<T>(
-  value: T | T[] | undefined,
-  filter: (v: T, idx: number) => T | undefined = (v) => v,
-): T[] {
-  if (value === undefined) return [];
-  const array = Array.isArray(value) ? value : [value];
-  return array.filter(Boolean).map(filter).filter(Boolean) as T[];
+export interface LauncherConfig {
+  processes: ProcessDef[];
+  start?: string[];
+  context?: (parent: Record<string, unknown>) => Record<string, unknown>;
 }
 
-export async function launcher(options: unknown) {
-  const configsManager = new ProcessConfigManager();
+export interface ProcessDef {
+  name: string;
+  config: FsmStateConfig;
+  handlers?: (StageHandler | Record<string, StageHandler | StageHandler[]>)[];
+  start?: boolean;
+}
+
+export async function launcher(
+  config: LauncherConfig,
+): Promise<() => Promise<void>> {
+  const registry = createHandlerRegistry();
 
   async function launch(
     processName: string,
     context: Record<string, unknown>,
-    startEvent: string = "start",
+    startEvent = "start",
   ) {
-    const config = configsManager.getProcessConfig(processName);
-    const load = configsManager.getHandlersLoader(processName);
-    return startFsmProcess(context, config, load, startEvent);
+    const cfg = registry.getConfig(processName);
+    const load = registry.getLoader(processName);
+    return startProcess(context, cfg, load, startEvent);
   }
 
-  function registerProcess(
-    configsManager: ProcessConfigManager,
-    process: Record<string, unknown>,
-  ) {
-    if (!process || typeof process !== "object") {
-      throw new Error("Invalid process configuration: not an object");
-    }
-    const processName = process.name;
-    if (!processName || typeof processName !== "string") {
-      throw new Error("Invalid process configuration: missing or invalid name");
-    }
+  const rootContext: Record<string, unknown> = {
+    [KEY_LAUNCH_PROCESS]: launch,
+  };
+  const initContext = config.context ?? ((ctx: Record<string, unknown>) => ctx);
 
-    const processConfig = process.config as FsmStateConfig | undefined;
-    if (processConfig && typeof processConfig !== "object") {
-      throw new Error(
-        `Invalid process configuration: config is not an object in process ${process.name}`,
-      );
-    }
-    if (processConfig) {
-      configsManager.registerConfig(processName, processConfig);
-    }
+  const startSet = config.start ? new Set(config.start) : undefined;
 
-    const processHandlers = asArray(
-      process.handlers ?? process.handler ?? process.default,
-      (v, idx) => {
-        if (typeof v === "function") return v;
-        if (typeof v === "object" && v !== null) return v;
-        throw new Error(
-          [
-            `Invalid process configuration:`,
-            `a process handler is not object nor function in process ${processName} at index ${idx}`,
-            `Recieved: ${v === null ? "null" : typeof v}`,
-          ].join("\n"),
-        );
-      },
-    );
-    if (processHandlers.length > 0) {
-      configsManager.registerHandlers(processName, ...processHandlers);
+  for (const def of config.processes) {
+    registry.register(def.name, def.config);
+    if (def.handlers?.length) {
+      registry.registerHandlers(def.name, ...def.handlers);
     }
   }
 
-  const rootContext = { "fsm:launch": launch };
-  const init = typeof options === "function" ? options : async () => options;
-  const config = await init(rootContext);
-  if (typeof config !== "object" || !config) {
-    throw new Error("Invalid launcher configuration");
-  }
+  const shutdowns: (() => Promise<void>)[] = [];
+  const seen = new Set<string>();
+  for (const def of config.processes) {
+    if (seen.has(def.name)) continue;
+    seen.add(def.name);
 
-  const processes = asArray(
-    config.processes ?? config.process ?? config.default,
-    (v) => {
-      if (typeof v === "function") {
-        return {
-          name: v.name || "",
-          handler: v,
-        };
-      }
-      if (typeof v !== "object") {
-        throw new Error(
-          "Invalid launcher configuration: process is not an object",
-        );
-      }
-      return v;
-    },
-  );
+    if (def.start === false) continue;
+    if (startSet && !startSet.has(def.name)) continue;
 
-  const processesToStart = {} as Record<string, undefined | boolean>;
-  for (const process of processes) {
-    const processName = process.name;
-    const start = process.start;
-    if (start === undefined) {
-      if (!(processName in processesToStart)) {
-        processesToStart[processName] = undefined;
-      }
-    } else {
-      processesToStart[processName] = start;
-    }
-    registerProcess(configsManager, process);
-  }
-
-  const shutdowns: (() => Promise<void>)[] = [];
-  let initContext: (
-    parent: Record<string, unknown>,
-  ) => Record<string, unknown> = (context) => context;
-  const configContext = config.context ?? config.init;
-  if (configContext) {
-    if (typeof configContext === "function") {
-      initContext = configContext;
-    } else if (typeof configContext === "object") {
-      initContext = () => ({ parent: configContext });
-    } else {
-      throw new Error("Invalid launcher configuration: context");
-    }
-  }
-  for (const [processName, start] of Object.entries(processesToStart)) {
-    if (start === false) continue;
     let context: Record<string, unknown> = {
       parent: rootContext,
-      "fsm:name": processName,
+      "fsm:name": def.name,
     };
     context = initContext(context) ?? context;
-    if (typeof context !== "object") {
-      throw new Error(
-        `Invalid launcher context for process "${processName}". Expected an object, but recieved ${typeof context}.`,
-      );
-    }
-    const shutdown = await launch(processName, context);
-    shutdowns.push(shutdown);
+    const handle = await launch(def.name, context);
+    shutdowns.push(handle.shutdown);
   }
 
   return async () => {

package/src/orchestrator/start-process.ts

@@ -1,34 +1,115 @@
-import { FsmProcess } from "../core/fsm-process.ts";
+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 "../utils/index.ts";
-import {
-  KEY_DISPATCH,
-  KEY_EVENT,
-  KEY_STATES,
-  KEY_TERMINATE,
-} from "./constants.ts";
-import { isGenerator } from "./is-generator.ts";
-import type { StageHandler } from "./types.ts";
-
-export async function startFsmProcess<C = unknown>(
+import type { FsmStateDescriptor } from "../core/fsm-state-descriptor.ts";
+import type { StageHandler } from "./handler-registry.ts";
+
+export interface ProcessHandle {
+  shutdown(): Promise<void>;
+  dump(...args: unknown[]): Promise<FsmProcessDump>;
+  restore(dump: FsmProcessDump, ...args: unknown[]): Promise<void>;
+}
+
+// Context keys for binding FSM functions into the shared context object.
+export const KEY_DISPATCH = "fsm:dispatch";
+export const KEY_TERMINATE = "fsm:terminate";
+export const KEY_STATES = "fsm:states";
+export const KEY_EVENT = "fsm:event";
+
+// ---------------------------------------------------------------------------
+// Transition introspection
+// ---------------------------------------------------------------------------
+
+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;
+        if (target) index[event] = true;
+        result.push([prevStateKey, event, target]);
+      }
+    }
+  }
+  return result;
+}
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// 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)
+// ---------------------------------------------------------------------------
+
+export async function startProcess<C = unknown>(
   context: C,
   config: FsmStateConfig,
   load: (
     state: string,
-    event: undefined | string,
+    event: string | undefined,
   ) => StageHandler<C>[] | Promise<StageHandler<C>[]>,
   startEvent = "",
-): Promise<() => Promise<void>> {
+): Promise<ProcessHandle> {
   let terminated = false;
   const ctx = context as Record<string, unknown>;
   const process = new FsmProcess(config);
   const statesStack: string[] = [];
-  // ctx[KEY_PROCESS] = process;
-  process.onStateCreate((state) => {
+
+  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);
@@ -36,18 +117,21 @@ export async function startFsmProcess<C = unknown>(
           let stateExited = false;
           state.onExit(() => {
             stateExited = true;
-            result.return?.(void 0);
+            result.return?.(undefined as never);
           });
           (async () => {
-            for await (const event of result) {
-              if (stateExited || terminated) {
-                break;
+            try {
+              for await (const event of result) {
+                if (stateExited || terminated) break;
+                await dispatch(event);
+                if (stateExited || terminated) break;
               }
-              await dispatch(event);
+            } catch {
+              // Swallow generator errors after return()
             }
           })();
         } else if (typeof result === "function") {
-          state.onExit(result);
+          state.onExit(result as () => void | Promise<void>);
         }
       }
     });
@@ -57,17 +141,48 @@ export async function startFsmProcess<C = unknown>(
       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 dispatch(event: string): Promise<void> {
-    if (event !== undefined && isStateTransitionEnabled(process, event)) {
-      await process.dispatch(event);
+
+  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 terminate;
+  return {
+    shutdown: terminate,
+    dump: dumpProcess,
+    restore: restoreProcess,
+  };
 }
+
+/** @deprecated Use `startProcess` instead */
+export const startFsmProcess = startProcess;

package/src/utils/index.ts

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

package/src/utils/printer.ts

@@ -1,5 +1,4 @@
 import type { FsmProcess } from "../core/fsm-process.ts";
-import type { FsmState } from "../core/fsm-state.ts";
 export type Printer = (...args: unknown[]) => void;
 export type PrinterConfig = {
   prefix?: string;
@@ -7,7 +6,7 @@ export type PrinterConfig = {
   lineNumbers?: boolean;
 };
 
-export const KEY_PRINTER = "printer";
+const printerStore = new WeakMap<object, Printer>();
 
 export function preparePrinter(
   process: FsmProcess,
@@ -26,23 +25,18 @@ export function preparePrinter(
   return printer;
 }
 
-export function setPrinter(state: FsmState, config: PrinterConfig = {}) {
-  const printer = preparePrinter(state.process, config);
-  state.setData(KEY_PRINTER, printer);
-}
-
 export function setProcessPrinter(
   process: FsmProcess,
   config: PrinterConfig = {},
 ) {
   const printer = preparePrinter(process, config);
-  process.setData(KEY_PRINTER, printer);
+  printerStore.set(process, printer);
 }
 
 export function getProcessPrinter(process: FsmProcess): Printer {
-  return process.getData(KEY_PRINTER) || console.log;
+  return printerStore.get(process) || console.log;
 }
 
-export function getPrinter(state: FsmState): Printer {
-  return state.getData(KEY_PRINTER, true) || getProcessPrinter(state.process);
+export function getPrinter(state: { process: FsmProcess }): Printer {
+  return printerStore.get(state) || getProcessPrinter(state.process);
 }

package/src/utils/tracer.ts

@@ -3,7 +3,7 @@ import type { FsmState } from "../core/fsm-state.ts";
 import { getPrinter, type Printer } from "./printer.ts";
 
 export function setProcessTracer(process: FsmProcess, print?: Printer) {
-  return process.onStateCreate((state) => {
+  return process.onStateCreate((state: FsmState) => {
     setStateTracer(state, print);
   });
 }

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