@vsirotin/ts-stop 0.5.1

package/lib/FiniteStateMachine.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FiniteStateMachine = void 0;
+const DefaultState_1 = require("./DefaultState");
+/**
+ * Concrete implementation of a finite state machine with optional state actions.
+ *
+ * This class supports states that can optionally implement action interfaces:
+ * - IStateWithAfterEntryAction: Execute action when entering the state
+ * - IStateWithBeforeExitAction: Execute action when exiting the state
+ * - Both interfaces: Execute both entry and exit actions
+ * - Neither interface: Traditional state machine behavior (no actions)
+ *
+ * @template STATE - The type representing possible states
+ * @template SIGNAL - The type representing signals/events
+ *
+ * @example
+ * ```typescript
+ * // Basic string-based turnstile (traditional approach)
+ * class Turnstile extends FiniteStateMachine<string, string> {
+ *     constructor() {
+ *         super(
+ *             ['locked', 'unlocked'],
+ *             ['coin', 'push'],
+ *             [
+ *                 { from: 'locked', signal: 'coin', to: 'unlocked' },
+ *                 { from: 'unlocked', signal: 'push', to: 'locked' }
+ *             ],
+ *             'locked'
+ *         );
+ *     }
+ *
+ * ...
+ * }
+ *
+ 
+ *
+ * class TurnstileWithActions extends FiniteStateMachine<ActionState, string> {
+ *     private locked = new ActionState('locked', 'Payment required');
+ *     private unlocked = new ActionState('unlocked', 'Please proceed');
+ *
+ *     constructor() {
+ *         super(
+ *             [this.locked, this.unlocked],
+ *             ['coin', 'push'],
+ *             [
+ *                 { from: this.locked, signal: 'coin', to: this.unlocked },
+ *                 { from: this.unlocked, signal: 'push', to: this.locked }
+ *             ],
+ *             this.locked
+ *         );
+ *     }
+ *
+ *     insertCoin(): ActionState { return this.sendSignal('coin'); }
+ *     pushThrough(): ActionState { return this.sendSignal('push'); }
+ * }
+ *
+ * ```
+ */
+class FiniteStateMachine {
+    /**
+     * Creates a new finite state machine.
+     *
+     * @param states - Array of all possible states
+     * @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
+     */
+    constructor(states, signals, transitions, startState) {
+        this.states = states;
+        this.signals = signals;
+        this.transitions = transitions;
+        this.startState = startState;
+        /**
+     * The default state that handles invalid signals.
+     * Set to null if no state implements IDefaultState.
+     */
+        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.`);
+        }
+        // Set default state if exactly one found
+        if (defaultStates.length === 1) {
+            this.defaultState = defaultStates[0];
+        }
+        // Initialize the machine to its starting state
+        this.currentState = startState;
+        // Check if a current state has output signal and process it
+        this.tryProcessStateWithOutputSignal();
+        // Execute initial state entry action if supported
+        this.executeEntryAction(this.currentState);
+    }
+    /**
+     * Gets the current state of the state machine.
+     *
+     * @returns The current state
+     */
+    getCurrentState() {
+        return this.currentState;
+    }
+    /**
+     * Processes a signal and potentially transitions to a new state with action execution.
+     *
+     * This method:
+     * 1. Finds a matching transition for the current state and signal
+     * 2. If found and the target state is different:
+     *    a. Executes beforeExitAction on current state (if implemented)
+     *    b. Changes to the new state
+     *    c. Executes afterEntryAction on new state (if implemented)
+     * 3. Returns the resulting state
+     *
+     * @param signal - The signal/event to process
+     * @returns The resulting state after processing the signal
+     */
+    sendSignal(signal) {
+        // Find a transition that matches current state and signal
+        const transition = this.transitions.find(t => t.from === this.currentState && t.signal === signal);
+        // If valid transition found, handle state change with actions
+        if (transition) {
+            this.executeStateTransition(transition);
+        }
+        else if (this.defaultState) {
+            // No valid transition found, but default state exists
+            // Execute default state's actions (entry/exit if implemented)
+            this.executeStateActions(this.defaultState);
+            // Current state remains unchanged
+        }
+        this.tryProcessStateWithOutputSignal();
+        return this.currentState;
+    }
+    tryProcessStateWithOutputSignal() {
+        if (this.isStateWithOutputSignal(this.currentState)) {
+            // Processing of behaviour for state with inside calculated output signal
+            this.executeStateActions(this.currentState);
+            const stateWithOutputSignal = this.currentState;
+            const outputSignal = stateWithOutputSignal.getOutputSignal();
+            // Add null/undefined check to prevent errors
+            if (outputSignal !== null && outputSignal !== undefined) {
+                this.sendSignal(outputSignal);
+            }
+        }
+    }
+    isStateWithOutputSignal(state) {
+        const obj = state;
+        return (typeof obj === 'object' &&
+            obj !== null &&
+            typeof obj.getOutputSignal === 'function');
+    }
+    executeStateTransition(transition) {
+        const oldState = this.currentState;
+        const newState = transition.to;
+        // Only execute actions if there's an actual state change
+        if (oldState !== newState) {
+            // Execute before exit action on current state
+            this.executeExitAction(oldState);
+            // Change state
+            this.currentState = newState;
+            // Execute after entry action on new state
+            this.executeEntryAction(newState);
+        }
+    }
+    executeStateActions(state) {
+        this.executeEntryAction(state);
+        this.executeExitAction(state);
+    }
+    /**
+     * Type guard to check if a state is an instance of DefaultState class.
+     *
+     * @param state - The state to check
+     * @returns true if the state is an instance of DefaultState
+     */
+    isDefaultState(state) {
+        return state instanceof DefaultState_1.DefaultState;
+    }
+    /**
+     * Type guard to check if a state implements IStateWithAfterEntryAction.
+     *
+     * @param state - The state to check
+     * @returns true if the state implements afterEntryAction method
+     */
+    hasAfterEntryAction(state) {
+        return typeof state === 'object' &&
+            state !== null &&
+            'afterEntryAction' in state &&
+            typeof state.afterEntryAction === 'function';
+    }
+    /**
+     * Type guard to check if a state implements IStateWithBeforeExitAction.
+     *
+     * @param state - The state to check
+     * @returns true if the state implements beforeExitAction method
+     */
+    hasBeforeExitAction(state) {
+        return typeof state === 'object' &&
+            state !== null &&
+            'beforeExitAction' in state &&
+            typeof state.beforeExitAction === 'function';
+    }
+    /**
+     * Executes the afterEntryAction on a state if it implements IStateWithAfterEntryAction.
+     *
+     * @param state - The state to execute the entry action on
+     */
+    executeEntryAction(state) {
+        if (this.hasAfterEntryAction(state)) {
+            state.afterEntryAction();
+        }
+    }
+    /**
+     * Executes the beforeExitAction on a state if it implements IStateWithBeforeExitAction.
+     *
+     * @param state - The state to execute the exit action on
+     */
+    executeExitAction(state) {
+        if (this.hasBeforeExitAction(state)) {
+            state.beforeExitAction();
+        }
+    }
+    /**
+     * Gets all possible states.
+     *
+     * @returns Array of all states
+     */
+    getAllStates() {
+        return [...this.states];
+    }
+    /**
+     * Gets all possible signals.
+     *
+     * @returns Array of all signals
+     */
+    getAllSignals() {
+        return [...this.signals];
+    }
+    /**
+     * Checks if a given signal is valid from the current state.
+     *
+     * @param signal - The signal to check
+     * @returns true if the signal can trigger a transition from the current state
+     */
+    isValidSignalFromCurrentState(signal) {
+        return this.transitions.some(t => t.from === this.currentState && t.signal === signal);
+    }
+    /**
+     * Gets all valid signals from the current state.
+     *
+     * @returns Array of signals that can trigger transitions from the current state
+     */
+    getValidSignalsFromCurrentState() {
+        return this.transitions
+            .filter(t => t.from === this.currentState)
+            .map(t => t.signal);
+    }
+    /**
+     * Gets all transitions.
+     *
+     * @returns Array of all transitions
+     */
+    getTransitions() {
+        return [...this.transitions];
+    }
+    /**
+     * Checks if a signal is valid in the state machine.
+     * @param signal - The signal to check
+     * @returns True if the signal is valid, false otherwise.
+     */
+    hasSignal(signal) {
+        return this.getAllSignals().includes(signal);
+    }
+    /**
+     * Checks if a given state exists in the state machine.
+     *
+     * @param state - The state to check
+     * @returns true if the state exists, false otherwise
+     */
+    hasState(state) {
+        return this.getAllStates().includes(state);
+    }
+    /**
+ * Gets the default state that handles invalid signals.
+ *
+ * @returns The default state or null if none exists
+ */
+    getDefaultState() {
+        return this.defaultState;
+    }
+    /**
+     * Checks if the state machine has a default state.
+     *
+     * @returns true if a default state exists
+     */
+    hasDefaultState() {
+        return this.defaultState !== null;
+    }
+}
+exports.FiniteStateMachine = FiniteStateMachine;
+//# sourceMappingURL=FiniteStateMachine.js.map

package/lib/FiniteStateMachine.js.map

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

package/lib/IStateWithActions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Interface for states that have an action after entry.
+ */
+export interface IStateWithAfterEntryAction {
+    afterEntryAction: () => void;
+}
+/**
+ * Interface for states that have an action before exit.
+ */
+export interface IStateWithBeforeExitAction {
+    beforeExitAction: () => void;
+}
+/**
+ * Interface combining both entry and exit actions.
+ */
+export interface IStateWithActions extends IStateWithAfterEntryAction, IStateWithBeforeExitAction {
+}
+//# sourceMappingURL=IStateWithActions.d.ts.map

package/lib/IStateWithActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStateWithActions.d.ts","sourceRoot":"","sources":["../src/IStateWithActions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAChC;AACD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAChC;AACD;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,0BAA0B,EAAE,0BAA0B;CAAI"}

package/lib/IStateWithActions.js

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

package/lib/IStateWithActions.js.map

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

package/lib/IStateWithOutputSignal.d.ts

@@ -0,0 +1,4 @@
+export interface IStateWithOutputSignal<SIGNAL> {
+    getOutputSignal(): SIGNAL;
+}
+//# sourceMappingURL=IStateWithOutputSignal.d.ts.map

package/lib/IStateWithOutputSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStateWithOutputSignal.d.ts","sourceRoot":"","sources":["../src/IStateWithOutputSignal.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,sBAAsB,CAAC,MAAM;IAC1C,eAAe,IAAI,MAAM,CAAC;CAC7B"}

package/lib/IStateWithOutputSignal.js

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

package/lib/IStateWithOutputSignal.js.map

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

package/lib/MatrixBasedStateMachine.d.ts

@@ -0,0 +1,108 @@
+import { FiniteStateMachine } from './FiniteStateMachine';
+import { TransitionMatrix } from './TransitionMatrix';
+/**
+ * Abstract base class for finite state machines that use transition matrices.
+ *
+ * This class extends FiniteStateMachine to provide a more intuitive way to define
+ * state transitions using a 2D matrix representation instead of explicit transition arrays.
+ *
+ * The matrix format allows for visual representation of state transitions:
+ * - Columns represent states
+ * - Rows represent signals
+ * - Cell values represent target states
+ * - Empty cells represent invalid/ignored transitions
+ *
+ * @template STATE - The type representing possible states
+ * @template SIGNAL - The type representing signals/events
+ *
+ * @example
+ * ```typescript
+ * // Example 1: Using explicit start state
+ * class TurnstileMatrix extends MatrixBasedStateMachine<string, string> {
+ *     constructor() {
+ *         const matrix = transitionMatrix([
+ *             [           , "locked"    , "unlocked" ],
+ *             [ "coin"    , "unlocked" ,             ],
+ *             [ "push"    ,            , "locked"   ]
+ *         ]);
+ *         super(matrix, "locked"); // Explicit start state
+ *     }
+ * }
+ *
+ * // Example 2: Using first state as start state (auto)
+ * class TurnstileMatrixAuto extends MatrixBasedStateMachine<string, string> {
+ *     constructor() {
+ *         const matrix = transitionMatrix([
+ *             [           , "locked"    , "unlocked" ],  // "locked" becomes start state
+ *             [ "coin"    , "unlocked" ,             ],
+ *             [ "push"    ,            , "locked"   ]
+ *         ]);
+ *         super(matrix); // Uses first state ("locked") as start state
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class MatrixBasedStateMachine<STATE, SIGNAL> extends FiniteStateMachine<STATE, SIGNAL> {
+    /**
+     * The transition matrix used to define state transitions.
+     * Stored for potential debugging or inspection purposes.
+     */
+    protected readonly matrix: TransitionMatrix<STATE, SIGNAL>;
+    /**
+     * Creates a new matrix-based finite state machine.
+     *
+     * @param matrix - The transition matrix defining all states, signals, and transitions
+     * @param startState - Optional. The initial state of the machine. If not provided,
+     *                     the first state from the matrix (first column in header row) will be used.
+     *                     If provided, must be one of the states in the matrix.
+     *
+     * @throws {Error} If matrix has no states
+     * @throws {Error} If startState is provided but not found in the matrix states
+     *
+     * @example
+     * ```typescript
+     * // Constructor with explicit start state
+     * const matrix = transitionMatrix([
+     *     [           , "locked"    , "unlocked" ],
+     *     [ "coin"    , "unlocked" ,             ],
+     *     [ "push"    ,            , "locked"   ]
+     * ]);
+     * super(matrix, "unlocked"); // Start in unlocked state
+     *
+     * // Constructor with auto start state (uses first state)
+     * super(matrix); // Automatically starts in "locked" state
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // TurnstileMatrix implementation from test/Turnstile/TurnstileMatrix.ts
+     * class TurnstileMatrix extends MatrixBasedStateMachine<string, string> {
+     *     constructor() {
+     *         const matrix = transitionMatrix([
+     *             [           , "locked"    , "unlocked" ],
+     *             [ "coin"    , "unlocked" ,             ],
+     *             [ "push"    ,            , "locked"   ]
+     *         ]);
+     *
+     *         // Two ways to call the constructor:
+     *         super(matrix, "locked");  // Option 1: Explicit start state
+     *         // OR
+     *         super(matrix);            // Option 2: Auto start state (uses "locked")
+     *     }
+     *
+     *     insertCoin(): string { return this.sendSignal('coin'); }
+     *     pushThrough(): string { return this.sendSignal('push'); }
+     *     isLocked(): boolean { return this.getCurrentState() === 'locked'; }
+     *     isUnlocked(): boolean { return this.getCurrentState() === 'unlocked'; }
+     * }
+     * ```
+     */
+    constructor(matrix: TransitionMatrix<STATE, SIGNAL>, startState?: STATE);
+    /**
+     * Gets the transition matrix used by this state machine.
+     *
+     * @returns The transition matrix
+     */
+    getMatrix(): TransitionMatrix<STATE, SIGNAL>;
+}
+//# sourceMappingURL=MatrixBasedStateMachine.d.ts.map

package/lib/MatrixBasedStateMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MatrixBasedStateMachine.d.ts","sourceRoot":"","sources":["../src/MatrixBasedStateMachine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAuB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,8BAAsB,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAE,SAAQ,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC;IAClG;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;gBACS,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,EAAE,KAAK;IAqCvE;;;;OAIG;IACH,SAAS,IAAI,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC;CAI/C"}

package/lib/MatrixBasedStateMachine.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MatrixBasedStateMachine = void 0;
+const FiniteStateMachine_1 = require("./FiniteStateMachine");
+/**
+ * Abstract base class for finite state machines that use transition matrices.
+ *
+ * This class extends FiniteStateMachine to provide a more intuitive way to define
+ * state transitions using a 2D matrix representation instead of explicit transition arrays.
+ *
+ * The matrix format allows for visual representation of state transitions:
+ * - Columns represent states
+ * - Rows represent signals
+ * - Cell values represent target states
+ * - Empty cells represent invalid/ignored transitions
+ *
+ * @template STATE - The type representing possible states
+ * @template SIGNAL - The type representing signals/events
+ *
+ * @example
+ * ```typescript
+ * // Example 1: Using explicit start state
+ * class TurnstileMatrix extends MatrixBasedStateMachine<string, string> {
+ *     constructor() {
+ *         const matrix = transitionMatrix([
+ *             [           , "locked"    , "unlocked" ],
+ *             [ "coin"    , "unlocked" ,             ],
+ *             [ "push"    ,            , "locked"   ]
+ *         ]);
+ *         super(matrix, "locked"); // Explicit start state
+ *     }
+ * }
+ *
+ * // Example 2: Using first state as start state (auto)
+ * class TurnstileMatrixAuto extends MatrixBasedStateMachine<string, string> {
+ *     constructor() {
+ *         const matrix = transitionMatrix([
+ *             [           , "locked"    , "unlocked" ],  // "locked" becomes start state
+ *             [ "coin"    , "unlocked" ,             ],
+ *             [ "push"    ,            , "locked"   ]
+ *         ]);
+ *         super(matrix); // Uses first state ("locked") as start state
+ *     }
+ * }
+ * ```
+ */
+class MatrixBasedStateMachine extends FiniteStateMachine_1.FiniteStateMachine {
+    /**
+     * Creates a new matrix-based finite state machine.
+     *
+     * @param matrix - The transition matrix defining all states, signals, and transitions
+     * @param startState - Optional. The initial state of the machine. If not provided,
+     *                     the first state from the matrix (first column in header row) will be used.
+     *                     If provided, must be one of the states in the matrix.
+     *
+     * @throws {Error} If matrix has no states
+     * @throws {Error} If startState is provided but not found in the matrix states
+     *
+     * @example
+     * ```typescript
+     * // Constructor with explicit start state
+     * const matrix = transitionMatrix([
+     *     [           , "locked"    , "unlocked" ],
+     *     [ "coin"    , "unlocked" ,             ],
+     *     [ "push"    ,            , "locked"   ]
+     * ]);
+     * super(matrix, "unlocked"); // Start in unlocked state
+     *
+     * // Constructor with auto start state (uses first state)
+     * super(matrix); // Automatically starts in "locked" state
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // TurnstileMatrix implementation from test/Turnstile/TurnstileMatrix.ts
+     * class TurnstileMatrix extends MatrixBasedStateMachine<string, string> {
+     *     constructor() {
+     *         const matrix = transitionMatrix([
+     *             [           , "locked"    , "unlocked" ],
+     *             [ "coin"    , "unlocked" ,             ],
+     *             [ "push"    ,            , "locked"   ]
+     *         ]);
+     *
+     *         // Two ways to call the constructor:
+     *         super(matrix, "locked");  // Option 1: Explicit start state
+     *         // OR
+     *         super(matrix);            // Option 2: Auto start state (uses "locked")
+     *     }
+     *
+     *     insertCoin(): string { return this.sendSignal('coin'); }
+     *     pushThrough(): string { return this.sendSignal('push'); }
+     *     isLocked(): boolean { return this.getCurrentState() === 'locked'; }
+     *     isUnlocked(): boolean { return this.getCurrentState() === 'unlocked'; }
+     * }
+     * ```
+     */
+    constructor(matrix, startState) {
+        // Get states from matrix
+        const states = matrix.getStates();
+        // Validate matrix has states
+        if (states.length === 0) {
+            throw new Error('Matrix must contain at least one state');
+        }
+        // Determine the actual start state
+        let actualStartState;
+        if (startState !== undefined) {
+            // Explicit start state provided - validate it exists
+            if (!states.includes(startState)) {
+                throw new Error(`Start state '${String(startState)}' not found in matrix states: [${states.map(s => String(s)).join(', ')}]`);
+            }
+            actualStartState = startState;
+        }
+        else {
+            // No start state provided - use first state from matrix
+            actualStartState = states[0];
+        }
+        // Call parent constructor with matrix-derived data
+        super(matrix.getStates(), matrix.getSignals(), matrix.getTransitions(), actualStartState);
+        // Store the matrix for potential future use
+        this.matrix = matrix;
+    }
+    /**
+     * Gets the transition matrix used by this state machine.
+     *
+     * @returns The transition matrix
+     */
+    getMatrix() {
+        return this.matrix;
+    }
+}
+exports.MatrixBasedStateMachine = MatrixBasedStateMachine;
+//# sourceMappingURL=MatrixBasedStateMachine.js.map

package/lib/MatrixBasedStateMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MatrixBasedStateMachine.js","sourceRoot":"","sources":["../src/MatrixBasedStateMachine.ts"],"names":[],"mappings":";;;AAAA,6DAA+E;AAG/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAsB,uBAAuC,SAAQ,uCAAiC;IAOlG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,YAAY,MAAuC,EAAE,UAAkB;QACnE,yBAAyB;QACzB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QAElC,6BAA6B;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC9D,CAAC;QAED,mCAAmC;QACnC,IAAI,gBAAuB,CAAC;QAE5B,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,qDAAqD;YACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,KAAK,CACX,gBAAgB,MAAM,CAAC,UAAU,CAAC,kCAAkC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC/G,CAAC;YACN,CAAC;YACD,gBAAgB,GAAG,UAAU,CAAC;QAClC,CAAC;aAAM,CAAC;YACJ,wDAAwD;YACxD,gBAAgB,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC;QAED,mDAAmD;QACnD,KAAK,CACD,MAAM,CAAC,SAAS,EAAE,EAClB,MAAM,CAAC,UAAU,EAAE,EACnB,MAAM,CAAC,cAAc,EAAE,EACvB,gBAAgB,CACnB,CAAC;QAEF,4CAA4C;QAC5C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,SAAS;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;CAEJ;AAtGD,0DAsGC"}

package/lib/TransitionMatrix.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Utility type to extract non-empty values from transition matrix
+ */
+export type NonEmpty<T> = T extends "" | undefined | null ? never : T;
+/**
+ * Creates transitions from a 2D matrix representation.
+ *
+ * Matrix format:
+ * - First row: [undefined, ...states] - column headers
+ * - Subsequent rows: [signal, ...transitions] - signal + target states
+ * - Empty cells: undefined, null, "", or omitted
+ *
+ * @template STATE - Type for states
+ * @template SIGNAL - Type for signals
+ */
+export declare class TransitionMatrix<STATE, SIGNAL> {
+    private states;
+    private signals;
+    private transitions;
+    /**
+     * Creates a transition matrix from a 2D array.
+     *
+     * @param matrix - 2D array where:
+     *   - matrix[0] = [undefined, ...states] (header row)
+     *   - matrix[i] = [signal, target1, target2, ...] (transition rows)
+     *
+     * @example
+     * ```typescript
+     * const matrix = [
+     *     [           , "locked"    , "unlocked" ],  // States header
+     *     [ "coin"    , "unlocked" ,             ],  // coin transitions
+     *     [ "push"    ,            , "locked"   ]   // push transitions
+     * ];
+     * ```
+     */
+    static fromArray<S, G>(matrix: Array<Array<S | G | undefined | null | "">>): TransitionMatrix<NonEmpty<S>, NonEmpty<G>>;
+    /**
+     * Get all states from the matrix.
+     */
+    getStates(): STATE[];
+    /**
+     * Get all signals from the matrix.
+     */
+    getSignals(): SIGNAL[];
+    /**
+     * Get all transitions from the matrix.
+     */
+    getTransitions(): {
+        from: STATE;
+        to: STATE;
+        signal: SIGNAL;
+    }[];
+}
+/**
+ * Helper function to create transition matrix from 2D array.
+ *
+ * @template S - State type
+ * @template G - Signal type
+ */
+export declare function transitionMatrix<S, G>(matrix: Array<Array<S | G | undefined | null | "">>): TransitionMatrix<NonEmpty<S>, NonEmpty<G>>;
+//# sourceMappingURL=TransitionMatrix.d.ts.map

package/lib/TransitionMatrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransitionMatrix.d.ts","sourceRoot":"","sources":["../src/TransitionMatrix.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB,CAAC,KAAK,EAAE,MAAM;IACvC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,WAAW,CAAoD;IAEvE;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EACjB,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,GACpD,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAiD7C;;OAEG;IACH,SAAS,IAAI,KAAK,EAAE;IAIpB;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;OAEG;IACH,cAAc,IAAI;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE;CAGjE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACjC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,GACpD,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAE5C"}