@statewalker/fsm 0.36.0 → 0.38.0

package/src/orchestrator/constants.ts

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,9 +0,0 @@
-export * from "./constants.ts";
-export * from "./index.ts";
-export * from "./launcher.ts";
-export * from "./process-config-manager.ts";
-export * from "./resolve-module-refs.ts";
-export * from "./start-node-processes.ts";
-export * from "./start-process.ts";
-export * from "./start-processes.ts";
-export * from "./types.ts";

package/src/orchestrator/is-generator.ts

@@ -1,12 +0,0 @@
-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

@@ -1,172 +0,0 @@
-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";
-
-export type ProcessConfig = {
-  name: string;
-  config?: FsmStateConfig;
-} & (
-  | {
-      handler?: StageHandler;
-    }
-  | {
-      handlers?:
-        | StageHandler
-        | (
-            | StageHandler
-            | {
-                [state: string]: StageHandler | StageHandler[];
-              }
-          )[];
-    }
-  | {
-      default?:
-        | StageHandler
-        | (
-            | StageHandler
-            | {
-                [state: string]: StageHandler | StageHandler[];
-              }
-          )[];
-    }
-);
-
-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(
-    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);
-  }
-
-  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 (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;
-    },
-  );
-
-  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,
-    };
-    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);
-  }
-
-  return async () => {
-    for (const shutdown of shutdowns) {
-      await shutdown();
-    }
-  };
-}

package/src/orchestrator/process-config-manager.ts

@@ -1,70 +0,0 @@
-import type { FsmStateConfig } from "../core/fsm-state-config.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/resolve-module-refs.ts

@@ -1,52 +0,0 @@
-/**
- * Resolve module paths relative to a base URL.
- * This is useful for converting relative paths to absolute URLs.
- *
- * @param baseUrl - The base URL to resolve against.
- * @param refs - An array of module references (relative or absolute).
- * @returns An array of resolved absolute module URLs as strings.
- * @example
- * ```ts
- * const urls = resolveModulesUrls(
- *  'file:///home/user/project/', // base URL
- *  'https://example.com/js/my-module.js', // absolute URL
- *  './module1.js', // relative path
- *  '../module2.js' // relative path
- * );
- * console.log(urls);
- * // Output: [
- * //  'https://example.com/js/my-module.js',
- * //  'file:///home/user/project/module1.js',
- * //  'file:///home/user/module2.js'
- * // ] *
- * ```
- */
-export function resolveModulesUrls(
-  baseUrl: URL | string,
-  ...refs: (URL | string)[]
-): string[] {
-  return refs.map((ref) => new URL(ref, baseUrl).href);
-}
-
-/**
- * Resolves module paths relative to a base URL.
- * This is useful for converting relative paths to absolute file system paths.
- * @param baseUrl - The base URL to resolve against
- * @param refs - An array of module references (relative or absolute)
- * @returns - An array of resolved absolute module paths as strings
- * @example
- * ```ts
- * const paths = resolveModulesPaths('file:///home/user/project/', './module1.js', '../module2.js');
- * console.log(paths);
- * // Output: [
- * //   '/home/user/project/module1.js',
- * //   '/home/user/module2.js'
- * // ]
- * ```
- */
-export function resolveModulesPaths(
-  baseUrl: URL | string,
-  ...refs: (URL | string)[]
-): string[] {
-  return refs.map((ref) => new URL(ref, baseUrl).pathname);
-}

package/src/orchestrator/start-node-processes.ts

@@ -1,19 +0,0 @@
-import { resolveModulesPaths } from "./resolve-module-refs.ts";
-import { startProcesses } from "./start-processes.ts";
-export async function startNodeProcesses(modules?: string[]): Promise<void> {
-  try {
-    if (!modules) {
-      modules = process.argv.slice(2);
-    }
-    const terminate = await startProcesses({
-      modules: resolveModulesPaths(`file://${process.cwd()}/`, ...modules),
-      onExit: () => process.exit(0),
-    });
-    process.on("SIGINT", terminate);
-    process.on("SIGTERM", terminate);
-    process.stdin.resume();
-  } catch (err) {
-    console.error("Fatal error:", err);
-    process.exit(1);
-  }
-}

package/src/orchestrator/start-process.ts

@@ -1,73 +0,0 @@
-import { FsmProcess } from "../core/fsm-process.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>(
-  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/start-processes.ts

@@ -1,32 +0,0 @@
-import { launcher } from "./launcher.ts";
-
-export async function startProcesses({
-  onExit,
-  modules,
-  init,
-}: {
-  onExit?: () => Promise<void> | void;
-  modules: unknown[];
-  init?: (
-    context: Record<string, unknown>,
-  ) => Promise<Record<string, unknown>> | Record<string, unknown>;
-}) {
-  const modulesList: unknown[] = [];
-  for (const module of modules) {
-    modulesList.push(
-      typeof module === "string" || module instanceof URL
-        ? await import(String(module))
-        : module,
-    );
-  }
-  return await launcher({
-    init,
-    processes: [
-      ...modulesList,
-      // This function is called on exit at the end of the process chain
-      function Exit() {
-        return onExit;
-      },
-    ],
-  });
-}

package/src/orchestrator/types.ts

@@ -1,34 +0,0 @@
-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

@@ -1,35 +0,0 @@
-import type { FsmState, FsmStateHandler } from "../core/fsm-state.ts";
-
-export const KEY_HANDLERS = "handlers";
-
-export function callStateHandlers(state: FsmState) {
-  const key = state.key;
-  for (
-    let parent: FsmState | undefined = state.parent;
-    parent;
-    parent = parent?.parent
-  ) {
-    const handlers =
-      parent.getData<Record<string, FsmStateHandler[]>>(KEY_HANDLERS)?.[key];
-    handlers?.forEach((handler) => {
-      handler(state);
-    });
-  }
-}
-
-export function addSubstateHandlers(
-  state: FsmState,
-  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)) {
-    let list = index[key];
-    if (!list) {
-      list = index[key] = [];
-    }
-    list.push(handler);
-  }
-  state.setData(KEY_HANDLERS, index);
-}

package/src/utils/index.ts

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