@vsirotin/ts-stop 0.5.1 → 0.6.0

package/lib/sfsm/Sfsm.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sfsm = void 0;
+const FaResolver_1 = require("./FaResolver");
+/**
+ * Stacked Finite State Machine engine.
+ *
+ * Usage:
+ *   const sfsm = new Sfsm(options);
+ *   sfsm.setCommandReceiver(receiver);
+ *   sfsm.loadFA(definition);   // auto-activates state I of root FA
+ *   sfsm.receiveSignal('TS.s');
+ *
+ * Signal re-entrancy: if receiveSignal is called while the engine is already
+ * processing a signal (e.g. from within a command receiver callback), the
+ * incoming signal is queued and processed after the current step completes.
+ * This prevents stack corruption and ensures deterministic ordering.
+ */
+class Sfsm {
+    constructor(options = {}) {
+        var _a, _b;
+        this.resolver = null;
+        this.stack = [];
+        this.commandReceiver = null;
+        this.log = [];
+        this.processing = false;
+        this.signalQueue = [];
+        this.options = {
+            byMissingData: (_a = options.byMissingData) !== null && _a !== void 0 ? _a : 'error',
+            byMissingTransition: (_b = options.byMissingTransition) !== null && _b !== void 0 ? _b : 'error'
+        };
+    }
+    /** Register the single command receiver for this SFSM instance. */
+    setCommandReceiver(receiver) {
+        this.commandReceiver = receiver;
+    }
+    /**
+     * Load a FA definition and initialise the engine.
+     * The root FA is pushed onto the stack with active state "I".
+     * No signal is sent automatically — the caller is responsible for
+     * sending the first signal (e.g. "TS.s") to drive out of state I.
+     */
+    loadFA(definition) {
+        this.resolver = new FaResolver_1.FaResolver(definition);
+        const rootName = this.resolver.getRootName();
+        this.stack = [{ faName: rootName, currentState: 'I' }];
+        this.log = [];
+        this.processing = false;
+        this.signalQueue = [];
+    }
+    /**
+     * Send a signal to the SFSM.
+     * If called re-entrantly (from within a command receiver), the signal
+     * is queued and will be processed after the current step finishes.
+     */
+    receiveSignal(signal, data) {
+        if (this.processing) {
+            this.signalQueue.push({ signal, data });
+            return;
+        }
+        this.processSignal(signal, data);
+        // Drain queue
+        while (this.signalQueue.length > 0) {
+            const next = this.signalQueue.shift();
+            this.processSignal(next.signal, next.data);
+        }
+    }
+    /** Returns the accumulated log entries. */
+    getLog() {
+        return [...this.log];
+    }
+    /** Returns the current FA name stack (bottom = index 0, head = last). */
+    getCurrentStack() {
+        return this.stack.map(f => f.faName);
+    }
+    /** Returns the active state of the head FA. */
+    getHeadState() {
+        if (this.stack.length === 0)
+            throw new Error('SFSM: not initialised');
+        return this.stack[this.stack.length - 1].currentState;
+    }
+    // ── Core engine ─────────────────────────────────────────────────────────
+    processSignal(signal, data) {
+        if (!this.resolver || this.stack.length === 0) {
+            throw new Error('SFSM: call loadFA() before sending signals');
+        }
+        this.processing = true;
+        try {
+            this.applySignal(signal, data);
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+    /**
+     * Rule 2: find a matching transition, searching from head down the stack.
+     * Returns { frameIndex, transition } or null if not found anywhere.
+     */
+    findTransition(signal) {
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const frame = this.stack[i];
+            const fa = this.resolver.get(frame.faName);
+            const match = fa.transitions.find(t => t[0] === frame.currentState && t[1] === signal);
+            if (match) {
+                return { frameIndex: i, toState: match[2], command: match[3] };
+            }
+        }
+        return null;
+    }
+    applySignal(signal, data) {
+        var _a, _b, _c, _d;
+        const result = this.findTransition(signal);
+        if (!result) {
+            // Rule 2.2.1 — no transition found anywhere
+            this.handleMissingTransition(signal);
+            return;
+        }
+        const { frameIndex, toState, command } = result;
+        // Capture stack state BEFORE any structural changes
+        const stackBefore = this.getCurrentStack();
+        const stateBefore = this.stack[frameIndex].currentState;
+        // Bubble-up: signal was handled by an ancestor FA, not the head
+        const bubbledUp = frameIndex < this.stack.length - 1;
+        // Rule 2.2.2.1 — pop frames above the matched FA
+        if (bubbledUp) {
+            this.stack.splice(frameIndex + 1);
+        }
+        // Update state
+        this.stack[frameIndex].currentState = toState;
+        // Rule label: 2.1 = head FA handled signal; 2.2.2.1 = ancestor handled after bubble-up
+        const rule = bubbledUp ? '2.2.2.1' : '2.1';
+        // Rule 2.1.1 — send command if present
+        let sentCommand;
+        let commandName;
+        let receiver;
+        if (command) {
+            sentCommand = command;
+            const meta = this.resolveCommandMeta(frameIndex, command);
+            commandName = meta === null || meta === void 0 ? void 0 : meta.name;
+            receiver = meta === null || meta === void 0 ? void 0 : meta.receiver;
+            const commandData = command.endsWith('$') ? data : undefined;
+            if (command.endsWith('$') && data === undefined) {
+                this.handleMissingData(signal, command);
+            }
+            (_a = this.commandReceiver) === null || _a === void 0 ? void 0 : _a.receiveCommand(command, commandData);
+        }
+        const logEntry = {
+            step: this.log.length + 1,
+            stack: stackBefore,
+            state: stateBefore,
+            stateName: (_b = this.resolveStateMeta(frameIndex, stateBefore)) === null || _b === void 0 ? void 0 : _b.name,
+            signal,
+            signalName: (_c = this.resolveSignalMeta(frameIndex, signal)) === null || _c === void 0 ? void 0 : _c.name,
+            rule,
+            newStack: this.getCurrentStack(),
+            newState: toState,
+            newStateName: (_d = this.resolveStateMeta(frameIndex, toState)) === null || _d === void 0 ? void 0 : _d.name,
+            command: sentCommand,
+            commandName,
+            receiver
+        };
+        this.log.push(logEntry);
+        // Rule 3: new state is itself a sub-FA — push it
+        const headFa = this.resolver.get(this.stack[frameIndex].faName);
+        if (headFa.subFaNames.has(toState)) {
+            this.stack.push({ faName: toState, currentState: 'I' });
+            this.applySignal(signal, data); // forward signal to sub-FA
+            return;
+        }
+        // Rule 4: new state is an exit state
+        if (toState.startsWith('E_')) {
+            if (this.stack.length === 1) {
+                // Rule 4.1 — root FA resets to I
+                this.stack[0].currentState = 'I';
+            }
+            else {
+                // Rule 4.2 — pop current FA, forward signal to new head
+                this.stack.pop();
+                this.applySignal(signal, data);
+            }
+        }
+    }
+    // ── Meta resolution helpers ──────────────────────────────────────────────
+    resolveStateMeta(frameIndex, state) {
+        var _a;
+        const fa = this.resolver.get(this.stack[frameIndex].faName);
+        return (_a = fa.node.states) === null || _a === void 0 ? void 0 : _a[state];
+    }
+    resolveSignalMeta(frameIndex, signal) {
+        var _a;
+        // Search from head FA downward for signal metadata
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const fa = this.resolver.get(this.stack[i].faName);
+            if ((_a = fa.node.signals) === null || _a === void 0 ? void 0 : _a[signal])
+                return fa.node.signals[signal];
+        }
+        return undefined;
+    }
+    resolveCommandMeta(frameIndex, command) {
+        var _a;
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const fa = this.resolver.get(this.stack[i].faName);
+            if ((_a = fa.node.commands) === null || _a === void 0 ? void 0 : _a[command])
+                return fa.node.commands[command];
+        }
+        return undefined;
+    }
+    // ── Policy handlers ──────────────────────────────────────────────────────
+    handleMissingTransition(signal) {
+        var _a;
+        const policy = (_a = this.options.byMissingTransition) !== null && _a !== void 0 ? _a : 'error';
+        const msg = `SFSM: no transition for signal "${signal}" in state "${this.getHeadState()}" (FA: ${this.getCurrentStack().join('>')})`;
+        if (policy === 'error')
+            throw new Error(msg);
+        if (policy === 'log_warning')
+            console.warn(msg);
+        // 'ignore': do nothing
+    }
+    handleMissingData(signal, command) {
+        var _a;
+        const policy = (_a = this.options.byMissingData) !== null && _a !== void 0 ? _a : 'error';
+        const msg = `SFSM: command "${command}" expects data but signal "${signal}" carries none`;
+        if (policy === 'error')
+            throw new Error(msg);
+        if (policy === 'log_warning')
+            console.warn(msg);
+    }
+}
+exports.Sfsm = Sfsm;
+//# sourceMappingURL=Sfsm.js.map

package/lib/sfsm/Sfsm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sfsm.js","sourceRoot":"","sources":["../../src/sfsm/Sfsm.ts"],"names":[],"mappings":"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"}

package/lib/sfsm/index.d.ts

@@ -0,0 +1,9 @@
+export { ICommandReceiver, ISignalReceiver, ISignalSender } from './interfaces';
+export { ExternalWorldHub } from './ExternalWorldHub';
+export { FaDefinition, FaNode, FaUpdate, Transition, SfsmOptions, LogEntry, MissingDataPolicy, MissingTransitionPolicy } from './types';
+export { FaResolver, ResolvedFa } from './FaResolver';
+export { Sfsm } from './Sfsm';
+export { reduceFA } from './FaReducer';
+export { updateCompactFA, updateFullFA } from './FaUpdater';
+export { loadFAFromFile, loadFAFromURL } from './FaLoader';
+//# sourceMappingURL=index.d.ts.map

package/lib/sfsm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sfsm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AACxI,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/lib/sfsm/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadFAFromURL = exports.loadFAFromFile = exports.updateFullFA = exports.updateCompactFA = exports.reduceFA = exports.Sfsm = exports.FaResolver = exports.ExternalWorldHub = void 0;
+var ExternalWorldHub_1 = require("./ExternalWorldHub");
+Object.defineProperty(exports, "ExternalWorldHub", { enumerable: true, get: function () { return ExternalWorldHub_1.ExternalWorldHub; } });
+var FaResolver_1 = require("./FaResolver");
+Object.defineProperty(exports, "FaResolver", { enumerable: true, get: function () { return FaResolver_1.FaResolver; } });
+var Sfsm_1 = require("./Sfsm");
+Object.defineProperty(exports, "Sfsm", { enumerable: true, get: function () { return Sfsm_1.Sfsm; } });
+var FaReducer_1 = require("./FaReducer");
+Object.defineProperty(exports, "reduceFA", { enumerable: true, get: function () { return FaReducer_1.reduceFA; } });
+var FaUpdater_1 = require("./FaUpdater");
+Object.defineProperty(exports, "updateCompactFA", { enumerable: true, get: function () { return FaUpdater_1.updateCompactFA; } });
+Object.defineProperty(exports, "updateFullFA", { enumerable: true, get: function () { return FaUpdater_1.updateFullFA; } });
+var FaLoader_1 = require("./FaLoader");
+Object.defineProperty(exports, "loadFAFromFile", { enumerable: true, get: function () { return FaLoader_1.loadFAFromFile; } });
+Object.defineProperty(exports, "loadFAFromURL", { enumerable: true, get: function () { return FaLoader_1.loadFAFromURL; } });
+//# sourceMappingURL=index.js.map

package/lib/sfsm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sfsm/index.ts"],"names":[],"mappings":";;;AACA,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,2CAAsD;AAA7C,wGAAA,UAAU,OAAA;AACnB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA;AACjB,yCAA4D;AAAnD,4GAAA,eAAe,OAAA;AAAE,yGAAA,YAAY,OAAA;AACtC,uCAA2D;AAAlD,0GAAA,cAAc,OAAA;AAAE,yGAAA,aAAa,OAAA"}

package/lib/sfsm/interfaces.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Interface for objects that can receive commands from the SFSM.
+ * Implement this interface for any device in the "external world" that the SFSM controls.
+ */
+export interface ICommandReceiver {
+    receiveCommand(command: string, data?: unknown): void;
+}
+/**
+ * Interface for objects that can receive signals.
+ * The SFSM implements this interface — external senders call receiveSignal() to drive it.
+ */
+export interface ISignalReceiver {
+    receiveSignal(signal: string, data?: unknown): void;
+}
+/**
+ * Interface for external objects that send signals to the SFSM.
+ * ExternalWorldHub calls connectSignalTarget() on every registered sender during connectTo().
+ */
+export interface ISignalSender {
+    connectSignalTarget(target: ISignalReceiver): void;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/sfsm/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/sfsm/interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CACtD"}

package/lib/sfsm/interfaces.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=interfaces.js.map

package/lib/sfsm/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/sfsm/interfaces.ts"],"names":[],"mappings":""}

package/lib/sfsm/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A transition in compact (runtime) format: [from, signal, to] or [from, signal, to, command]
+ */
+export type Transition = [string, string, string] | [string, string, string, string];
+/**
+ * Metadata for a named element (state, signal, or command) in extended format.
+ */
+export interface ElementMeta {
+    name: string;
+    description?: string;
+    sender?: string;
+    receiver?: string;
+}
+/**
+ * A node in the FA tree. Can represent either the root FA or a nested sub-FA.
+ *
+ * In compact format: the entire FaDefinition value is just a Transition[].
+ * In extended format: this object contains states, signals, commands, and ts.
+ *
+ * A state entry under "states" is either:
+ *  - another FaNode (if it has a "ts" key) — a sub-FA
+ *  - an ElementMeta (a leaf state with name/description only)
+ */
+export interface FaNode {
+    states?: Record<string, FaNode | ElementMeta>;
+    signals?: Record<string, ElementMeta>;
+    commands?: Record<string, ElementMeta>;
+    ts: Transition[];
+}
+/**
+ * The top-level FA definition object.
+ * Key = root FA name, value = FaNode (extended) or Transition[] (compact).
+ */
+export type FaDefinition = Record<string, FaNode | Transition[]>;
+/**
+ * An update descriptor applied by updateCompactFA or updateFullFA.
+ * - remove: list of FA names to remove (children only; parent ts is cleaned automatically)
+ * - add: map of FA name → new definition; existing entries are replaced, new ones inserted
+ */
+export interface FaUpdate {
+    remove?: string[];
+    add?: Record<string, FaNode | Transition[]>;
+}
+/**
+ * How the SFSM reacts when a data-carrying command has no data available in the signal.
+ */
+export type MissingDataPolicy = 'ignore' | 'log_warning' | 'error';
+/**
+ * How the SFSM reacts when no matching transition is found for a (state, signal) pair.
+ */
+export type MissingTransitionPolicy = 'ignore' | 'log_warning' | 'error';
+/**
+ * Configuration options for the SFSM engine.
+ */
+export interface SfsmOptions {
+    byMissingData?: MissingDataPolicy;
+    byMissingTransition?: MissingTransitionPolicy;
+}
+/**
+ * A single entry in the processing log.
+ * Fields marked (e) are only populated when the FA is in extended format.
+ */
+export interface LogEntry {
+    step: number;
+    stack: string[];
+    state: string;
+    stateName?: string;
+    signal: string;
+    signalName?: string;
+    rule: string;
+    newStack: string[];
+    newState: string;
+    newStateName?: string;
+    command?: string;
+    commandName?: string;
+    receiver?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/sfsm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sfsm/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,EAAE,EAAE,UAAU,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/lib/sfsm/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/sfsm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sfsm/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsirotin/ts-stop",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "State Oriented Programming library for TypeScript",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -10,6 +10,11 @@
       "types": "./lib/index.d.ts",
       "import": "./lib/esm/index.js",
       "require": "./lib/index.js"
+    },
+    "./sfsm": {
+      "types": "./lib/sfsm/index.d.ts",
+      "import": "./lib/esm/sfsm/index.js",
+      "require": "./lib/sfsm/index.js"
     }
   },
   "files": [
@@ -23,7 +28,10 @@
     "test:coverage": "jest --coverage",
     "clean": "rm -rf lib coverage",
     "publish:local": "./scripts/publish-local.sh",
-    "pack": "npm run build && npm pack"
+    "pack": "npm run build && npm pack",
+    "reduce-fa": "node scripts/reduce-fa.js",
+    "update-full-fa": "node scripts/update-fa.js --format=full",
+    "update-compact-fa": "node scripts/update-fa.js --format=compact"
   },
   "keywords": [
     "typescript",
@@ -34,8 +42,10 @@
   "license": "MIT",
   "devDependencies": {
     "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.10",
     "jest": "^29.5.0",
+    "js-yaml": "^4.1.1",
     "ts-jest": "^29.1.0",
     "typescript": "^5.0.0"
   },