@statewalker/fsm 0.30.1 → 0.32.0

package/dist/index.d.ts

@@ -227,19 +227,18 @@ declare function toStageHandlers<C>(value: unknown, accept: (key: string, value:
 type ProcessConfig = {
     name: string;
     config?: FsmStateConfig;
-    handlers?: (StageHandler | {
+} & ({
+    handler?: StageHandler;
+} | {
+    handlers?: StageHandler | (StageHandler | {
         [state: string]: StageHandler | StageHandler[];
     })[];
-};
-type ProcessLauncherConfig = {
-    start: string[];
-    context?: Record<string, unknown>;
-    processes: ProcessConfig[];
-};
-type LauncherRootContext = Record<string, unknown> & {
-    launch: (processName: string, context: Record<string, unknown>, startEvent?: string) => Promise<() => Promise<void>>;
-};
-declare function launcher(init: (root: LauncherRootContext) => ProcessLauncherConfig | Promise<ProcessLauncherConfig>): Promise<() => Promise<void>>;
+} | {
+    default?: StageHandler | (StageHandler | {
+        [state: string]: StageHandler | StageHandler[];
+    })[];
+});
+declare function launcher(options: unknown): Promise<() => Promise<void>>;
 
 interface IProcessConfigManager {
     getProcessConfig(processName: string): FsmStateConfig;
@@ -283,4 +282,4 @@ declare function setStateTracer(state: FsmState, print?: Printer): void;
 declare function isStateTransitionEnabled(process: FsmProcess, event: string): boolean;
 declare function getStateTransitions(state?: FsmState): [from: string, event: string, to: string][];
 
-export { EVENT_ANY, EVENT_EMPTY, type FsmEventKey, FsmProcess, type FsmProcessDump, type FsmProcessDumpHandler, type FsmProcessHandler, FsmState, type FsmStateConfig, FsmStateDescriptor, type FsmStateDump, type FsmStateDumpHandler, type FsmStateErrorHandler, type FsmStateHandler, type FsmStateKey, type IProcessConfigManager, KEY_DISPATCH, KEY_EVENT, KEY_LAUNCH_PROCESS, KEY_PRINTER, KEY_REGISTER_CONFIG, KEY_REGISTER_HANDLERS, KEY_STATES, KEY_TERMINATE, type LauncherRootContext, type Module, type Printer, type PrinterConfig, type ProcessConfig, ProcessConfigManager, type ProcessLauncherConfig, STATE_ANY, STATE_FINAL, STATE_INITIAL, STATUS_ENTER, STATUS_EXIT, STATUS_FINISHED, STATUS_FIRST, STATUS_LAST, STATUS_LEAF, STATUS_NEXT, STATUS_NONE, type StageHandler, getPrinter, getProcessPrinter, getStateTransitions, isStateTransitionEnabled, launcher, newFsmProcess, newProcess, preparePrinter, setPrinter, setProcessPrinter, setProcessTracer, setStateTracer, startFsmProcess, toStageHandlers };
+export { EVENT_ANY, EVENT_EMPTY, type FsmEventKey, FsmProcess, type FsmProcessDump, type FsmProcessDumpHandler, type FsmProcessHandler, FsmState, type FsmStateConfig, FsmStateDescriptor, type FsmStateDump, type FsmStateDumpHandler, type FsmStateErrorHandler, type FsmStateHandler, type FsmStateKey, type IProcessConfigManager, KEY_DISPATCH, KEY_EVENT, KEY_LAUNCH_PROCESS, KEY_PRINTER, KEY_REGISTER_CONFIG, KEY_REGISTER_HANDLERS, KEY_STATES, KEY_TERMINATE, type Module, type Printer, type PrinterConfig, type ProcessConfig, ProcessConfigManager, STATE_ANY, STATE_FINAL, STATE_INITIAL, STATUS_ENTER, STATUS_EXIT, STATUS_FINISHED, STATUS_FIRST, STATUS_LAST, STATUS_LEAF, STATUS_NEXT, STATUS_NONE, type StageHandler, getPrinter, getProcessPrinter, getStateTransitions, isStateTransitionEnabled, launcher, newFsmProcess, newProcess, preparePrinter, setPrinter, setProcessPrinter, setProcessTracer, setStateTracer, startFsmProcess, toStageHandlers };

package/dist/index.js

@@ -610,29 +610,106 @@ async function startFsmProcess(context, config, load, startEvent = "") {
 }
 
 // src/orchestrator/launcher.ts
-async function launcher(init) {
+function asArray(value, filter = (v) => v) {
+  if (value === void 0) return [];
+  const array = Array.isArray(value) ? value : [value];
+  return array.filter(Boolean).map(filter).filter(Boolean);
+}
+async function launcher(options) {
   const configsManager = new ProcessConfigManager();
   async function launch(processName, context, startEvent = "start") {
     const config2 = configsManager.getProcessConfig(processName);
     const load = configsManager.getHandlersLoader(processName);
     return startFsmProcess(context, config2, load, startEvent);
   }
-  const rootContext = {
-    launch
-  };
-  const config = await init(rootContext);
-  for (const process of config.processes) {
-    if (process.config) {
-      configsManager.registerConfig(process.name, process.config);
+  function registerProcess(configsManager2, process) {
+    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 processConfig = process.config;
+    if (processConfig && typeof processConfig !== "object") {
+      throw new Error(
+        `Invalid process configuration: config is not an object in process ${process.name}`
+      );
+    }
+    if (processConfig) {
+      configsManager2.registerConfig(processName, processConfig);
+    }
+    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) {
+      configsManager2.registerHandlers(processName, ...processHandlers);
     }
-    if (process.handlers) {
-      configsManager.registerHandlers(process.name, ...process.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 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;
     }
+  );
+  for (const process of processes) {
+    registerProcess(configsManager, process);
   }
   const shutdowns = [];
-  for (const processName of config.start ?? []) {
-    const parent = config.context ?? rootContext;
-    const context = { parent };
+  let startProcesses = asArray(config.start);
+  if (startProcesses.length === 0) {
+    startProcesses = processes.map((p) => p.name).filter(Boolean);
+  }
+  let initContext = (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 of startProcesses) {
+    let context = {
+      parent: rootContext,
+      "fsm:name": processName
+    };
+    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);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/fsm",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "HFSM Implementation",
   "keywords": [],
   "homepage": "https://github.com/statewalker/statewalker-fsm",

package/src/orchestrator/launcher.ts

@@ -6,31 +6,42 @@ import type { StageHandler } from "./types.ts";
 export type ProcessConfig = {
   name: string;
   config?: FsmStateConfig;
-  handlers?: (
-    | StageHandler
-    | {
-        [state: string]: StageHandler | StageHandler[];
-      }
-  )[];
-};
-export type ProcessLauncherConfig = {
-  start: string[];
-  context?: Record<string, unknown>;
-  processes: ProcessConfig[];
-};
+} & (
+  | {
+      handler?: StageHandler;
+    }
+  | {
+      handlers?:
+        | StageHandler
+        | (
+            | StageHandler
+            | {
+                [state: string]: StageHandler | StageHandler[];
+              }
+          )[];
+    }
+  | {
+      default?:
+        | StageHandler
+        | (
+            | StageHandler
+            | {
+                [state: string]: StageHandler | StageHandler[];
+              }
+          )[];
+    }
+);
 
-export type LauncherRootContext = Record<string, unknown> & {
-  launch: (
-    processName: string,
-    context: Record<string, unknown>,
-    startEvent?: string,
-  ) => Promise<() => Promise<void>>;
-};
-export async function launcher(
-  init: (
-    root: LauncherRootContext,
-  ) => ProcessLauncherConfig | Promise<ProcessLauncherConfig>,
-) {
+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 async function launcher(options: unknown) {
   const configsManager = new ProcessConfigManager();
 
   async function launch(
@@ -43,23 +54,105 @@ export async function launcher(
     return startFsmProcess(context, config, load, startEvent);
   }
 
-  const rootContext: LauncherRootContext = {
-    launch,
-  };
-  const config = await init(rootContext);
-  for (const process of config.processes) {
-    if (process.config) {
-      configsManager.registerConfig(process.name, process.config);
+  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 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 (process.handlers) {
-      configsManager.registerHandlers(process.name, ...process.handlers);
+    if (processConfig) {
+      configsManager.registerConfig(processName, processConfig);
     }
+
+    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);
+    }
+  }
+
+  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 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;
+    },
+  );
+  for (const process of processes) {
+    registerProcess(configsManager, process);
   }
 
   const shutdowns: (() => Promise<void>)[] = [];
-  for (const processName of config.start ?? []) {
-    const parent = config.context ?? rootContext;
-    const context = { parent };
+  let startProcesses = asArray<string>(config.start);
+  if (startProcesses.length === 0) {
+    startProcesses = processes.map((p) => p.name).filter(Boolean) as string[];
+  }
+
+  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 of startProcesses) {
+    let context: Record<string, unknown> = {
+      parent: rootContext,
+      "fsm:name": processName,
+    };
+    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);
   }