@statewalker/fsm 0.15.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/fsm",
-  "version": "0.15.2",
+  "version": "0.20.0",
   "description": "HFSM Implementation",
   "keywords": [],
   "homepage": "https://github.com/statewalker/statewalker-fsm",
@@ -11,41 +11,44 @@
   "license": "MIT",
   "type": "module",
   "files": [
-    "dist/**/package.json",
-    "dist/**/*.js",
-    "src/**/*.js",
-    "index.js"
+    "dist",
+    "src"
   ],
-  "module": "src/index.js",
-  "main": "src/index.js",
-  "jsdelivr": "dist/index.js",
-  "unpkg": "dist/index.js",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "jsdelivr": "./dist/index.js",
+  "unpkg": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    "umd": "./dist/index-umd.min.js",
-    "default": "./src/index.js"
+    ".": {
+      "import": "./src/index.ts"
+    }
   },
   "dependencies": {
     "@statewalker/tree": "0.10.2"
   },
   "devDependencies": {
-    "@statewalker/rollup": "^0.1.6",
-    "eslint": "^8",
-    "expect.js": "^0.3",
-    "mocha": "^10",
-    "rollup": "^3"
+    "@statewalker/eslint-config": "*",
+    "@statewalker/typescript-config": "*",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.4",
+    "vitest": "^1.4.0"
   },
   "repository": {
     "type": "git",
     "url": "git@github.com:statewalker/statewalker-fsm.git"
   },
   "scripts": {
-    "eslint": "eslint src",
-    "rollup": "rollup -c",
-    "test": "mocha -R spec ./test/index.js && yarn eslint",
-    "prepublishOnly": "rm -rf dist && yarn test && yarn rollup"
+    "build": "yarn test && tsup",
+    "watch": "tsup --watch",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"**/*.(js|ts)\"",
+    "test": "vitest --run",
+    "test:watch": "vitest"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/FsmBaseClass.ts

@@ -0,0 +1,52 @@
+import { bindMethods } from "./utils/bindMethods.ts";
+
+export class FsmBaseClass {
+  handlers: Record<string, Function[]> = {};
+  data: Record<string, unknown> = {};
+  constructor() {
+    bindMethods(this, "setData", "getData");
+  }
+  setData<T>(key: string, value: T) {
+    this.data[key] = value;
+    return this;
+  }
+  getData<T>(key: string): T | undefined {
+    return this.data[key] as T;
+  }
+
+  // ----------------------------------------------
+  // 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);
+  }
+
+  _removeHandler(type: string, handler: Function) {
+    let list = this.handlers[type];
+    if (!list) return;
+    list = list.filter((h) => h !== handler);
+    if (list.length > 0) {
+      this.handlers[type] = list;
+    } else {
+      delete this.handlers[type];
+    }
+  }
+  _runHandlerSync(type: string, ...args: unknown[]) {
+    const list = this.handlers[type] || [];
+    return list.map((handler) => handler(...args));
+  }
+  async _runHandler(type: string, ...args: unknown[]) {
+    const promises = this._runHandlerSync(type, ...args);
+    for (const promise of promises) {
+      try {
+        await promise;
+      } catch (error) {
+        await this._handleError(error);
+      }
+    }
+  }
+  async _handleError(error: Error | unknown) {
+    console.error(error);
+  }
+}

package/src/FsmProcess.ts

@@ -0,0 +1,184 @@
+import { bindMethods } from "./utils/bindMethods.ts";
+import { FsmBaseClass } from "./FsmBaseClass.ts";
+import {
+  FsmState,
+  FsmStateDump,
+  FsmStateSyncHandler,
+} from "./FsmState.ts";
+import {
+  EVENT_EMPTY,
+  FsmStateConfig,
+  STATE_FINAL,
+  STATE_INITIAL,
+} from "./FsmStateConfig.ts";
+import { FsmStateDescriptor } from "./FsmStateDescriptor.ts";
+
+export const STATUS_NONE = 0;
+export const STATUS_FIRST = 1;
+export const STATUS_NEXT = 2;
+export const STATUS_LEAF = 4;
+export const STATUS_LAST = 8;
+export const STATUS_FINISHED = 16;
+
+//
+export const STATUS_ENTER = STATUS_FIRST | STATUS_NEXT;
+export const STATUS_EXIT = STATUS_LEAF | STATUS_LAST;
+
+export type FsmProcessHandler = (
+  process: FsmProcess,
+  ...args: any[]
+) => void | Promise<void>;
+
+export type FsmProcessDump = Record<string, any> & {
+  status: number;
+  event?: string;
+  stack: FsmStateDump[];
+};
+
+export type FsmProcessDumpHandler = (
+  process: FsmProcess,
+  dump: FsmProcessDump
+) => void | Promise<void>;
+
+export class FsmProcess extends FsmBaseClass {
+  state?: FsmState;
+  event?: string;
+  status: number = 0;
+  config: FsmStateConfig;
+  rootDescriptor: FsmStateDescriptor;
+
+  constructor(config: FsmStateConfig) {
+    super();
+    this.rootDescriptor = FsmStateDescriptor.build(config);
+    this.config = config;
+    bindMethods(this, "dispatch", "dump", "restore");
+  }
+
+  async dispatch(event: string, mask: number = STATUS_LEAF) {
+    this.event = event;
+    while (true) {
+      if (this.status & STATUS_EXIT) {
+        await this.state?._runHandler("onExit", this.state);
+      }
+      if (!this._update()) return false;
+      if (this.status & STATUS_ENTER) {
+        await this.state?._runHandler("onEnter", this.state);
+      }
+      if (this.status & mask) return true;
+    }
+  }
+
+  async dump(...args: unknown[]): Promise<FsmProcessDump> {
+    const dumpState = async (state: FsmState) => {
+      const stateDump: FsmStateDump = {
+        key: state.key,
+        data: {},
+      };
+      await state._runHandler("dump", state, stateDump.data, ...args);
+      return stateDump;
+    };
+    const dumpStates = async (
+      state: FsmState | undefined,
+      stack: FsmStateDump[] = []
+    ) => {
+      if (!state) return stack;
+      state.parent && (await dumpStates(state.parent, stack));
+      stack.push(await dumpState(state));
+      return stack;
+    };
+    const dump: FsmProcessDump = {
+      status: this.status,
+      event: this.event,
+      stack: await dumpStates(this.state),
+    };
+    return dump;
+  }
+
+  async restore(dump: FsmProcessDump, ...args: unknown[]) {
+    this.status = dump.status || 0;
+    this.event = dump.event;
+    this.state = undefined;
+    for (let i = 0; i < dump.stack.length; i++) {
+      const stateDump = dump.stack[i];
+      this.state = this.state
+        ? this._newSubstate(this.state, stateDump.key)
+        : this._newState(undefined, stateDump.key, this.rootDescriptor);
+      await this.state._runHandler(
+        "restore",
+        this.state,
+        stateDump.data,
+        ...args
+      );
+    }
+    return this;
+  }
+
+  onStateCreate(handler: FsmStateSyncHandler) {
+    return this._addHandler("onStateCreate", handler, true);
+  }
+
+  onStateError(handler: (state: FsmState, error: any) => void | Promise<void>) {
+    return this._addHandler("onStateError", handler);
+  }
+
+  async _handleStateError(state: FsmState, error: Error | unknown) {
+    await this._runHandler("onStateError", state, error);
+    this._handleError(error);
+  }
+
+  _newState(
+    parent: FsmState | undefined,
+    key: string,
+    descriptor: FsmStateDescriptor | undefined
+  ) {
+    const state = new FsmState(this, parent, key, descriptor);
+    this._runHandlerSync("onStateCreate", state);
+    return state;
+  }
+
+  _getSubstate(parent: FsmState | undefined, prevStateKey: string | undefined) {
+    if (!parent) return;
+    const toState =
+      parent.descriptor?.getTargetStateKey(
+        prevStateKey || STATE_INITIAL,
+        this.event || EVENT_EMPTY
+      ) || STATE_FINAL;
+    if (!toState) return;
+    return this._newSubstate(parent, toState);
+  }
+
+  _newSubstate(parent: FsmState | undefined, toState: string) {
+    let descriptor: FsmStateDescriptor | undefined;
+    for (
+      let state: FsmState | undefined = parent;
+      !descriptor && state;
+      state = state.parent
+    ) {
+      descriptor = state.descriptor?.states[toState];
+    }
+    return this._newState(parent, toState, descriptor);
+  }
+
+  _update() {
+    if (this.status & STATUS_FINISHED) return false;
+    const nextState =
+      this.status !== STATUS_NONE
+        ? this.status & STATUS_ENTER
+          ? this._getSubstate(this.state, STATE_INITIAL)
+          : this._getSubstate(this.state?.parent, this.state?.key)
+        : this._newState(undefined, this.config.key, this.rootDescriptor);
+    if (nextState !== undefined) {
+      this.state = nextState;
+      this.status = this.status & STATUS_EXIT ? STATUS_NEXT : STATUS_FIRST;
+    } else {
+      if (this.status & STATUS_EXIT) {
+        this.state = this.state?.parent;
+        this.status = STATUS_LAST;
+      } else {
+        this.status = STATUS_LEAF;
+      }
+      if (!this.state) this.status = STATUS_FINISHED;
+    }
+    return !(this.status & STATUS_FINISHED);
+  }
+}

package/src/FsmState.ts

@@ -0,0 +1,87 @@
+import { bindMethods } from "./utils/bindMethods.ts";
+import { FsmBaseClass } from "./FsmBaseClass.ts";
+import { FsmProcess } from "./FsmProcess.ts";
+import { FsmStateDescriptor } from "./FsmStateDescriptor.ts";
+
+export type FsmStateDump = Record<string, any> & {
+  key: string;
+  data: Record<string, unknown>;
+};
+export type FsmStateHandler = (
+  state: FsmState,
+  ...args: unknown[]
+) => void | Promise<void>;
+
+export type FsmStateSyncHandler = (state: FsmState, ...args: unknown[]) => void;
+
+export type FsmStateDumpHandler = (
+  state: FsmState,
+  dump: FsmStateDump
+) => void | Promise<void>;
+
+export type FsmStateErrorHandler = (
+  state: FsmState,
+  error: any
+) => void | Promise<void>;
+
+export class FsmState extends FsmBaseClass {
+  process: FsmProcess;
+  key: string;
+  parent?: FsmState;
+  descriptor?: FsmStateDescriptor;
+
+  constructor(
+    process: FsmProcess,
+    parent: FsmState | undefined,
+    key: string,
+    descriptor?: FsmStateDescriptor
+  ) {
+    super();
+    this.process = process;
+    this.key = key;
+    this.parent = parent;
+    this.descriptor = descriptor;
+    bindMethods(
+      this,
+      "onEnter",
+      "onExit",
+      "dump",
+      "restore",
+      "useData",
+      "onStateError"
+    );
+  }
+
+  onEnter(handler: FsmStateHandler) {
+    return this._addHandler("onEnter", handler, true);
+  }
+  onExit(handler: FsmStateHandler) {
+    return this._addHandler("onExit", handler, false);
+  }
+  onStateError(handler: FsmStateErrorHandler) {
+    return this._addHandler("onStateError", handler);
+  }
+  dump(handler: FsmStateDumpHandler) {
+    return this._addHandler("dump", handler, true);
+  }
+  restore(handler: FsmStateDumpHandler) {
+    return this._addHandler("restore", handler, true);
+  }
+  getData<T>(key: string, recursive: boolean = true): T | undefined {
+    return (
+      (this.data[key] as T) ??
+      (recursive ? this.parent?.getData<T>(key, recursive) : undefined)
+    );
+  }
+  useData<T>(key: string) {
+    return [
+      (recursive: boolean = true) => this.getData<T>(key, recursive),
+      (value: T) => this.setData(key, value),
+    ];
+  }
+
+  async _handleError(error: Error | unknown) {
+    await this._runHandler("onStateError", this, error);
+    await this.process._handleStateError(this, error);
+  }
+}

package/src/FsmStateConfig.ts

@@ -0,0 +1,13 @@
+export const STATE_ANY = "*";
+export const STATE_INITIAL = "";
+export const STATE_FINAL = "";
+export const EVENT_ANY = "*";
+export const EVENT_EMPTY = "";
+
+export type FsmStateConfig = {
+  key: string;
+
+  transitions: [string, string, string][];
+
+  states?: FsmStateConfig[];
+};

package/src/FsmStateDescriptor.ts

@@ -0,0 +1,47 @@
+import {
+  type FsmStateConfig,
+  EVENT_ANY,
+  STATE_ANY,
+  STATE_FINAL,
+} from "./FsmStateConfig.ts";
+
+export class FsmStateDescriptor {
+  transitions: Record<string, Record<string, string>> = {};
+  states: Record<string, 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] || {});
+      index[event] = to;
+    }
+    if (config.states) {
+      for (const substateConfig of config.states) {
+        descriptor.states[substateConfig.key] = this.build(substateConfig);
+      }
+    }
+    return descriptor;
+  }
+
+  getTargetStateKey(stateKey: string, eventKey: string) {
+    const pairs = [
+      [stateKey, eventKey],
+      [STATE_ANY, eventKey],
+      [stateKey, EVENT_ANY],
+      [STATE_ANY, EVENT_ANY],
+    ];
+    let targetKey;
+    for (
+      let i = 0, len = pairs.length;
+      targetKey === undefined && i < len;
+      i++
+    ) {
+      const [stateKey, eventKey] = pairs[i];
+      const stateTransitions = this.transitions[stateKey];
+      if (!stateTransitions) continue;
+      targetKey = stateTransitions[eventKey];
+    }
+    return targetKey !== undefined ? targetKey : STATE_FINAL;
+  }
+}

package/src/context/handlers.ts

@@ -0,0 +1,30 @@
+import { FsmState, FsmStateHandler } from "../FsmState.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)) {
+    const list = (index[key] = index[key] || []);
+    list.push(handler);
+  }
+  state.setData(KEY_HANDLERS, index);
+}

package/src/context/index.ts

@@ -0,0 +1,3 @@
+export * from "./handlers.ts";
+export * from "./printer.ts";
+export * from "./tracer.ts";

package/src/context/printer.ts

@@ -0,0 +1,48 @@
+import { type FsmProcess } from "../FsmProcess.ts";
+import { type FsmState } from "../FsmState.ts";
+export type Printer = (...args: any[]) => void;
+export type PrinterConfig = {
+  prefix?: string;
+  print?: (...args: any[]) => void;
+  lineNumbers?: boolean;
+};
+
+export const KEY_PRINTER = "printer";
+
+export function preparePrinter(
+  process: FsmProcess,
+  { prefix = "", print = console.log, lineNumbers = false }: PrinterConfig
+): Printer {
+  let lineCounter = 0;
+  const shift = () => {
+    let prefix = "";
+    for (let s = process.state?.parent; !!s; s = s.parent) {
+      prefix += "  ";
+    }
+    return prefix;
+  };
+  const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;
+  const printer = (...args: string[]) => print(prefix, getPrefix(), ...args);
+  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);
+}
+
+export function getPrinter(state: FsmState): Printer {
+  return (
+    state.getData(KEY_PRINTER, true) ||
+    state.process.getData(KEY_PRINTER) ||
+    console.log
+  );
+}

package/src/context/tracer.ts

@@ -0,0 +1,19 @@
+import { FsmProcess } from "../FsmProcess.ts";
+import { FsmState } from "../FsmState.ts";
+import { getPrinter, type Printer } from "./printer.ts";
+
+export function setProcessTracer(process: FsmProcess, print?: Printer) {
+  return process.onStateCreate((state) => {
+    setStateTracer(state, print);
+  });
+}
+
+export function setStateTracer(state: FsmState, print?: Printer) {
+  const printLine = print || getPrinter(state);
+  state.onEnter(() => {
+    printLine(`<${state?.key} event="${state.process.event}">`);
+  });
+  state.onExit(() => {
+    printLine(`</${state.key}> <!-- event="${state.process.event}" -->`);
+  });
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./FsmProcess.ts";
+export * from "./FsmState.ts";
+export * from "./FsmStateConfig.ts";
+export * from "./FsmStateDescriptor.ts";
+export * from "./context/index.ts";

package/src/utils/bindMethods.ts

@@ -0,0 +1,7 @@
+export function bindMethods<T>(obj: T, ...methods: string[]) {
+  const o = obj as any;
+  methods.forEach((methodName) => {
+    o[methodName] = (o[methodName] as Function).bind(o);
+  });
+  return obj;
+}