@statewalker/fsm 0.28.0 → 0.30.0

package/src/FsmBaseClass.ts

@@ -1,5 +1,8 @@
+type Handler<P extends unknown[] = unknown[], R = unknown> = (...args: P) => R; // Function;
+// type Handler = Function;
+
 export class FsmBaseClass {
-  handlers: Record<string, Function[]> = {};
+  handlers: Record<string, Handler[]> = {};
   data: Record<string, unknown> = {};
   constructor() {
     bindMethods(this, "setData", "getData");
@@ -14,13 +17,17 @@ export class FsmBaseClass {
 
   // ----------------------------------------------
   // internal methods
-  _addHandler(type: string, handler: Function, direct: boolean = true) {
-    const list = (this.handlers[type] = this.handlers[type] || []);
-    direct ? list.push(handler) : list.unshift(handler);
-    return () => this._removeHandler(type, handler);
+  protected _addHandler<T>(type: string, handler: T, direct: boolean = true) {
+    let list = this.handlers[type];
+    if (!list) {
+      list = this.handlers[type] = [];
+    }
+    const h = handler as Handler;
+    direct ? list.push(h) : list.unshift(h);
+    return () => this._removeHandler(type, h);
   }
 
-  _removeHandler(type: string, handler: Function) {
+  protected _removeHandler<T>(type: string, handler: T) {
     let list = this.handlers[type];
     if (!list) return;
     list = list.filter((h) => h !== handler);

package/src/FsmProcess.ts

@@ -1,8 +1,12 @@
-import { FsmBaseClass, bindMethods } from "./FsmBaseClass.ts";
-import { FsmState, FsmStateDump, FsmStateHandler } from "./FsmState.ts";
+import { bindMethods, FsmBaseClass } from "./FsmBaseClass.ts";
+import {
+  FsmState,
+  type FsmStateDump,
+  type FsmStateHandler,
+} from "./FsmState.ts";
 import {
   EVENT_EMPTY,
-  FsmStateConfig,
+  type FsmStateConfig,
   STATE_FINAL,
   STATE_INITIAL,
 } from "./FsmStateConfig.ts";

package/src/FsmState.ts

@@ -1,6 +1,6 @@
-import { FsmBaseClass, bindMethods } from "./FsmBaseClass.ts";
-import { FsmProcess } from "./FsmProcess.ts";
-import { FsmStateDescriptor } from "./FsmStateDescriptor.ts";
+import { bindMethods, FsmBaseClass } from "./FsmBaseClass.ts";
+import type { FsmProcess } from "./FsmProcess.ts";
+import type { FsmStateDescriptor } from "./FsmStateDescriptor.ts";
 
 export type FsmStateDump = Record<string, unknown> & {
   key: string;
@@ -13,12 +13,12 @@ export type FsmStateHandler = (
 
 export type FsmStateDumpHandler = (
   state: FsmState,
-  dump: FsmStateDump
+  dump: FsmStateDump,
 ) => void | Promise<void>;
 
 export type FsmStateErrorHandler = (
   state: FsmState,
-  error: unknown
+  error: unknown,
 ) => void | Promise<void>;
 
 export class FsmState extends FsmBaseClass {
@@ -31,7 +31,7 @@ export class FsmState extends FsmBaseClass {
     process: FsmProcess,
     parent: FsmState | undefined,
     key: string,
-    descriptor?: FsmStateDescriptor
+    descriptor?: FsmStateDescriptor,
   ) {
     super();
     this.process = process;
@@ -45,7 +45,7 @@ export class FsmState extends FsmBaseClass {
       "dump",
       "restore",
       "useData",
-      "onStateError"
+      "onStateError",
     );
   }
 

package/src/FsmStateDescriptor.ts

@@ -1,6 +1,6 @@
 import {
-  type FsmStateConfig,
   EVENT_ANY,
+  type FsmStateConfig,
   STATE_ANY,
   STATE_FINAL,
 } from "./FsmStateConfig.ts";
@@ -12,13 +12,16 @@ export class FsmStateDescriptor {
   static build(config: FsmStateConfig) {
     const descriptor = new FsmStateDescriptor();
     for (const [from, event, to] of config.transitions || []) {
-      const index = (descriptor.transitions[from] =
-        descriptor.transitions[from] || {});
+      let index = descriptor.transitions[from];
+      if (!index) {
+        index = descriptor.transitions[from] = {};
+      }
       index[event] = to;
     }
     if (config.states) {
       for (const substateConfig of config.states) {
-        descriptor.states[substateConfig.key] = this.build(substateConfig);
+        descriptor.states[substateConfig.key] =
+          FsmStateDescriptor.build(substateConfig);
       }
     }
     return descriptor;
@@ -31,7 +34,7 @@ export class FsmStateDescriptor {
       [stateKey, EVENT_ANY],
       [STATE_ANY, EVENT_ANY],
     ];
-    let targetKey;
+    let targetKey: string | undefined;
     for (
       let i = 0, len = pairs.length;
       targetKey === undefined && i < len;

package/src/index.ts

@@ -2,6 +2,6 @@ export * from "./FsmProcess.ts";
 export * from "./FsmState.ts";
 export * from "./FsmStateConfig.ts";
 export * from "./FsmStateDescriptor.ts";
+export * from "./newFsmProcess.ts";
+export * from "./orchestrator/index.ts";
 export * from "./utils/index.ts";
-export * from "./newFsmProcess.js";
-export * from "./startFsmProcess.js";

package/src/newFsmProcess.ts

@@ -1,13 +1,14 @@
-import { FsmProcess } from "./FsmProcess.js";
-import type { FsmStateConfig } from "./FsmStateConfig.js";
-import { isStateTransitionEnabled } from "./utils/transitions.js";
+import { FsmProcess } from "./FsmProcess.ts";
+import type { FsmStateConfig } from "./FsmStateConfig.ts";
+import { isStateTransitionEnabled } from "./utils/transitions.ts";
 
-export type Module<C = unknown> = (
-  context: C,
-) =>
+export type Module<C = unknown> = (context: C) =>
   | void
   | (() => void | Promise<void>)
-  | Promise<void | (() => void | Promise<void>)>;
+  | Promise<void | (() => void | Promise<void>)>
+  // Event emitters / triggers
+  | Generator<string>
+  | AsyncGenerator<string>;
 
 export function newFsmProcess<C>(
   context: C,
@@ -27,28 +28,56 @@ export function newFsmProcess<C>(
   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 handler = await module(context);
-        if (typeof handler === "function") {
-          state.onExit(handler);
+        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 dispatch(event: string): Promise<boolean> {
-    return terminated ||
-      (event !== undefined &&
-        (!started || isStateTransitionEnabled(process, event)))
-      ? process.dispatch(event)
-      : false;
-  }
   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"
+    );
+  }
 }

package/src/orchestrator/ProcessConfigManager.ts

@@ -0,0 +1,70 @@
+import type { FsmStateConfig } from "../FsmStateConfig.ts";
+import { type StageHandler, toStageHandlers } from "./types.ts";
+
+export interface IProcessConfigManager {
+  getProcessConfig(processName: string): FsmStateConfig;
+  getHandlersLoader<C = unknown>(
+    processName: string,
+  ): (state: string, event: undefined | string) => StageHandler<C>[];
+  registerConfig(name: string, config: FsmStateConfig): () => void;
+  registerHandlers(name: string, ...modules: unknown[]): () => void;
+}
+
+export class ProcessConfigManager implements IProcessConfigManager {
+  protected configs: Record<string, FsmStateConfig> = {};
+  protected handlers: Record<string, unknown[]> = {};
+
+  getProcessConfig(processName: string): FsmStateConfig {
+    return this.configs[processName] ?? { key: "Main" };
+  }
+
+  getHandlersLoader<C = unknown>(
+    processName: string,
+  ): (state: string, event: undefined | string) => StageHandler<C>[] {
+    const config = this.getProcessConfig(processName);
+    return (stateKey: string) => {
+      const modulesKeys: string[] = [];
+      if (stateKey === config.key) {
+        modulesKeys.push("default");
+      }
+      modulesKeys.push(
+        stateKey,
+        `${stateKey}Controller`,
+        `${stateKey}StateController`,
+        `${stateKey}View`,
+        `${stateKey}StateView`,
+        `${stateKey}Trigger`,
+        `${stateKey}StateTrigger`,
+        `${stateKey}Test`,
+        `${stateKey}StateTest`,
+      );
+      const keysSet = new Set(modulesKeys);
+      const processHandlers = this.handlers[processName] ?? [];
+      const handlers = toStageHandlers(processHandlers, (key: string) =>
+        keysSet.has(key),
+      );
+      return handlers;
+    };
+  }
+
+  registerConfig(name: string, config: FsmStateConfig): () => void {
+    this.configs[name] = config;
+    return () => {
+      delete this.configs[name];
+    };
+  }
+
+  registerHandlers(name: string, ...modules: unknown[]): () => void {
+    let list: unknown[] = this.handlers[name];
+    if (!list) {
+      list = this.handlers[name] = [];
+    }
+    list.push(modules);
+    return () => {
+      list = list.filter((v) => v !== modules);
+      if (list.length === 0) {
+        delete this.handlers[name];
+      }
+    };
+  }
+}

package/src/orchestrator/constants.ts

@@ -0,0 +1,130 @@
+/**
+ * Key used to bind the dispatch function to the process context.
+ * The dispatch function allows triggering state transitions by dispatching events.
+ *
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * // Initialize the FSM process using `startFsmProcess`
+ * const dispatch = context["fsm:dispatch"] as (event: string) => Promise<void>;
+ * await dispatch("someEvent");
+ */
+export const KEY_DISPATCH = "fsm:dispatch" as const;
+
+/**
+ * Key used to bind the terminate function to the process context.
+ * The terminate function is used to gracefully shut down the FSM process.
+ * It returns a Promise that resolves when the process has been fully terminated.
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * // Initialize the FSM process using `startFsmProcess`
+ * const terminate = context["fsm:terminate"] as () => Promise<void>;
+ * await terminate();
+ * ```
+ */
+export const KEY_TERMINATE = "fsm:terminate" as const;
+
+/**
+ * Key used to bind the current stack of active states to the process context.
+ * This provides a snapshot of the states the FSM process has entered.
+ * It is represented as an array of strings -- state keys.
+ *
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * // Initialize the FSM process using `startFsmProcess`
+ * const states = context["fsm:states"] as string[];
+ * console.log("Current active states:", states);
+ * ```
+ */
+export const KEY_STATES = "fsm:states" as const;
+
+/**
+ * Key used to bind the current event being processed to the process context.
+ * This represents the event that triggered the current state transition.
+ * It is represented as a string.
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * // Initialize the FSM process using `startFsmProcess`
+ * const event = context["fsm:event"] as string;
+ * console.log("Current event:", event);
+ * ```
+ */
+export const KEY_EVENT = "fsm:event" as const;
+
+//-------------------------------------------------
+
+// export const KEY_START_PROCESS = "fsm:sys:start" as const;
+/**
+ * Key used to register a new FSM process configuration in the process context.
+ * This key is associated with a function that allows adding new FSM configurations.
+ * The function takes a process name and its configuration, and returns a cleanup function
+ * to remove the registered configuration.
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * initProcessManager(context); // Initialize the process manager in the context
+ * ...
+ * type StateConfig = { key: string; transitions?: string[][]; states?: StateConfig[] };
+ * const registerConfig = context["fsm:sys:registerConfig"] as (name: string, config: StateConfig) => () => void;
+ * const unregister = registerConfig("myProcess", { key: "Main", transitions: [...] });
+ * // To unregister the configuration later
+ * unregister();
+ * ```
+ */
+export const KEY_REGISTER_CONFIG = "fsm:sys:registerConfig" as const;
+
+/**
+ * Key used to register state and event handlers for FSM processes in the process context.
+ * This key is associated with a function that allows adding handler modules for a specific process.
+ * The function takes a process name and a variable number of handler modules, returning a cleanup function
+ * to remove the registered handlers.
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * initProcessManager(context); // Initialize the process manager in the context
+ * ...
+ * const registerHandlers = context["fsm:sys:registerHandlers"] as (name: string, ...modules: unknown[]) => () => void;
+ * const handlerModule1 = {
+ *   Main: async (context) => { ... },
+ *   SomeState: async (context) => { ... },
+ * }
+ * // Views layer can be defined in the same or separate modules
+ * const handlerModule3 = {
+ *  MainView: async (context) => { ... },
+ *  SomeStateView: async (context) => { ... },
+ * }
+ * // A common handler function to call for all states
+ * const handlerModule2 = (context) => { ... };
+ * const unregister = registerHandlers(
+ *  "myProcess",
+ *  handlerModule1,
+ *  handlerModule2,
+ *  handlerModule3
+ * );
+ * // To unregister the handlers later
+ * unregister();
+ * ```
+ */
+export const KEY_REGISTER_HANDLERS = "fsm:sys:registerHandlers" as const;
+
+/**
+ * Key used to launch an FSM process in the process context.
+ * This key is associated with a function that initiates the FSM process based on its name and context.
+ * The function takes the process name and context, returning either nothing, a cleanup function,
+ * or a Promise that resolves to either nothing or a cleanup function.
+ * Example usage:
+ * ```typescript
+ * const context: Record<string, unknown> = {};
+ * initProcessManager(context); // Initialize the process manager in the context
+ * // Register process configurations and handlers as needed
+ *
+ * const launchProcess = context["fsm:sys:launch"] as (name: string, context: Record<string, unknown>) => () => Promise<void>;
+ * const terminate = await launchProcess("myProcess", context);
+ * // To terminate the process later
+ * terminate?.();
+ * ```
+ */
+export const KEY_LAUNCH_PROCESS = "fsm:sys:launch" as const;

package/src/orchestrator/index.ts

@@ -0,0 +1,6 @@
+export * from "./constants.ts";
+export * from "./index.ts";
+export * from "./launcher.ts";
+export * from "./ProcessConfigManager.ts";
+export * from "./startFsmProcess.ts";
+export * from "./types.ts";

package/src/orchestrator/isGenerator.ts

@@ -0,0 +1,12 @@
+export 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"
+  );
+}

package/src/orchestrator/launcher.ts

@@ -0,0 +1,72 @@
+import type { FsmStateConfig } from "../FsmStateConfig.ts";
+import { ProcessConfigManager } from "./ProcessConfigManager.ts";
+import { startFsmProcess } from "./startFsmProcess.ts";
+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[];
+};
+
+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>,
+) {
+  const configsManager = new ProcessConfigManager();
+
+  async function launch(
+    processName: string,
+    context: Record<string, unknown>,
+    startEvent: string = "start",
+  ) {
+    const config = configsManager.getProcessConfig(processName);
+    const load = configsManager.getHandlersLoader(processName);
+    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);
+    }
+    if (process.handlers) {
+      configsManager.registerHandlers(process.name, ...process.handlers);
+    }
+  }
+
+  const shutdowns: (() => Promise<void>)[] = [];
+  for (const processName of config.start ?? []) {
+    const parent = config.context ?? rootContext;
+    const context = { parent };
+    const shutdown = await launch(processName, context);
+    shutdowns.push(shutdown);
+  }
+
+  return async () => {
+    for (const shutdown of shutdowns) {
+      await shutdown();
+    }
+  };
+}

package/src/orchestrator/startFsmProcess.ts

@@ -0,0 +1,73 @@
+import { FsmProcess } from "../FsmProcess.ts";
+import type { FsmStateConfig } from "../FsmStateConfig.ts";
+import { isStateTransitionEnabled } from "../utils/index.ts";
+import {
+  KEY_DISPATCH,
+  KEY_EVENT,
+  KEY_STATES,
+  KEY_TERMINATE,
+} from "./constants.ts";
+import { isGenerator } from "./isGenerator.ts";
+import type { StageHandler } from "./types.ts";
+
+export async function startFsmProcess<C = unknown>(
+  context: C,
+  config: FsmStateConfig,
+  load: (
+    state: string,
+    event: undefined | string,
+  ) => StageHandler<C>[] | Promise<StageHandler<C>[]>,
+  startEvent = "",
+): Promise<() => Promise<void>> {
+  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) => {
+    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?.(void 0);
+          });
+          (async () => {
+            for await (const event of result) {
+              if (stateExited || terminated) {
+                break;
+              }
+              await dispatch(event);
+            }
+          })();
+        } else if (typeof result === "function") {
+          state.onExit(result);
+        }
+      }
+    });
+    state.onExit(() => {
+      statesStack.pop();
+      ctx[KEY_STATES] = [...statesStack];
+      ctx[KEY_EVENT] = process.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);
+    }
+  }
+  ctx[KEY_DISPATCH] = dispatch;
+  ctx[KEY_TERMINATE] = terminate;
+  await process.dispatch(startEvent);
+  return terminate;
+}

package/src/orchestrator/types.ts

@@ -0,0 +1,34 @@
+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>;
+
+export function toStageHandlers<C>(
+  value: unknown,
+  accept: (key: string, value: unknown) => boolean,
+): StageHandler<C>[] {
+  return visit(value);
+
+  function visit(val: unknown): StageHandler<C>[] {
+    if (!val) {
+      return [];
+    }
+    if (typeof val === "function") {
+      return [val] as StageHandler<C>[];
+    }
+    if (typeof val !== "object") {
+      return [];
+    }
+    if (Array.isArray(val)) {
+      return val.flatMap(visit);
+    }
+    const modulesIndex = val as Record<string, unknown>;
+    return Object.entries(modulesIndex).flatMap(([key, value]) => {
+      return accept(key, value) ? visit(value) : [];
+    });
+  }
+}

package/src/utils/handlers.ts

@@ -6,24 +6,29 @@ export function callStateHandlers(state: FsmState) {
   const key = state.key;
   for (
     let parent: FsmState | undefined = state.parent;
-    !!parent;
+    parent;
     parent = parent?.parent
   ) {
     const handlers =
       parent.getData<Record<string, FsmStateHandler[]>>(KEY_HANDLERS)?.[key];
-    handlers?.forEach((handler) => handler(state));
+    handlers?.forEach((handler) => {
+      handler(state);
+    });
   }
 }
 
 export function addSubstateHandlers(
   state: FsmState,
-  handlers: Record<string, FsmStateHandler>
+  handlers: Record<string, FsmStateHandler>,
 ) {
   const oldIndex =
     state.getData<Record<string, FsmStateHandler[]>>(KEY_HANDLERS);
   const index = oldIndex ? { ...oldIndex } : {};
   for (const [key, handler] of Object.entries(handlers)) {
-    const list = (index[key] = index[key] || []);
+    let list = index[key];
+    if (!list) {
+      list = index[key] = [];
+    }
     list.push(handler);
   }
   state.setData(KEY_HANDLERS, index);