@statewalker/fsm 0.16.0 → 0.20.0

package/dist/index.js

@@ -1,295 +1,373 @@
-// @statewalker/fsm v0.16.0 https://github.com/statewalker/statewalker-fsm Copyright 2022 Mikhail Kotelnikov
-import { MODE, newAsyncTreeWalker, newTreeWalker } from '@statewalker/tree';
+// src/utils/bindMethods.ts
+function bindMethods(obj, ...methods) {
+  const o = obj;
+  methods.forEach((methodName) => {
+    o[methodName] = o[methodName].bind(o);
+  });
+  return obj;
+}
 
-function buildStateDescriptor(config = {}) {
-  const { key, transitions = [], states = {}, options, ...params } = config;
-  const result = {
-    key,
-    transitions: {},
-    states: {},
-    options: Object.assign(options || {}, params)
-  };
-  for (const t of transitions) {
-    let stateKey, eventKey, targetStateKey;
-    if (Array.isArray(t)) {
-      stateKey = t[0];
-      eventKey = t[1];
-      targetStateKey = t[2];
+// src/FsmBaseClass.ts
+var FsmBaseClass = class {
+  handlers = {};
+  data = {};
+  constructor() {
+    bindMethods(this, "setData", "getData");
+  }
+  setData(key, value) {
+    this.data[key] = value;
+    return this;
+  }
+  getData(key) {
+    return this.data[key];
+  }
+  // ----------------------------------------------
+  // internal methods
+  _addHandler(type, handler, direct = true) {
+    const list = this.handlers[type] = this.handlers[type] || [];
+    direct ? list.push(handler) : list.unshift(handler);
+    return () => this._removeHandler(type, handler);
+  }
+  _removeHandler(type, handler) {
+    let list = this.handlers[type];
+    if (!list)
+      return;
+    list = list.filter((h) => h !== handler);
+    if (list.length > 0) {
+      this.handlers[type] = list;
     } else {
-      const { from, event, to } = t;
-      stateKey = from;
-      eventKey = event;
-      targetStateKey = to;
+      delete this.handlers[type];
     }
-    const index = result.transitions[stateKey] = result.transitions[stateKey] || {};
-    index[eventKey] = targetStateKey;
   }
-  if (Array.isArray(states)) {
-    for (const s of states) {
-      result.states[s.key] = buildStateDescriptor(s);
-    }
-  } else if (states) {
-    for (const key of Object.keys(states)) {
-      result.states[key] = buildStateDescriptor(states[key]);
+  _runHandlerSync(type, ...args) {
+    const list = this.handlers[type] || [];
+    return list.map((handler) => handler(...args));
+  }
+  async _runHandler(type, ...args) {
+    const promises = this._runHandlerSync(type, ...args);
+    for (const promise of promises) {
+      try {
+        await promise;
+      } catch (error) {
+        await this._handleError(error);
+      }
     }
   }
-  return result;
-}
+  async _handleError(error) {
+    console.error(error);
+  }
+};
 
-var KEYS = {
-  STATE_ANY : "*",
-  STATE_INITIAL : "",
-  STATE_FINAL : "",
-  EVENT_ANY : "*",
-  EVENT_EMPTY : "",
+// src/FsmState.ts
+var FsmState = class extends FsmBaseClass {
+  process;
+  key;
+  parent;
+  descriptor;
+  constructor(process, parent, key, descriptor) {
+    super();
+    this.process = process;
+    this.key = key;
+    this.parent = parent;
+    this.descriptor = descriptor;
+    bindMethods(
+      this,
+      "onEnter",
+      "onExit",
+      "dump",
+      "restore",
+      "useData",
+      "onStateError"
+    );
+  }
+  onEnter(handler) {
+    return this._addHandler("onEnter", handler, true);
+  }
+  onExit(handler) {
+    return this._addHandler("onExit", handler, false);
+  }
+  onStateError(handler) {
+    return this._addHandler("onStateError", handler);
+  }
+  dump(handler) {
+    return this._addHandler("dump", handler, true);
+  }
+  restore(handler) {
+    return this._addHandler("restore", handler, true);
+  }
+  getData(key, recursive = true) {
+    return this.data[key] ?? (recursive ? this.parent?.getData(key, recursive) : void 0);
+  }
+  useData(key) {
+    return [
+      (recursive = true) => this.getData(key, recursive),
+      (value) => this.setData(key, value)
+    ];
+  }
+  async _handleError(error) {
+    await this._runHandler("onStateError", this, error);
+    await this.process._handleStateError(this, error);
+  }
 };
 
-function checkProcessDescriptor(descriptor) {
-  return checkStateDescriptor(descriptor);
+// src/FsmStateConfig.ts
+var STATE_ANY = "*";
+var STATE_INITIAL = "";
+var STATE_FINAL = "";
+var EVENT_ANY = "*";
+var EVENT_EMPTY = "";
 
-  function checkStateDescriptor(descriptor, report = [], stack = []) {
-    stack = [...stack, descriptor.key];
-    const result = Object.assign({ key: descriptor.key }, checkStateTransitions(descriptor));
-    if (result.deadendStates.length || result.unreachableStates.length) {
-      const info = { path: stack };
-      report.push(info);
-      if (result.deadendStates.length) info.deadendStates = result.deadendStates;
-      if (result.unreachableStates.length) info.unreachableStates = result.unreachableStates;
+// src/FsmStateDescriptor.ts
+var FsmStateDescriptor = class _FsmStateDescriptor {
+  transitions = {};
+  states = {};
+  static build(config) {
+    const descriptor = new _FsmStateDescriptor();
+    for (const [from, event, to] of config.transitions) {
+      const index = descriptor.transitions[from] = descriptor.transitions[from] || {};
+      index[event] = to;
     }
-    for (const subDescriptor of Object.values(descriptor.states)) {
-      checkStateDescriptor(subDescriptor, report, stack);
+    if (config.states) {
+      for (const substateConfig of config.states) {
+        descriptor.states[substateConfig.key] = this.build(substateConfig);
+      }
     }
-    return report;
+    return descriptor;
   }
-
-  function checkStateTransitions(descriptor) {
-    const sourceStates = {};
-    const targetStates = {};
-    for (const [from, destinations] of Object.entries(descriptor.transitions)) {
-      sourceStates[from] = (sourceStates[from] || 0) + 1;
-      for (const targetKey of Object.values(destinations)) {
-        targetStates[targetKey] = (targetStates[targetKey] || 0) + 1;
-      }
+  getTargetStateKey(stateKey, eventKey) {
+    const pairs = [
+      [stateKey, eventKey],
+      [STATE_ANY, eventKey],
+      [stateKey, EVENT_ANY],
+      [STATE_ANY, EVENT_ANY]
+    ];
+    let targetKey;
+    for (let i = 0, len = pairs.length; targetKey === void 0 && i < len; i++) {
+      const [stateKey2, eventKey2] = pairs[i];
+      const stateTransitions = this.transitions[stateKey2];
+      if (!stateTransitions)
+        continue;
+      targetKey = stateTransitions[eventKey2];
     }
-    // Unreachable states - no transitions leading to these states
-    const unreachableStates = [];
-    // Deadend states - no transitions from these states
-    const deadendStates = [];
+    return targetKey !== void 0 ? targetKey : STATE_FINAL;
+  }
+};
 
-    // Unreachable states - no transitions leading to these states
-    for (const sourceKey of Object.keys(sourceStates)) {
-      if (sourceKey !== KEYS.STATE_ANY &&
-        sourceKey !== KEYS.STATE_FINAL &&
-        sourceKey !== KEYS.STATE_INITIAL &&
-        !(sourceKey in targetStates)) {
-        unreachableStates.push(sourceKey);
+// src/FsmProcess.ts
+var STATUS_NONE = 0;
+var STATUS_FIRST = 1;
+var STATUS_NEXT = 2;
+var STATUS_LEAF = 4;
+var STATUS_LAST = 8;
+var STATUS_FINISHED = 16;
+var STATUS_ENTER = STATUS_FIRST | STATUS_NEXT;
+var STATUS_EXIT = STATUS_LEAF | STATUS_LAST;
+var FsmProcess = class extends FsmBaseClass {
+  state;
+  event;
+  status = 0;
+  config;
+  rootDescriptor;
+  constructor(config) {
+    super();
+    this.rootDescriptor = FsmStateDescriptor.build(config);
+    this.config = config;
+    bindMethods(this, "dispatch", "dump", "restore");
+  }
+  async dispatch(event, mask = STATUS_LEAF) {
+    this.event = event;
+    while (true) {
+      if (this.status & STATUS_EXIT) {
+        await this.state?._runHandler("onExit", this.state);
       }
-    }
-
-    // Deadend states - no transitions from these states
-    for (const targetKey of Object.keys(targetStates)) {
-      if (targetKey !== KEYS.STATE_FINAL && !(targetKey in sourceStates)) {
-        deadendStates.push(targetKey);
+      if (!this._update())
+        return false;
+      if (this.status & STATUS_ENTER) {
+        await this.state?._runHandler("onEnter", this.state);
       }
+      if (this.status & mask)
+        return true;
     }
-
-    return { unreachableStates, deadendStates }
   }
-}
-
-function getStateDescriptor(process, stateKey) {
-  let descriptor;
-  for (let i = process.stack.length - 1; !descriptor && i >= 0; i--) {
-    const states = process.stack[i].descriptor.states || {};
-    descriptor = states[stateKey];
+  async dump(...args) {
+    const dumpState = async (state) => {
+      const stateDump = {
+        key: state.key,
+        data: {}
+      };
+      await state._runHandler("dump", state, stateDump.data, ...args);
+      return stateDump;
+    };
+    const dumpStates = async (state, stack = []) => {
+      if (!state)
+        return stack;
+      state.parent && await dumpStates(state.parent, stack);
+      stack.push(await dumpState(state));
+      return stack;
+    };
+    const dump = {
+      status: this.status,
+      event: this.event,
+      stack: await dumpStates(this.state)
+    };
+    return dump;
   }
-  return descriptor || { transitions: {}, states: {} };
-}
-
-/**
- * This method returns a list of all states used in 
- * the specified state descriptor.
- * 
- * @param {object} descriptor compiled state descriptor
- * defining transitions between sub-states and sub-states
- * @returns a sorted list of all states 
- */
-function getAllStateKeys(descriptor) {
-  const index = {};
-  const add = (key) => index[key] = (index[key] || 0) + 1;
-  visit(descriptor);
-  return Object.keys(index).sort();
-  function visit(descriptor) {
-    add(descriptor.key);
-    for (const [from, destinations] of Object.entries(descriptor.transitions)) {
-      add(from);
-      for (const targetKey of Object.values(destinations)) {
-        add(targetKey);
-      }
+  async restore(dump, ...args) {
+    this.status = dump.status || 0;
+    this.event = dump.event;
+    this.state = void 0;
+    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(void 0, stateDump.key, this.rootDescriptor);
+      await this.state._runHandler(
+        "restore",
+        this.state,
+        stateDump.data,
+        ...args
+      );
     }
-    for (const [stateKey, stateDescriptor] of Object.entries(descriptor.states)) {
-      add(stateKey);
-      visit(stateDescriptor);
+    return this;
+  }
+  onStateCreate(handler) {
+    return this._addHandler("onStateCreate", handler, true);
+  }
+  onStateError(handler) {
+    return this._addHandler("onStateError", handler);
+  }
+  async _handleStateError(state, error) {
+    await this._runHandler("onStateError", state, error);
+    this._handleError(error);
+  }
+  _newState(parent, key, descriptor) {
+    const state = new FsmState(this, parent, key, descriptor);
+    this._runHandlerSync("onStateCreate", state);
+    return state;
+  }
+  _getSubstate(parent, prevStateKey) {
+    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, toState) {
+    let descriptor;
+    for (let state = parent; !descriptor && state; state = state.parent) {
+      descriptor = state.descriptor?.states[toState];
     }
+    return this._newState(parent, toState, descriptor);
   }
-}
-
-function getTargetStateKey(descriptor, stateKey, eventKey) {
-  const pairs = [
-    [stateKey, eventKey],
-    [KEYS.STATE_ANY, eventKey],
-    [stateKey, KEYS.EVENT_ANY],
-    [KEYS.STATE_ANY, KEYS.EVENT_ANY]
-  ];
-  let targetKey;
-  for (let i = 0, len = pairs.length; (targetKey === undefined) && i < len; i++) {
-    const [stateKey, eventKey] = pairs[i];
-    const stateTransitions = descriptor.transitions[stateKey];
-    if (!stateTransitions) continue;
-    targetKey = stateTransitions[eventKey];
-  }
-  return (targetKey !== undefined) ? targetKey : KEYS.STATE_FINAL;
-}
-
-function newProcessInstance({
-  config,
-  descriptor,
-  newState = (obj) => obj,
-  newProcess = (descriptor) => ({
-    descriptor,
-    status: 0,
-    stack: [],
-    event: undefined,
-    current: undefined
-  })
-}) {
-  descriptor = descriptor || buildStateDescriptor(config);
-  const process = newProcess(descriptor);
-  const loadNextState = () => {
-    let key, descriptor;
-    if (!process.status) {
-      descriptor = process.descriptor;
-      key = descriptor.key;
+  _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(void 0, this.config.key, this.rootDescriptor);
+    if (nextState !== void 0) {
+      this.state = nextState;
+      this.status = this.status & STATUS_EXIT ? STATUS_NEXT : STATUS_FIRST;
     } else {
-      if (!process.stack.length) {
-        key = KEYS.STATE_FINAL;
+      if (this.status & STATUS_EXIT) {
+        this.state = this.state?.parent;
+        this.status = STATUS_LAST;
       } else {
-        const eventKey = process.event.key || KEYS.EVENT_EMPTY;
-        const parentDescriptor = process.stack[process.stack.length - 1].descriptor;
-        const stateKey = process.status & MODE.ENTER
-          ? KEYS.STATE_INITIAL
-          : process.current ? process.current.key : KEYS.STATE_FINAL;
-        key = getTargetStateKey(parentDescriptor, stateKey, eventKey);
-        if (key) {
-          descriptor = getStateDescriptor(process, key);
-        }
+        this.status = STATUS_LEAF;
       }
+      if (!this.state)
+        this.status = STATUS_FINISHED;
     }
-    return key ? newState({ process, key, descriptor }) : null;
-  };
-  return [process, loadNextState];
-}
+    return !(this.status & STATUS_FINISHED);
+  }
+};
 
-function newAsyncProcess({
-  config,
-  descriptor,
-  before, after,
-  newProcess,
-  newState,
-  handleError = console.error
-}) {
-  const [process, loadNextState] = newProcessInstance({
-    config,
-    descriptor,
-    newProcess,
-    newState
-  });
-  const shift = newAsyncTreeWalker(before, after, process);
-  process.finished = false;
-  process.next = (event) => {
-    process.nextEvent = event;
-    return process.running = process.running || Promise
-      .resolve()
-      .then(async () => {
-        try {
-          process.event = process.nextEvent;
-          process.nextEvent = undefined;
-          while (!process.finished && process.event) {
-            process.finished = !await shift(loadNextState);
-            if ((process.status & MODE.EXIT) && process.nextEvent) {
-              // Consume the next event if it exists.
-              process.event = process.nextEvent;
-              process.nextEvent = undefined;
-            } else if (process.status & MODE.LEAF) {
-              // Returns control when the process is in a "leaf" state (a state without children)
-              break;
-            }
-          }
-        } catch (error) {
-          handleError(error);
-        }
-      })
-      .finally(() => process.running = undefined)
-      .then(() => !process.finished);
-  };
-  return process;
+// src/context/handlers.ts
+var KEY_HANDLERS = "handlers";
+function callStateHandlers(state) {
+  const key = state.key;
+  for (let parent = state.parent; !!parent; parent = parent?.parent) {
+    const handlers = parent.getData(KEY_HANDLERS)?.[key];
+    handlers?.forEach((handler) => handler(state));
+  }
 }
-
-/**
- * Returns all possible transitions from the current state of the process.
- * @param {Object} options - method parameters
- * @param {Process} options.process - the current process for which 
- * all transitions should be returned
- * @returns {Array<Object>} - an array of all transitions;
- * each entry in this returned array contains the following keys:
- * 1) parentStateKey - key of the state where the transition can be activated
- * 2) sourceStateKey - the initial transition state
- * 3) eventKey - key of the event activating transition
- * 4) targetStateKey - the resulting state for this transition
- * 
- */
-function getAllTransitions(process) {
-  const list = [];
-  let stateKey = process.current ? process.current.key : KEYS.STATE_INITIAL;
-  for (let i = process.stack.length - 1; i >= 0; i--) {
-    const parentState = process.stack[i];
-    const parentStateKey = parentState.key;
-    const descriptor = parentState.descriptor;
-    for (const sKey of [stateKey, KEYS.STATE_ANY]) {
-      const stateTransitions = descriptor.transitions[sKey];
-      if (!stateTransitions) continue;
-      for (const[eventKey, targetKey] of Object.entries(stateTransitions)) {
-        list.push([parentStateKey, sKey, eventKey, targetKey]);
-      }
-    }
-    stateKey = parentStateKey;
+function addSubstateHandlers(state, handlers) {
+  const oldIndex = state.getData(KEY_HANDLERS);
+  const index = oldIndex ? { ...oldIndex } : {};
+  for (const [key, handler] of Object.entries(handlers)) {
+    const list = index[key] = index[key] || [];
+    list.push(handler);
   }
-  return list;
+  state.setData(KEY_HANDLERS, index);
 }
 
-function newSyncProcess({
-  config,
-  descriptor,
-  before, after,
-  newProcess,
-  newState,
-}) {
-  const [process, loadNextState] = newProcessInstance({
-    config,
-    descriptor,
-    newProcess,
-    newState,
-  });
-  const shift = newTreeWalker(before, after, process);
-  process.dispatch = process.next = (event) => {
-    if (typeof event === 'string') event = { key : event };
-    process.event = event;
-    while (process.event) {
-      if (!shift(loadNextState)) return false;
-      if (process.status & MODE.LEAF) return true;
+// src/context/printer.ts
+var KEY_PRINTER = "printer";
+function preparePrinter(process, { prefix = "", print = console.log, lineNumbers = false }) {
+  let lineCounter = 0;
+  const shift = () => {
+    let prefix2 = "";
+    for (let s = process.state?.parent; !!s; s = s.parent) {
+      prefix2 += "  ";
     }
+    return prefix2;
   };
-  return process;
+  const getPrefix = lineNumbers ? () => `[${++lineCounter}]${shift()}` : shift;
+  const printer = (...args) => print(prefix, getPrefix(), ...args);
+  return printer;
+}
+function setPrinter(state, config = {}) {
+  const printer = preparePrinter(state.process, config);
+  state.setData(KEY_PRINTER, printer);
+}
+function setProcessPrinter(process, config = {}) {
+  const printer = preparePrinter(process, config);
+  process.setData(KEY_PRINTER, printer);
+}
+function getPrinter(state) {
+  return state.getData(KEY_PRINTER, true) || state.process.getData(KEY_PRINTER) || console.log;
 }
 
-export { KEYS, buildStateDescriptor, checkProcessDescriptor, getAllStateKeys, getAllTransitions, getStateDescriptor, getTargetStateKey, newAsyncProcess, newProcessInstance, newSyncProcess };
+// src/context/tracer.ts
+function setProcessTracer(process, print) {
+  return process.onStateCreate((state) => {
+    setStateTracer(state, print);
+  });
+}
+function setStateTracer(state, print) {
+  const printLine = print || getPrinter(state);
+  state.onEnter(() => {
+    printLine(`<${state?.key} event="${state.process.event}">`);
+  });
+  state.onExit(() => {
+    printLine(`</${state.key}> <!-- event="${state.process.event}" -->`);
+  });
+}
+export {
+  EVENT_ANY,
+  EVENT_EMPTY,
+  FsmProcess,
+  FsmState,
+  FsmStateDescriptor,
+  KEY_HANDLERS,
+  KEY_PRINTER,
+  STATE_ANY,
+  STATE_FINAL,
+  STATE_INITIAL,
+  STATUS_ENTER,
+  STATUS_EXIT,
+  STATUS_FINISHED,
+  STATUS_FIRST,
+  STATUS_LAST,
+  STATUS_LEAF,
+  STATUS_NEXT,
+  STATUS_NONE,
+  addSubstateHandlers,
+  callStateHandlers,
+  getPrinter,
+  preparePrinter,
+  setPrinter,
+  setProcessPrinter,
+  setProcessTracer,
+  setStateTracer
+};