@vsirotin/ts-stop 0.5.2 → 0.6.0

package/lib/esm/sfsm/ExternalWorldHub.js

@@ -0,0 +1,80 @@
+/**
+ * Wiring hub between the SFSM and the "external world".
+ *
+ * - registerSignalSender(signals, sender) — declares which signal names a sender may emit.
+ * - registerCommandReceiver(commands, receiver) — declares which commands a receiver handles.
+ * - connectTo(sfsm) — wires everything: sets itself as the SFSM command receiver and
+ *   calls connectSignalTarget(sfsm) on every registered signal sender.
+ *
+ * The explicit signal/command name lists enable precise runtime error messages and
+ * provide a foundation for FA-vs-wiring validation.
+ *
+ * Fluent API:
+ *   new ExternalWorldHub()
+ *     .registerSignalSender(['TS.s'], service)
+ *     .registerSignalSender(['TS.to', 'TS.ps'], device)
+ *     .registerCommandReceiver(['TS.ut', 'TS.l'], device)
+ *     .connectTo(sfsm);
+ */
+export class ExternalWorldHub {
+    constructor() {
+        this.commandRoutes = new Map();
+        this.signalSenders = [];
+    }
+    /**
+     * Register a command receiver for the given list of exact command names.
+     * Throws if any command name is already registered.
+     * Fluent — returns this.
+     */
+    registerCommandReceiver(commands, receiver) {
+        for (const cmd of commands) {
+            if (this.commandRoutes.has(cmd)) {
+                throw new Error(`ExternalWorldHub: command "${cmd}" is already registered`);
+            }
+            this.commandRoutes.set(cmd, receiver);
+        }
+        return this;
+    }
+    /**
+     * Register a signal sender for the given list of signal names.
+     * Duplicate signal names across registrations are allowed (same sender may be
+     * registered multiple times for documentation clarity), but will not cause
+     * double-wiring — connectSignalTarget is called once per registerSignalSender call.
+     * Fluent — returns this.
+     */
+    registerSignalSender(signals, sender) {
+        this.signalSenders.push({ signals, sender });
+        return this;
+    }
+    /**
+     * Wire this hub to the given SFSM instance:
+     * 1. Sets this hub as the SFSM's command receiver.
+     * 2. Calls connectSignalTarget(sfsm) on every registered signal sender.
+     * Fluent — returns this.
+     */
+    connectTo(sfsm) {
+        sfsm.setCommandReceiver(this);
+        for (const { sender } of this.signalSenders) {
+            sender.connectSignalTarget(sfsm);
+        }
+        return this;
+    }
+    /** ICommandReceiver implementation — dispatches command to the registered receiver. */
+    receiveCommand(command, data) {
+        const receiver = this.commandRoutes.get(command);
+        if (!receiver) {
+            const registered = [...this.commandRoutes.keys()].join(', ');
+            throw new Error(`ExternalWorldHub: no receiver registered for command "${command}". ` +
+                `Registered commands: [${registered}]`);
+        }
+        receiver.receiveCommand(command, data);
+    }
+    /** Returns all command names that have a registered receiver (for diagnostics / validation). */
+    getRegisteredCommands() {
+        return [...this.commandRoutes.keys()];
+    }
+    /** Returns all signal names that have a registered sender (for diagnostics / validation). */
+    getRegisteredSignals() {
+        return this.signalSenders.flatMap(e => e.signals);
+    }
+}

package/lib/esm/sfsm/FaLoader.js

@@ -0,0 +1,30 @@
+import * as fs from 'fs';
+/**
+ * Reads and parses a JSON file at the given path and returns it as a FaDefinition.
+ * Works with both extended and compact formats.
+ *
+ * Node.js only — uses `fs.readFileSync` and is not available in browser environments.
+ *
+ * @param filePath - Absolute or relative path to a JSON file containing an FA definition.
+ * @returns Parsed FaDefinition ready to pass to `Sfsm.loadFA()`.
+ * @throws If the file cannot be read or the contents are not valid JSON.
+ */
+export function loadFAFromFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * Fetches and parses a JSON FA definition from a URL.
+ * Works in both browser and Node.js (≥ 18) environments — uses the standard `fetch` API.
+ *
+ * @param url - Absolute URL to a JSON file containing an FA definition.
+ * @returns Promise resolving to a FaDefinition ready to pass to `Sfsm.loadFA()`.
+ * @throws If the request fails, the server returns a non-2xx status, or the body is not valid JSON.
+ */
+export async function loadFAFromURL(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`loadFAFromURL: request failed with status ${response.status} ${response.statusText} for URL: ${url}`);
+    }
+    return response.json();
+}

package/lib/esm/sfsm/FaReducer.js

@@ -0,0 +1,36 @@
+/**
+ * Converts an extended FA definition (nested FaNode tree) into compact format
+ * (flat Record<string, Transition[]> with each FA's name as a top-level key).
+ *
+ * If the input is already in compact multi-FA format (all values are Transition[]),
+ * it is returned unchanged.
+ *
+ * Metadata (state names, descriptions, signal/command metadata) is discarded in the output.
+ */
+export function reduceFA(definition) {
+    const entries = Object.entries(definition);
+    // Already compact: all values are arrays
+    if (entries.every(([, v]) => Array.isArray(v))) {
+        return definition;
+    }
+    const result = {};
+    const [rootName, rootValue] = entries[0];
+    collectNodes(rootName, rootValue, result);
+    return result;
+}
+function collectNodes(name, node, result) {
+    result[name] = node.ts;
+    if (node.states) {
+        for (const [stateName, stateValue] of Object.entries(node.states)) {
+            if (isSubFaNode(stateValue)) {
+                collectNodes(stateName, stateValue, result);
+            }
+        }
+    }
+}
+function isSubFaNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'ts' in value &&
+        Array.isArray(value.ts));
+}

package/lib/esm/sfsm/FaResolver.js

@@ -0,0 +1,115 @@
+/**
+ * Parses a raw FaDefinition and builds a flat index of all FAs by name.
+ *
+ * A state entry is considered a sub-FA if its value object contains a "ts" key.
+ * Leaf states (no "ts") are plain named states.
+ */
+export class FaResolver {
+    constructor(definition) {
+        this.definition = definition;
+        this.index = new Map();
+        this.buildIndex();
+    }
+    /** Returns the resolved FA for the given name, or throws if not found. */
+    get(name) {
+        const fa = this.index.get(name);
+        if (!fa) {
+            throw new Error(`SFSM: FA "${name}" not found in definition.`);
+        }
+        return fa;
+    }
+    /** Returns the name of the root FA.
+     *
+     * For single-key definitions (compact single FA or extended FA), the sole key is the root.
+     * For multi-key compact definitions (all values are Transition[]), the root is the FA whose
+     * name is never referenced as a target state (3rd element) in any other FA's transitions.
+     */
+    getRootName() {
+        const keys = Object.keys(this.definition);
+        if (keys.length === 1) {
+            return keys[0];
+        }
+        // Multi-key: all values must be Transition[]
+        const allCompact = keys.every(k => Array.isArray(this.definition[k]));
+        if (!allCompact) {
+            throw new Error(`SFSM: Multi-key FA definition must use compact format (all values must be Transition[]).`);
+        }
+        // Collect all target state names referenced across all transitions
+        const referenced = new Set();
+        for (const key of keys) {
+            const transitions = this.definition[key];
+            for (const t of transitions) {
+                referenced.add(t[2]); // newState is at index 2
+            }
+        }
+        // Root = the FA name that is never a target in any other FA's transitions
+        const roots = keys.filter(k => !referenced.has(k));
+        if (roots.length !== 1) {
+            throw new Error(`SFSM: Cannot determine root FA. Candidates: [${roots.join(', ')}]. ` +
+                `All FA names: [${keys.join(', ')}].`);
+        }
+        return roots[0];
+    }
+    buildIndex() {
+        const entries = Object.entries(this.definition);
+        const allCompact = entries.every(([, v]) => Array.isArray(v));
+        if (allCompact && entries.length > 1) {
+            // Multi-key compact format: index all FAs, sub-FA names derived from definition keys
+            this.buildCompactMultiIndex();
+        }
+        else {
+            const rootName = this.getRootName();
+            const rootValue = this.definition[rootName];
+            if (Array.isArray(rootValue)) {
+                // Single-key compact format
+                const node = { ts: rootValue };
+                this.index.set(rootName, {
+                    name: rootName,
+                    transitions: rootValue,
+                    subFaNames: new Set(),
+                    node
+                });
+            }
+            else {
+                // Extended format
+                this.indexNode(rootName, rootValue);
+            }
+        }
+    }
+    buildCompactMultiIndex() {
+        const definedFaNames = new Set(Object.keys(this.definition));
+        for (const [name, value] of Object.entries(this.definition)) {
+            const transitions = value;
+            // A state is a sub-FA if its name is a key in the definition
+            const subFaNames = new Set(transitions
+                .map(t => t[2])
+                .filter(target => definedFaNames.has(target)));
+            const node = { ts: transitions };
+            this.index.set(name, { name, transitions, subFaNames, node });
+        }
+    }
+    indexNode(name, node) {
+        const subFaNames = new Set();
+        if (node.states) {
+            for (const [stateName, stateValue] of Object.entries(node.states)) {
+                if (this.isSubFa(stateValue)) {
+                    subFaNames.add(stateName);
+                    this.indexNode(stateName, stateValue);
+                }
+            }
+        }
+        this.index.set(name, {
+            name,
+            transitions: node.ts,
+            subFaNames,
+            node
+        });
+    }
+    /** A state value is a sub-FA if it has a "ts" array property. */
+    isSubFa(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'ts' in value &&
+            Array.isArray(value.ts));
+    }
+}

package/lib/esm/sfsm/FaUpdater.js

@@ -0,0 +1,101 @@
+/**
+ * Apply an update to a compact FA definition (flat Record<string, Transition[]>).
+ *
+ * Steps (in order):
+ * 1. remove: delete the named top-level keys; also prune every remaining FA's
+ *    transitions whose 3rd element (target state) is one of the removed names.
+ * 2. add: upsert the provided keys (existing entries are replaced, new ones are added).
+ *
+ * The source is not mutated — a deep-cloned result is returned.
+ */
+export function updateCompactFA(source, update) {
+    var _a;
+    const result = JSON.parse(JSON.stringify(source));
+    const toRemove = new Set((_a = update.remove) !== null && _a !== void 0 ? _a : []);
+    for (const name of toRemove) {
+        delete result[name];
+    }
+    // Prune transitions referencing removed FAs from all surviving FAs.
+    for (const transitions of Object.values(result)) {
+        const arr = transitions;
+        const filtered = arr.filter(t => !toRemove.has(t[2]));
+        arr.length = 0;
+        arr.push(...filtered);
+    }
+    if (update.add) {
+        for (const [name, value] of Object.entries(update.add)) {
+            result[name] = JSON.parse(JSON.stringify(value));
+        }
+    }
+    return result;
+}
+/**
+ * Apply an update to an extended (full/declaration) FA definition.
+ *
+ * Steps (in order):
+ * 1. remove: recursively locate each named FA in the tree; remove it from its
+ *    parent's states map and prune the parent's ts of any transition targeting it.
+ * 2. add: for each entry, recursively locate the FA by name and replace it entirely.
+ *    If the name matches the root key, the root node is replaced.
+ *
+ * The source is not mutated — a deep-cloned result is returned.
+ */
+export function updateFullFA(source, update) {
+    var _a;
+    const result = JSON.parse(JSON.stringify(source));
+    for (const name of ((_a = update.remove) !== null && _a !== void 0 ? _a : [])) {
+        const rootNode = Object.values(result)[0];
+        removeFromNode(rootNode, name);
+    }
+    if (update.add) {
+        const rootKey = Object.keys(result)[0];
+        for (const [name, newNode] of Object.entries(update.add)) {
+            if (name === rootKey) {
+                result[rootKey] = JSON.parse(JSON.stringify(newNode));
+            }
+            else {
+                const rootNode = Object.values(result)[0];
+                replaceInNode(rootNode, name, newNode);
+            }
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function removeFromNode(node, targetName) {
+    if (!node.states)
+        return false;
+    if (targetName in node.states && isSubFaNode(node.states[targetName])) {
+        delete node.states[targetName];
+        node.ts = node.ts.filter(t => t[2] !== targetName);
+        return true;
+    }
+    for (const stateValue of Object.values(node.states)) {
+        if (isSubFaNode(stateValue) && removeFromNode(stateValue, targetName)) {
+            return true;
+        }
+    }
+    return false;
+}
+function replaceInNode(node, targetName, newNode) {
+    if (!node.states)
+        return false;
+    if (targetName in node.states) {
+        node.states[targetName] = JSON.parse(JSON.stringify(newNode));
+        return true;
+    }
+    for (const stateValue of Object.values(node.states)) {
+        if (isSubFaNode(stateValue) && replaceInNode(stateValue, targetName, newNode)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isSubFaNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'ts' in value &&
+        Array.isArray(value.ts));
+}

package/lib/esm/sfsm/Sfsm.js

@@ -0,0 +1,225 @@
+import { FaResolver } from './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.
+ */
+export 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(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);
+    }
+}

package/lib/esm/sfsm/index.js

@@ -0,0 +1,6 @@
+export { ExternalWorldHub } from './ExternalWorldHub';
+export { FaResolver } from './FaResolver';
+export { Sfsm } from './Sfsm';
+export { reduceFA } from './FaReducer';
+export { updateCompactFA, updateFullFA } from './FaUpdater';
+export { loadFAFromFile, loadFAFromURL } from './FaLoader';

package/lib/esm/sfsm/interfaces.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/sfsm/types.js

@@ -0,0 +1 @@
+export {};

package/lib/fa/DefaultState.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Marker base class for states that should be used processed by invalid signals and
+ * in situation, then no transitions set for pair (current signal, current state).
+ * Only one state in a state machine can have this role.
+ */
+export declare abstract class DefaultState {
+    isDefaultState(): boolean;
+}
+//# sourceMappingURL=DefaultState.d.ts.map

package/lib/fa/DefaultState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultState.d.ts","sourceRoot":"","sources":["../../src/fa/DefaultState.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,8BAAsB,YAAY;IAC9B,cAAc,IAAI,OAAO;CAG5B"}

package/lib/fa/DefaultState.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultState = void 0;
+/**
+ * Marker base class for states that should be used processed by invalid signals and
+ * in situation, then no transitions set for pair (current signal, current state).
+ * Only one state in a state machine can have this role.
+ */
+class DefaultState {
+    isDefaultState() {
+        return true;
+    }
+}
+exports.DefaultState = DefaultState;
+//# sourceMappingURL=DefaultState.js.map

package/lib/fa/DefaultState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultState.js","sourceRoot":"","sources":["../../src/fa/DefaultState.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,MAAsB,YAAY;IAC9B,cAAc;QACV,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ;AAJD,oCAIC"}