@vsirotin/ts-stop 0.5.1

package/README.md

@@ -0,0 +1,173 @@
+# @vsirotin/ts-stop
+
+State Oriented Programming library for TypeScript.
+
+DEvelopment in progress.
+
+## Installation
+
+### From NPM (when published)
+```bash
+npm install @vsirotin/ts-stop
+```
+
+### Local Installation for Another Project
+
+If you want to use this package in another project without publishing to NPM:
+
+#### Step 1: Build and Pack the Library
+```bash
+# In the ts-stop directory
+cd /path/to/StOP/ts/ts-stop
+npm run build
+npm pack
+```
+
+This creates a file `vsirotin-ts-stop-<version>.tgz` in the ts-stop directory.
+
+#### Step 2: Install in Your Project
+
+Choose one of these methods:
+
+**Method 1: Install from Tarball (Recommended)**
+```bash
+# In your project directory
+npm install /Users/viktorsirotin/VSCodeProjects/StOP/ts/ts-stop/vsirotin-ts-stop-0.0.1.tgz
+```
+
+**Method 2: Install from Directory**
+```bash
+# In your project directory
+npm install /path/to/StOP/ts/ts-stop
+```
+
+**Method 3: Add to package.json**
+```json
+{
+  "dependencies": {
+    "@vsirotin/ts-stop": "file:/path/to/StOP/ts/ts-stop"
+  }
+}
+```
+Then run `npm install`.
+
+#### Step 3: Update After Changes
+
+When you make changes to the ts-stop library:
+
+```bash
+# In the ts-stop directory
+npm run build
+npm pack
+
+# In your project directory
+npm install /path/to/StOP/ts/ts-stop/vsirotin-ts-stop-0.0.1.tgz --force
+```
+
+Or if using Method 2 or 3:
+```bash
+# In your project directory
+npm install --force
+```
+
+## Usage
+
+```typescript
+import { FiniteStateMachine, DefaultState } from '@vsirotin/ts-stop';
+
+// Example: Simple State Machine
+const states = [/* your states */];
+const signals = [/* your signals */];
+const transitions = [/* your transitions */];
+const startState = states[0];
+
+const machine = new FiniteStateMachine(
+  states,
+  signals,
+  transitions,
+  startState
+);
+
+// Process signals
+machine.processSignal(someSignal);
+```
+
+## Development
+
+### Build
+```bash
+npm run build          # Build both CommonJS and ESM versions
+npm run build:cjs      # Build CommonJS version only
+npm run build:esm      # Build ESM version only
+```
+
+### Test
+```bash
+npm test               # Run tests
+npm run test:coverage  # Run tests with coverage
+```
+
+### Clean
+```bash
+npm run clean          # Remove build artifacts
+```
+
+### Package
+```bash
+npm run pack           # Build and create tarball for distribution
+```
+
+## 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
+
+## Using the Package Locally
+
+To use this package in another project without publishing to NPM:
+
+### Method 1: Direct Installation
+```bash
+# From your target project directory
+npm install /path/to/StOP/ts/ts-stop
+```
+
+### Method 2: Using the Packed Tarball
+```bash
+# In ts-stop directory
+npm run pack
+
+# In your target project directory
+npm install /path/to/StOP/ts/ts-stop/vsirotin-ts-stop-0.0.1.tgz
+```
+
+### Method 3: Using package.json
+In your target project's `package.json`:
+```json
+{
+  "dependencies": {
+    "@vsirotin/ts-stop": "file:../StOP/ts/ts-stop"
+  }
+}
+```
+Then run `npm install`.
+
+## License
+
+MIT

package/lib/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/DefaultState.d.ts.map

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

package/lib/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/DefaultState.js.map

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

package/lib/FiniteStateMachine.d.ts

@@ -0,0 +1,222 @@
+import { DefaultState } from './DefaultState';
+import { IStateWithAfterEntryAction, IStateWithBeforeExitAction } from './IStateWithActions';
+/**
+ * Represents a transition in a finite state machine.
+ *
+ * @template STATE - The type representing possible states
+ * @template SIGNAL - The type representing signals/events
+ */
+export interface ITransition<STATE, SIGNAL> {
+    from: STATE;
+    signal: SIGNAL;
+    to: STATE;
+}
+/**
+ * Interface defining the contract for a finite state machine.
+ *
+ * @template STATE - The type representing possible states in the state machine
+ * @template SIGNAL - The type representing signals/events that trigger state transitions
+ */
+export interface IFiniteStateMachine<STATE> {
+    /**
+     * Gets the current state of the state machine.
+     *
+     * @returns The current state
+     */
+    getCurrentState(): STATE;
+}
+/**
+ * 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'); }
+ * }
+ *
+ * ```
+ */
+export declare abstract class FiniteStateMachine<STATE, SIGNAL> implements IFiniteStateMachine<STATE> {
+    protected states: STATE[];
+    protected signals: SIGNAL[];
+    protected transitions: ITransition<STATE, SIGNAL>[];
+    protected startState: STATE;
+    /**
+     * The current state of the state machine.
+     * Protected to allow subclass access while maintaining encapsulation.
+     */
+    protected currentState: STATE;
+    /**
+ * The default state that handles invalid signals.
+ * Set to null if no state implements IDefaultState.
+ */
+    private defaultState;
+    /**
+     * 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: STATE[], signals: SIGNAL[], transitions: ITransition<STATE, SIGNAL>[], startState: STATE);
+    /**
+     * Gets the current state of the state machine.
+     *
+     * @returns The current state
+     */
+    getCurrentState(): STATE;
+    /**
+     * 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
+     */
+    protected sendSignal(signal: SIGNAL): STATE;
+    private tryProcessStateWithOutputSignal;
+    private isStateWithOutputSignal;
+    private executeStateTransition;
+    private executeStateActions;
+    /**
+     * 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
+     */
+    protected isDefaultState(state: STATE): boolean;
+    /**
+     * Type guard to check if a state implements IStateWithAfterEntryAction.
+     *
+     * @param state - The state to check
+     * @returns true if the state implements afterEntryAction method
+     */
+    protected hasAfterEntryAction(state: STATE): state is STATE & IStateWithAfterEntryAction;
+    /**
+     * Type guard to check if a state implements IStateWithBeforeExitAction.
+     *
+     * @param state - The state to check
+     * @returns true if the state implements beforeExitAction method
+     */
+    protected hasBeforeExitAction(state: STATE): state is STATE & IStateWithBeforeExitAction;
+    /**
+     * Executes the afterEntryAction on a state if it implements IStateWithAfterEntryAction.
+     *
+     * @param state - The state to execute the entry action on
+     */
+    private executeEntryAction;
+    /**
+     * Executes the beforeExitAction on a state if it implements IStateWithBeforeExitAction.
+     *
+     * @param state - The state to execute the exit action on
+     */
+    private executeExitAction;
+    /**
+     * Gets all possible states.
+     *
+     * @returns Array of all states
+     */
+    getAllStates(): STATE[];
+    /**
+     * Gets all possible signals.
+     *
+     * @returns Array of all signals
+     */
+    getAllSignals(): SIGNAL[];
+    /**
+     * 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: SIGNAL): boolean;
+    /**
+     * Gets all valid signals from the current state.
+     *
+     * @returns Array of signals that can trigger transitions from the current state
+     */
+    getValidSignalsFromCurrentState(): SIGNAL[];
+    /**
+     * Gets all transitions.
+     *
+     * @returns Array of all transitions
+     */
+    getTransitions(): ITransition<STATE, SIGNAL>[];
+    /**
+     * 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: SIGNAL): boolean;
+    /**
+     * 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: STATE): boolean;
+    /**
+ * Gets the default state that handles invalid signals.
+ *
+ * @returns The default state or null if none exists
+ */
+    getDefaultState(): DefaultState | null;
+    /**
+     * Checks if the state machine has a default state.
+     *
+     * @returns true if a default state exists
+     */
+    hasDefaultState(): boolean;
+}
+//# sourceMappingURL=FiniteStateMachine.d.ts.map

package/lib/FiniteStateMachine.d.ts.map

@@ -0,0 +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"}