@vsirotin/ts-stop 0.5.2 → 0.6.0

package/README.md

@@ -2,43 +2,9 @@
 
 State Oriented Programming library for TypeScript.
 
-DEvelopment in progress.
-
-## Installation
-
-### From NPM 
-```bash
-npm install @vsirotin/ts-stop
-```
-
-
-
-## Usage
-
-See documentation on https://github.com/vsirotin/StOP/blob/4d8c2d42601e35453c08a74a7eda75ddc1725e4e/README.md
-
-
-## Package Structure
-
-After building, the package contains:
-
-```
-lib/
-├── index.js           # CommonJS entry point
-├── index.d.ts         # TypeScript declarations
-├── index.d.ts.map     # TypeScript declaration source map
-├── index.js.map       # JavaScript source map
-├── esm/               # ES Modules
-│   └── index.js       # ESM entry point
-└── [other modules with .js, .d.ts, and .map files]
-```
-
-The package includes:
-- **CommonJS** modules in `lib/` for Node.js compatibility
-- **ESM** (ES Modules) in `lib/esm/` for modern JavaScript
-- **TypeScript declarations** (`.d.ts`) for type checking
-- **Source maps** for debugging
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for development instructions.
 
+For usage and API documentation, see the [main StOP documentation](../../docs/Tutorial/01-StOP-Tutorial.md).
 
 ## License
 

package/lib/FiniteStateMachine.d.ts

@@ -102,8 +102,9 @@ export declare abstract class FiniteStateMachine<STATE, SIGNAL> implements IFini
      * @param signals - Array of all possible signals/events
      * @param transitions - Array of transition rules defining how signals move between states
      * @param startState - The initial state of the machine
+     * @param skipValidation - When true, all structural validations are skipped (default: false)
      */
-    constructor(states: STATE[], signals: SIGNAL[], transitions: ITransition<STATE, SIGNAL>[], startState: STATE);
+    constructor(states: STATE[], signals: SIGNAL[], transitions: ITransition<STATE, SIGNAL>[], startState: STATE, skipValidation?: boolean);
     /**
      * Gets the current state of the state machine.
      *
@@ -126,6 +127,10 @@ export declare abstract class FiniteStateMachine<STATE, SIGNAL> implements IFini
      */
     protected sendSignal(signal: SIGNAL): STATE;
     private tryProcessStateWithOutputSignal;
+    private validateUnreachableStates;
+    private validateDanglingReferences;
+    private validateOutputSignalStates;
+    private validateOutputSignalCycles;
     private isStateWithOutputSignal;
     private executeStateTransition;
     private executeStateActions;

package/lib/FiniteStateMachine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FiniteStateMachine.d.ts","sourceRoot":"","sources":["../src/FiniteStateMachine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAG7F;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,EAAE,MAAM;IACtC,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,KAAK,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACtC;;;;OAIG;IACH,eAAe,IAAI,KAAK,CAAC;CAE5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,8BAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAE,YAAW,mBAAmB,CAAC,KAAK,CAAC;IAsBrF,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE;IACzB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAC3B,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE;IACnD,SAAS,CAAC,UAAU,EAAE,KAAK;IAxB/B;;;OAGG;IACH,SAAS,CAAC,YAAY,EAAE,KAAK,CAAC;IAE1B;;;GAGD;IACH,OAAO,CAAC,YAAY,CAA6B;IAEjD;;;;;;;OAOG;gBAEW,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,WAAW,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EACzC,UAAU,EAAE,KAAK;IA6B/B;;;;OAIG;IACH,eAAe,IAAI,KAAK;IAIxB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK;IAqB3C,OAAO,CAAC,+BAA+B;IAcvC,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,mBAAmB;IAK3B;;;;;OAKG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI/C;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK,GAAG,0BAA0B;IAOxF;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK,GAAG,0BAA0B;IAOxF;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;OAIG;IACH,YAAY,IAAI,KAAK,EAAE;IAIvB;;;;OAIG;IACH,aAAa,IAAI,MAAM,EAAE;IAIzB;;;;;OAKG;IACH,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAMtD;;;;OAIG;IACH,+BAA+B,IAAI,MAAM,EAAE;IAM3C;;;;OAIG;IACH,cAAc,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE;IAI9C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI3B;;;;GAID;IACH,eAAe,IAAI,YAAY,GAAG,IAAI;IAItC;;;;OAIG;IACH,eAAe,IAAI,OAAO;CAG7B"}
+{"version":3,"file":"FiniteStateMachine.d.ts","sourceRoot":"","sources":["../src/FiniteStateMachine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAG7F;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,EAAE,MAAM;IACtC,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,KAAK,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACtC;;;;OAIG;IACH,eAAe,IAAI,KAAK,CAAC;CAE5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,8BAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAE,YAAW,mBAAmB,CAAC,KAAK,CAAC;IAuBrF,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE;IACzB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAC3B,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE;IACnD,SAAS,CAAC,UAAU,EAAE,KAAK;IAzB/B;;;OAGG;IACH,SAAS,CAAC,YAAY,EAAE,KAAK,CAAC;IAE1B;;;GAGD;IACH,OAAO,CAAC,YAAY,CAA6B;IAEjD;;;;;;;;OAQG;gBAEW,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,WAAW,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EACzC,UAAU,EAAE,KAAK,EAC3B,cAAc,GAAE,OAAe;IA2CnC;;;;OAIG;IACH,eAAe,IAAI,KAAK;IAIxB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK;IAqB3C,OAAO,CAAC,+BAA+B;IAcvC,OAAO,CAAC,yBAAyB;IA0BjC,OAAO,CAAC,0BAA0B;IAiClC,OAAO,CAAC,0BAA0B;IAelC,OAAO,CAAC,0BAA0B;IAmDlC,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,mBAAmB;IAK3B;;;;;OAKG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI/C;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK,GAAG,0BAA0B;IAOxF;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,KAAK,GAAG,0BAA0B;IAOxF;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;OAIG;IACH,YAAY,IAAI,KAAK,EAAE;IAIvB;;;;OAIG;IACH,aAAa,IAAI,MAAM,EAAE;IAIzB;;;;;OAKG;IACH,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAMtD;;;;OAIG;IACH,+BAA+B,IAAI,MAAM,EAAE;IAM3C;;;;OAIG;IACH,cAAc,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE;IAI9C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI3B;;;;GAID;IACH,eAAe,IAAI,YAAY,GAAG,IAAI;IAItC;;;;OAIG;IACH,eAAe,IAAI,OAAO;CAG7B"}

package/lib/FiniteStateMachine.js

@@ -65,8 +65,9 @@ class FiniteStateMachine {
      * @param signals - Array of all possible signals/events
      * @param transitions - Array of transition rules defining how signals move between states
      * @param startState - The initial state of the machine
+     * @param skipValidation - When true, all structural validations are skipped (default: false)
      */
-    constructor(states, signals, transitions, startState) {
+    constructor(states, signals, transitions, startState, skipValidation = false) {
         this.states = states;
         this.signals = signals;
         this.transitions = transitions;
@@ -78,11 +79,21 @@ class FiniteStateMachine {
         this.defaultState = null;
         // Find states that implement IDefaultState
         const defaultStates = states.filter(state => this.isDefaultState(state));
-        // Validate default state count
-        if (defaultStates.length > 1) {
-            throw new Error(`Multiple states implement IDefaultState interface. ` +
-                `Only one state can handle invalid signals. ` +
-                `Found ${defaultStates.length} states with IDefaultState.`);
+        if (!skipValidation) {
+            // Validate default state count
+            if (defaultStates.length > 1) {
+                throw new Error(`ERROR-STOP-01: Multiple states implement IDefaultState interface. ` +
+                    `Only one state can handle invalid signals. ` +
+                    `Found ${defaultStates.length} states with IDefaultState.`);
+            }
+            // Validate that all transition and start-state references are defined
+            this.validateDanglingReferences();
+            // Validate that all output signal states have at least one outgoing transition
+            this.validateOutputSignalStates();
+            // Validate that output-signal states do not form cycles
+            this.validateOutputSignalCycles();
+            // Validate that all states are reachable from the start state
+            this.validateUnreachableStates();
         }
         // Set default state if exactly one found
         if (defaultStates.length === 1) {
@@ -145,6 +156,103 @@ class FiniteStateMachine {
             }
         }
     }
+    validateUnreachableStates() {
+        const reachable = new Set();
+        const queue = [this.startState];
+        reachable.add(this.startState);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const t of this.transitions) {
+                if (t.from === current && !reachable.has(t.to)) {
+                    reachable.add(t.to);
+                    queue.push(t.to);
+                }
+            }
+        }
+        for (const state of this.states) {
+            if (this.isDefaultState(state))
+                continue; // DefaultState handles invalid signals — unreachable by design
+            if (!reachable.has(state)) {
+                throw new Error(`ERROR-STOP-08: State '${state}' is unreachable from start state '${this.startState}'. ` +
+                    `All non-default states must be reachable from the start state via the transition graph.`);
+            }
+        }
+    }
+    validateDanglingReferences() {
+        const stateSet = new Set(this.states);
+        const signalSet = new Set(this.signals);
+        if (!stateSet.has(this.startState)) {
+            throw new Error(`ERROR-STOP-03: Start state '${this.startState}' is not in the states array. ` +
+                `The start state must be one of the provided states.`);
+        }
+        for (const t of this.transitions) {
+            if (!stateSet.has(t.from)) {
+                throw new Error(`ERROR-STOP-04: Transition references unknown state '${t.from}' as 'from'. ` +
+                    `All transition states must be in the states array.`);
+            }
+            if (!stateSet.has(t.to)) {
+                throw new Error(`ERROR-STOP-05: Transition references unknown state '${t.to}' as 'to'. ` +
+                    `All transition states must be in the states array.`);
+            }
+            if (!signalSet.has(t.signal)) {
+                throw new Error(`ERROR-STOP-06: Transition references unknown signal '${String(t.signal)}'. ` +
+                    `All transition signals must be in the signals array.`);
+            }
+        }
+    }
+    validateOutputSignalStates() {
+        for (const state of this.states) {
+            if (this.isStateWithOutputSignal(state)) {
+                const hasOutgoing = this.transitions.some(t => t.from === state);
+                if (!hasOutgoing) {
+                    throw new Error(`ERROR-STOP-02: Configuration error: State '${state}' implements IStateWithOutputSignal ` +
+                        `but has no outgoing transitions. States with output signals must have ` +
+                        `at least one outgoing transition.`);
+                }
+            }
+        }
+    }
+    validateOutputSignalCycles() {
+        const outputStateSet = new Set(this.states.filter(s => this.isStateWithOutputSignal(s)));
+        if (outputStateSet.size < 2)
+            return;
+        // Build adjacency: output state → output states reachable via one transition
+        const adj = new Map();
+        for (const state of outputStateSet) {
+            adj.set(state, this.transitions
+                .filter(t => t.from === state && outputStateSet.has(t.to))
+                .map(t => t.to));
+        }
+        // DFS-based cycle detection (colour: 0=unvisited, 1=in-stack, 2=done)
+        const visited = new Set();
+        const onStack = new Set();
+        const stackPath = [];
+        const dfs = (state) => {
+            var _a;
+            visited.add(state);
+            onStack.add(state);
+            stackPath.push(state);
+            for (const neighbor of ((_a = adj.get(state)) !== null && _a !== void 0 ? _a : [])) {
+                if (onStack.has(neighbor)) {
+                    const cycleStart = stackPath.indexOf(neighbor);
+                    const cyclePath = [...stackPath.slice(cycleStart), neighbor];
+                    throw new Error(`ERROR-STOP-07: Circular dependency detected in output signals: ` +
+                        `${cyclePath.map(s => String(s)).join(' -> ')}. ` +
+                        `States with output signals cannot form cycles as this creates infinite loops.`);
+                }
+                if (!visited.has(neighbor)) {
+                    dfs(neighbor);
+                }
+            }
+            onStack.delete(state);
+            stackPath.pop();
+        };
+        for (const state of outputStateSet) {
+            if (!visited.has(state)) {
+                dfs(state);
+            }
+        }
+    }
     isStateWithOutputSignal(state) {
         const obj = state;
         return (typeof obj === 'object' &&

package/lib/FiniteStateMachine.js.map

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

package/lib/esm/FiniteStateMachine.js

@@ -62,8 +62,9 @@ export class FiniteStateMachine {
      * @param signals - Array of all possible signals/events
      * @param transitions - Array of transition rules defining how signals move between states
      * @param startState - The initial state of the machine
+     * @param skipValidation - When true, all structural validations are skipped (default: false)
      */
-    constructor(states, signals, transitions, startState) {
+    constructor(states, signals, transitions, startState, skipValidation = false) {
         this.states = states;
         this.signals = signals;
         this.transitions = transitions;
@@ -75,11 +76,21 @@ export class FiniteStateMachine {
         this.defaultState = null;
         // Find states that implement IDefaultState
         const defaultStates = states.filter(state => this.isDefaultState(state));
-        // Validate default state count
-        if (defaultStates.length > 1) {
-            throw new Error(`Multiple states implement IDefaultState interface. ` +
-                `Only one state can handle invalid signals. ` +
-                `Found ${defaultStates.length} states with IDefaultState.`);
+        if (!skipValidation) {
+            // Validate default state count
+            if (defaultStates.length > 1) {
+                throw new Error(`ERROR-STOP-01: Multiple states implement IDefaultState interface. ` +
+                    `Only one state can handle invalid signals. ` +
+                    `Found ${defaultStates.length} states with IDefaultState.`);
+            }
+            // Validate that all transition and start-state references are defined
+            this.validateDanglingReferences();
+            // Validate that all output signal states have at least one outgoing transition
+            this.validateOutputSignalStates();
+            // Validate that output-signal states do not form cycles
+            this.validateOutputSignalCycles();
+            // Validate that all states are reachable from the start state
+            this.validateUnreachableStates();
         }
         // Set default state if exactly one found
         if (defaultStates.length === 1) {
@@ -142,6 +153,103 @@ export class FiniteStateMachine {
             }
         }
     }
+    validateUnreachableStates() {
+        const reachable = new Set();
+        const queue = [this.startState];
+        reachable.add(this.startState);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const t of this.transitions) {
+                if (t.from === current && !reachable.has(t.to)) {
+                    reachable.add(t.to);
+                    queue.push(t.to);
+                }
+            }
+        }
+        for (const state of this.states) {
+            if (this.isDefaultState(state))
+                continue; // DefaultState handles invalid signals — unreachable by design
+            if (!reachable.has(state)) {
+                throw new Error(`ERROR-STOP-08: State '${state}' is unreachable from start state '${this.startState}'. ` +
+                    `All non-default states must be reachable from the start state via the transition graph.`);
+            }
+        }
+    }
+    validateDanglingReferences() {
+        const stateSet = new Set(this.states);
+        const signalSet = new Set(this.signals);
+        if (!stateSet.has(this.startState)) {
+            throw new Error(`ERROR-STOP-03: Start state '${this.startState}' is not in the states array. ` +
+                `The start state must be one of the provided states.`);
+        }
+        for (const t of this.transitions) {
+            if (!stateSet.has(t.from)) {
+                throw new Error(`ERROR-STOP-04: Transition references unknown state '${t.from}' as 'from'. ` +
+                    `All transition states must be in the states array.`);
+            }
+            if (!stateSet.has(t.to)) {
+                throw new Error(`ERROR-STOP-05: Transition references unknown state '${t.to}' as 'to'. ` +
+                    `All transition states must be in the states array.`);
+            }
+            if (!signalSet.has(t.signal)) {
+                throw new Error(`ERROR-STOP-06: Transition references unknown signal '${String(t.signal)}'. ` +
+                    `All transition signals must be in the signals array.`);
+            }
+        }
+    }
+    validateOutputSignalStates() {
+        for (const state of this.states) {
+            if (this.isStateWithOutputSignal(state)) {
+                const hasOutgoing = this.transitions.some(t => t.from === state);
+                if (!hasOutgoing) {
+                    throw new Error(`ERROR-STOP-02: Configuration error: State '${state}' implements IStateWithOutputSignal ` +
+                        `but has no outgoing transitions. States with output signals must have ` +
+                        `at least one outgoing transition.`);
+                }
+            }
+        }
+    }
+    validateOutputSignalCycles() {
+        const outputStateSet = new Set(this.states.filter(s => this.isStateWithOutputSignal(s)));
+        if (outputStateSet.size < 2)
+            return;
+        // Build adjacency: output state → output states reachable via one transition
+        const adj = new Map();
+        for (const state of outputStateSet) {
+            adj.set(state, this.transitions
+                .filter(t => t.from === state && outputStateSet.has(t.to))
+                .map(t => t.to));
+        }
+        // DFS-based cycle detection (colour: 0=unvisited, 1=in-stack, 2=done)
+        const visited = new Set();
+        const onStack = new Set();
+        const stackPath = [];
+        const dfs = (state) => {
+            var _a;
+            visited.add(state);
+            onStack.add(state);
+            stackPath.push(state);
+            for (const neighbor of ((_a = adj.get(state)) !== null && _a !== void 0 ? _a : [])) {
+                if (onStack.has(neighbor)) {
+                    const cycleStart = stackPath.indexOf(neighbor);
+                    const cyclePath = [...stackPath.slice(cycleStart), neighbor];
+                    throw new Error(`ERROR-STOP-07: Circular dependency detected in output signals: ` +
+                        `${cyclePath.map(s => String(s)).join(' -> ')}. ` +
+                        `States with output signals cannot form cycles as this creates infinite loops.`);
+                }
+                if (!visited.has(neighbor)) {
+                    dfs(neighbor);
+                }
+            }
+            onStack.delete(state);
+            stackPath.pop();
+        };
+        for (const state of outputStateSet) {
+            if (!visited.has(state)) {
+                dfs(state);
+            }
+        }
+    }
     isStateWithOutputSignal(state) {
         const obj = state;
         return (typeof obj === 'object' &&

package/lib/esm/fa/DefaultState.js

@@ -0,0 +1,10 @@
+/**
+ * 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 class DefaultState {
+    isDefaultState() {
+        return true;
+    }
+}