@statewalker/fsm 0.30.0 → 0.31.0

package/dist/index.d.ts

@@ -231,15 +231,7 @@ type ProcessConfig = {
         [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>>;
+declare function launcher(options: unknown): Promise<() => Promise<void>>;
 
 interface IProcessConfigManager {
     getProcessConfig(processName: string): FsmStateConfig;
@@ -283,4 +275,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,79 @@ async function startFsmProcess(context, config, load, startEvent = "") {
 }
 
 // src/orchestrator/launcher.ts
-async function launcher(init) {
+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 (process.handlers) {
-      configsManager.registerHandlers(process.name, ...process.handlers);
+    if (processConfig) {
+      configsManager2.registerConfig(process.name, processConfig);
     }
+    let processHandlers = process.handlers;
+    if (processHandlers) {
+      if (typeof processHandlers !== "object") {
+        throw new Error(
+          `Invalid process configuration: handlers is not an array or object in process ${process.name}`
+        );
+      }
+      processHandlers = Array.isArray(processHandlers) ? processHandlers : [processHandlers];
+      configsManager2.registerHandlers(process.name, ...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");
+  }
+  let processes = config.processes ?? config.default;
+  if (!processes || typeof processes !== "object") {
+    throw new Error("Invalid launcher configuration: missing processes");
+  }
+  processes = Array.isArray(processes) ? processes : [];
+  for (const process of processes) {
+    registerProcess(configsManager, process);
   }
   const shutdowns = [];
-  for (const processName of config.start ?? []) {
-    const parent = config.context ?? rootContext;
-    const context = { parent };
+  const startProcesses = Array.isArray(config.start) ? config.start : [];
+  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.0",
+  "version": "0.31.0",
   "description": "HFSM Implementation",
   "keywords": [],
   "homepage": "https://github.com/statewalker/statewalker-fsm",

package/src/orchestrator/launcher.ts

@@ -13,24 +13,21 @@ export type ProcessConfig = {
       }
   )[];
 };
-export type ProcessLauncherConfig = {
-  start: string[];
-  context?: Record<string, unknown>;
-  processes: ProcessConfig[];
-};
+// export type ProcessLauncherConfig = {
+//   start: string[];
+//   context?: Record<string, unknown>;
+//   processes: ProcessConfig[];
+// };
 
-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>,
-) {
+// export type LauncherRootContext = Record<string, unknown> & {
+//   launch: (
+//     processName: string,
+//     context: Record<string, unknown>,
+//     startEvent?: string,
+//   ) => Promise<() => Promise<void>>;
+// };
+
+export async function launcher(options: unknown) {
   const configsManager = new ProcessConfigManager();
 
   async function launch(
@@ -43,23 +40,83 @@ 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: ProcessConfig,
+  ) {
+    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 (process.handlers) {
-      configsManager.registerHandlers(process.name, ...process.handlers);
+    if (processConfig) {
+      configsManager.registerConfig(process.name, processConfig);
+    }
+    let processHandlers = process.handlers;
+    if (processHandlers) {
+      if (typeof processHandlers !== "object") {
+        throw new Error(
+          `Invalid process configuration: handlers is not an array or object in process ${process.name}`,
+        );
+      }
+      processHandlers = Array.isArray(processHandlers)
+        ? processHandlers
+        : [processHandlers];
+      configsManager.registerHandlers(process.name, ...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");
+  }
+  let processes = config.processes ?? config.default;
+  if (!processes || typeof processes !== "object") {
+    throw new Error("Invalid launcher configuration: missing processes");
+  }
+  processes = Array.isArray(processes) ? processes : [];
+  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 };
+  const startProcesses = Array.isArray(config.start) ? config.start : [];
+  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);
   }

package/src/utils/newFsmStateHandler.ts

@@ -1,199 +0,0 @@
-import { FsmState } from "../FsmState";
-import { isStateTransitionEnabled } from "./transitions";
-
-export function newModuleLoader<T>(baseUrl: string) {
-  const cache: Record<string, Promise<T>> = {};
-  return async (path: string) => {
-    return (cache[path] =
-      cache[path] ||
-      (async () => {
-        const suffixes = ["/", "", ".ts", "/index.ts"];
-        for (const suffix of suffixes) {
-          const url = new URL(path + suffix, baseUrl).pathname;
-          try {
-            return (await import(url)) as T;
-          } catch (error) {
-            continue;
-          }
-        }
-      })());
-  };
-}
-
-export async function newHandlerLoader(
-  baseUrl: string,
-  loader: (
-    path: string,
-  ) => Promise<undefined | FsmStateModule> = newModuleLoader(baseUrl),
-): Promise<(state: FsmState) => Promise<FsmStateModule[]>> {
-  return async (state: FsmState) => {
-    const stack: string[] = [];
-    for (let s: FsmState | undefined = state; s; s = s.parent) {
-      stack.unshift(s.key);
-    }
-
-    const handlers: FsmStateModule[] = [];
-    let topName: undefined | string;
-    while (stack.length > 0) {
-      const lastSegment = stack.pop();
-      if (!topName) {
-        topName = lastSegment;
-        if (topName === undefined) break;
-      }
-      const path = [...stack, topName].join("/");
-      const handler = await loader(path);
-      handler && handlers.push(handler);
-    }
-
-    return handlers;
-  };
-}
-
-/*
-* StateContext: 
-- Each context is a function or a class
-- It recieves the stack of state objects
-- The returned value is used to pass to the handler function
-* Trigger function
-- recieves the context instance
-- notifies about changes using the given callback
-* Handler
-- recieves the context
-- starts activities on call
-- optionally returns a cleanup function
-- could return a promise with optional cleanup function; the state is not 
-  activated until all handlers return the control
-*/
-export type FsmStateModule<
-  FsmStateContext = Record<string, unknown>,
-  FsmStateStore = Record<string, unknown>,
-> = {
-  context?:
-    | ((...stack: FsmStateStore[]) => FsmStateContext)
-    | (new (
-        ...stack: FsmStateStore[]
-      ) => FsmStateContext);
-  // trigger?: (context: FsmStateContext) => AsyncGenerator<string>;
-  trigger?: (context: FsmStateContext) => AsyncIterator<string>;
-  handler?: (
-    context: FsmStateContext,
-  ) => void | (() => void) | Promise<void | (() => void)>;
-};
-
-export function newModuleContext<
-  C = Record<string, unknown>,
-  S = Record<string, unknown>,
->(module: FsmStateModule<C, S>, ...stack: S[]): C {
-  if (isClass<S[], C>(module.context)) {
-    return new module.context(...stack) as unknown as C;
-  } else if (isFunction<S[], C>(module.context)) {
-    return module.context(...stack);
-  } else {
-    return stack[0] as unknown as C;
-  }
-}
-function isFunction<T extends Array<unknown>, R = unknown>(
-  value: unknown,
-): value is (...args: T) => R {
-  return typeof value === "function";
-}
-function isClass<T extends Array<unknown>, R = unknown>(
-  value: unknown,
-): value is new (
-  ...args: T
-) => R {
-  if (!isFunction(value)) return false;
-  return value?.prototype?.constructor?.toString().match(/^class/);
-}
-
-export function newStateHandlers<
-  FsmStateContext = Record<string, unknown>,
-  FsmStateStore = Record<string, unknown>,
->(
-  loader: (
-    state: FsmState,
-  ) => Promise<FsmStateModule<FsmStateContext, FsmStateStore>[]>,
-  newContext: (state: FsmState, ...stack: FsmStateStore[]) => FsmStateStore = (
-    state,
-  ) =>
-    ({
-      state: state.key,
-      event: state.process.event,
-    }) as unknown as FsmStateStore,
-  contextCache: Map<unknown, FsmStateContext> = new Map<
-    unknown,
-    FsmStateContext
-  >(),
-) {
-  const triggers = new Map<unknown, () => void>();
-  return (state: FsmState) => {
-    const stack: FsmStateStore[] = [];
-    for (let s: FsmState | undefined = state.parent; !!s; s = s.parent) {
-      const store = s.getData<FsmStateStore>("context");
-      store && stack.push(store);
-    }
-    const store = newContext(state, ...stack);
-    stack.unshift(store);
-    state.setData("context", store);
-
-    let registrations: (void | (() => void) | Promise<void | (() => void)>)[] =
-      [];
-    state.onExit(async () => {
-      for (const r of registrations) {
-        const registration = await r;
-        registration?.();
-      }
-    });
-    state.onEnter(async () => {
-      const modules = await loader(state);
-      if (!modules?.length) return;
-      for (const module of modules) {
-        const contextKey: unknown = module.context;
-        // Create state context or get it from the local cache
-        let stateContext = contextCache.get(contextKey);
-        if (!stateContext) {
-          stateContext = newModuleContext(module, ...stack);
-          contextCache.set(contextKey, stateContext);
-          registrations.push(() => {
-            contextCache.delete(contextKey);
-          });
-        }
-
-        // Initialize triggers
-        if (module.trigger && !triggers.has(module.trigger)) {
-          const process = state.process;
-          const iterator = module.trigger(stateContext);
-          let finalize: undefined | (() => void);
-          const end = new Promise<{ done: boolean; value?: string }>(
-            (r) => (finalize = () => r({ done: true })),
-          );
-          registrations.push(() => triggers.delete(module.trigger));
-          registrations.push(finalize);
-          registrations.push(() => iterator?.return?.(void 0));
-          (async () => {
-            try {
-              while (true) {
-                const { done, value: event } = await Promise.race([
-                  iterator.next(),
-                  end,
-                ]);
-                if (done) break;
-                if (event && isStateTransitionEnabled(process, event)) {
-                  process.dispatch(event);
-                }
-              }
-            } finally {
-              finalize?.();
-            }
-          })();
-        }
-
-        // Run actions associated with this event
-        if (module.handler) {
-          const cleanup = module.handler(stateContext);
-          registrations.push(cleanup);
-        }
-      }
-    });
-  };
-}