@vedmalex/statemachine 1.0.0-beta.1

package/types/monitoring.d.ts

@@ -0,0 +1,239 @@
+import type { ErrorContext, IMonitor, MonitorMetricsSnapshot, TransitionContext } from './types';
+/**
+ * Performance metrics interface
+ */
+interface PerformanceMetrics {
+    transitionTime: number;
+    stateChangeCount: number;
+    errorCount: number;
+    timestamp: number;
+}
+/**
+ * Health check status
+ */
+export declare const HealthStatus: {
+    readonly HEALTHY: "healthy";
+    readonly WARNING: "warning";
+    readonly CRITICAL: "critical";
+    readonly UNKNOWN: "unknown";
+};
+export type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];
+/**
+ * Health check result
+ */
+interface HealthCheckResult {
+    status: HealthStatus;
+    message: string;
+    timestamp: number;
+    metrics?: Record<string, any>;
+}
+/**
+ * Monitoring configuration
+ */
+export interface MonitoringConfig {
+    enabled: boolean;
+    metricsInterval: number;
+    healthCheckInterval: number;
+    maxMetricsHistory: number;
+    thresholds: {
+        transitionTimeWarning: number;
+        transitionTimeCritical: number;
+        errorRateWarning: number;
+        errorRateCritical: number;
+    };
+}
+/**
+ * Default monitoring configuration
+ */
+export declare const DEFAULT_MONITORING_CONFIG: MonitoringConfig;
+/**
+ * Metrics collector for StateMachine performance monitoring
+ */
+export declare class MetricsCollector {
+    private metrics;
+    private config;
+    private startTime;
+    private transitionCount;
+    private errorCount;
+    constructor(config?: Partial<MonitoringConfig>);
+    /**
+     * Record a state transition
+     */
+    recordTransition(transitionTime: number): void;
+    /**
+     * Record an error
+     */
+    recordError(): void;
+    /**
+     * Get current metrics summary
+     */
+    getMetricsSummary(): {
+        totalTransitions: number;
+        totalErrors: number;
+        averageTransitionTime: number;
+        errorRate: number;
+        uptime: number;
+    };
+    /**
+     * Get metrics history
+     */
+    getMetricsHistory(timeRange?: number): PerformanceMetrics[];
+    /**
+     * Clear metrics history
+     */
+    clearMetrics(): void;
+    /**
+     * Get recent metrics within time range
+     */
+    private getRecentMetrics;
+    /**
+     * Add metrics to history with size limit
+     */
+    private addMetrics;
+    /**
+     * Log metrics if significant
+     */
+    private logMetrics;
+}
+/**
+ * Performance monitor for real-time tracking
+ */
+export declare class PerformanceMonitor {
+    private metricsCollector;
+    private config;
+    private intervalId;
+    private isRunning;
+    constructor(metricsCollector: MetricsCollector, config?: Partial<MonitoringConfig>);
+    /**
+     * Start performance monitoring
+     */
+    start(): void;
+    /**
+     * Stop performance monitoring
+     */
+    stop(): void;
+    /**
+     * Get current performance status
+     */
+    getPerformanceStatus(): {
+        status: HealthStatus;
+        summary: ReturnType<MetricsCollector['getMetricsSummary']>;
+        issues: string[];
+    };
+    /**
+     * Collect current metrics
+     */
+    private collectMetrics;
+}
+/**
+ * Health checker for StateMachine instances
+ */
+export declare class HealthChecker {
+    private performanceMonitor;
+    private config;
+    private intervalId;
+    private isRunning;
+    private lastHealthCheck;
+    constructor(performanceMonitor: PerformanceMonitor, config?: Partial<MonitoringConfig>);
+    /**
+     * Start health checking
+     */
+    start(): void;
+    /**
+     * Stop health checking
+     */
+    stop(): void;
+    /**
+     * Perform immediate health check
+     */
+    performHealthCheck(): HealthCheckResult;
+    /**
+     * Get last health check result
+     */
+    getLastHealthCheck(): HealthCheckResult | undefined;
+    /**
+     * Generate health message based on status
+     */
+    private generateHealthMessage;
+    /**
+     * Log health check results
+     */
+    private logHealthCheck;
+}
+/**
+ * Comprehensive monitoring system
+ */
+export declare class StateMachineMonitor {
+    private metricsCollector;
+    private performanceMonitor;
+    private healthChecker;
+    private config;
+    constructor(config?: Partial<MonitoringConfig>);
+    /**
+     * Start all monitoring components
+     */
+    start(): void;
+    /**
+     * Stop all monitoring components
+     */
+    stop(): void;
+    /**
+     * Record a transition for monitoring (F-T4-TS-5 widening: added success + context params)
+     */
+    recordTransition(transitionTime: number, success?: boolean, _context?: TransitionContext): void;
+    /**
+     * Record an error for monitoring (F-T4-TS-5 widening: added error + context params)
+     */
+    recordError(_error?: Error, _context?: ErrorContext): void;
+    /**
+     * Record an event for monitoring (optional IMonitor extension)
+     */
+    recordEvent(_eventName: string, _duration: number): void;
+    /**
+     * Get aggregate metrics snapshot (optional IMonitor extension)
+     */
+    getMetrics(): MonitorMetricsSnapshot;
+    /**
+     * Get comprehensive monitoring report
+     */
+    getMonitoringReport(): {
+        health: HealthCheckResult;
+        performance: ReturnType<PerformanceMonitor['getPerformanceStatus']>;
+        metrics: ReturnType<MetricsCollector['getMetricsSummary']>;
+        config: MonitoringConfig;
+    };
+    /**
+     * Export metrics for external monitoring systems
+     */
+    exportMetrics(): {
+        prometheus?: string;
+        json: any;
+    };
+    /**
+     * Generate Prometheus-compatible metrics (without memory metrics)
+     */
+    private generatePrometheusMetrics;
+}
+/**
+ * @internal — default factory for StateMachine.monitor injection slot.
+ * Returns a new StateMachineMonitor instance (NOT a singleton).
+ */
+export declare function createDefaultMonitor(): IMonitor;
+/**
+ * Utility functions for monitoring integration
+ */
+export declare const MonitoringUtils: {
+    /**
+     * Create monitoring decorator for StateMachine methods
+     */
+    withMonitoring<T extends (...args: any[]) => any>(fn: T, monitor: StateMachineMonitor, _operationName: string): T;
+    /**
+     * Create monitoring middleware
+     */
+    createMonitoringMiddleware(monitor: StateMachineMonitor): {
+        beforeTransition: (context: any) => void;
+        afterTransition: (context: any) => void;
+        onError: (_context: any, _error: any) => void;
+    };
+};
+export {};

package/types/presets.d.ts

@@ -0,0 +1,27 @@
+import type { ValidationConfig } from './config_validator';
+import { LogLevel } from './logger';
+import type { MonitoringConfig } from './monitoring';
+export interface PresetConfig {
+    logger?: {
+        level: LogLevel;
+        enableStructuredLogging?: boolean;
+    };
+    monitoring?: Partial<MonitoringConfig>;
+    validation?: Partial<ValidationConfig>;
+}
+export declare const Presets: {
+    /**
+     * Максимальная производительность, минимум логов.
+     * Идеально для клиентской части (SPA).
+     */
+    Frontend: PresetConfig;
+    /**
+     * Полный контроль, JSON-логи, метрики.
+     * Идеально для Node.js / Microservices.
+     */
+    Backend: PresetConfig;
+    /**
+     * Режим отладки: все проверки включены, подробные логи.
+     */
+    Debug: PresetConfig;
+};

package/types/scheduler.d.ts

@@ -0,0 +1,65 @@
+import type { ITimerScheduler } from './types';
+/**
+ * Тип для идентификатора таймера
+ */
+type TimerToken = object;
+/**
+ * Планировщик таймеров на базе Min-Heap (Двоичная куча).
+ * Позволяет эффективно управлять тысячами таймеров, используя единый цикл проверки.
+ */
+export declare class TimerScheduler {
+    private heap;
+    private activeTokens;
+    private intervalId;
+    private pollingInterval;
+    constructor();
+    /**
+     * Настройка режима опроса
+     * @param interval Интервал проверки в мс. Если 0 или null - авто-тик выключается (ручной режим)
+     */
+    setPollingInterval(interval: number | null): void;
+    /**
+     * Проверка активности планировщика
+     */
+    isActive(): boolean;
+    /**
+     * Запуск единого таймера
+     */
+    start(): void;
+    /**
+     * Остановка единого таймера
+     */
+    stop(): void;
+    /**
+     * Добавить задачу
+     * @param delay задержка в мс
+     * @param callback функция для выполнения
+     * @returns токен для отмены
+     */
+    schedule(delay: number, callback: () => void): TimerToken;
+    /**
+     * Отменить задачу
+     * @param token токен задачи
+     */
+    cancel(token: TimerToken): void;
+    /**
+     * Обработать очередь (вызывается таймером или вручную)
+     */
+    process(now?: number): void;
+    /**
+     * Очистить все задачи
+     */
+    clear(): void;
+    private insert;
+    private extractMin;
+    private bubbleUp;
+    private sinkDown;
+    private swap;
+}
+/**
+ * @internal — default factory for StateMachine.scheduler injection slot.
+ * Returns a new TimerScheduler instance (NOT a singleton).
+ * Same-module placement required: TimerScheduler constructor is public within module.
+ */
+export declare function createDefaultScheduler(): ITimerScheduler;
+export {};

package/types/security.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @deprecated Will be removed in a follow-up task. Security policy enforcement should
+ * happen at the host-application layer; this module is a source-tree marker.
+ *
+ * Post TD-T3-4 pruning, symbols from this module are not reachable from `dist/index.js` —
+ * the deprecation has no public deprecation cycle, only source-tree intent.
+ *
+ * Governance treatments (multi-treatment file, per TASK-003 CODE_REVIEW F-CR3-8):
+ *   - tsconfig.json `include: ["src/**\/*"]` — typechecked under strict TS for now
+ *   - vitest.config.ts `coverage.exclude` — excluded from coverage instrumentation
+ *   - knip.json `ignore` — excluded from unused-export warnings
+ *   - package.json `files: ["dist", "types", ...]` — NOT shipped to npm (since TASK-003 CODE_REVIEW F-CR3-1)
+ *
+ * Removal trigger: when no in-tree code references the file (currently `src/tests/security.test.ts`
+ * does), delete the file plus its test plus all four governance-list entries above.
+ *
+ * Security module for safe function serialization and validation
+ * Replaces unsafe `new Function()` usage with secure alternatives
+ */
+import type { ActionOrString, ErrorHandler, ErrorHandlerOrString, EventAction } from './types';
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export interface FunctionSecurityConfig {
+    allowedFunctionNames: Set<string>;
+    maxFunctionLength: number;
+    enableValidation: boolean;
+    customPatterns?: DangerousPattern[];
+}
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export type FunctionRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export interface DangerousPattern {
+    pattern: RegExp;
+    risk: FunctionRiskLevel;
+    description: string;
+    category?: string;
+}
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export interface FunctionValidationResult {
+    isValid: boolean;
+    errors: string[];
+    riskLevel: FunctionRiskLevel;
+    detectedPatterns: string[];
+}
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export declare const DEFAULT_SECURITY_CONFIG: FunctionSecurityConfig;
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export type SafeSerializedAction = {
+    type: 'string';
+    name: string;
+} | {
+    type: 'function';
+    body: string;
+    hash: string;
+    metadata: {
+        length: number;
+        createdAt: number;
+        functionName?: string;
+    };
+};
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export declare class FunctionValidator {
+    private config;
+    private allPatterns;
+    constructor(config?: Partial<FunctionSecurityConfig>);
+    addCustomPattern(pattern: DangerousPattern): void;
+    /**
+     * Validates function body for security threats.
+     *
+     * Never throws: returns a structured result.
+     */
+    validate(body: string, functionName?: string): FunctionValidationResult;
+    /**
+     * Validates function body for security threats
+     */
+    validateFunctionBody(body: string, functionName?: string): boolean;
+    /**
+     * Creates a security hash for function validation
+     */
+    createSecurityHash(body: string, metadata: any): Promise<string>;
+    /**
+     * Validates security hash
+     */
+    validateSecurityHash(body: string, metadata: any, expectedHash: string): Promise<boolean>;
+}
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export declare class SafeFunctionSerializer {
+    validator: FunctionValidator;
+    constructor(config?: Partial<FunctionSecurityConfig>);
+    /**
+     * Safely serializes an action with security validation (Async)
+     */
+    serializeActionAsync<TOwner extends object, R = void>(action: ActionOrString<TOwner, R> | ErrorHandlerOrString<TOwner>, functionName?: string): Promise<SafeSerializedAction | undefined>;
+    /**
+     * Legacy synchronous serialization (Uses weak hash, kept for backward compatibility)
+     * @deprecated Use serializeActionAsync instead for better security
+     */
+    serializeAction<TOwner extends object, R = void>(action: ActionOrString<TOwner, R> | ErrorHandlerOrString<TOwner>, functionName?: string): SafeSerializedAction | undefined;
+    /**
+     * Safely deserializes an action with security validation (Async)
+     */
+    deserializeActionAsync<TOwner extends object, R = void>(serializedAction: SafeSerializedAction | undefined): Promise<ActionOrString<TOwner, R> | ErrorHandlerOrString<TOwner> | undefined>;
+    /**
+     * Safely deserializes an action (Synchronous - Legacy/Weak)
+     */
+    deserializeAction<TOwner extends object, R = void>(serializedAction: SafeSerializedAction | undefined): ActionOrString<TOwner, R> | ErrorHandlerOrString<TOwner> | undefined;
+    /**
+     * Safely deserializes legacy function strings (without security metadata)
+     * This method provides backward compatibility for old string-based function serialization
+     * while maintaining security through validation and sandboxing.
+     */
+    deserializeLegacyString(action: string): EventAction<any> | ErrorHandler<any> | undefined;
+    /**
+     * Creates a function safely without using new Function()
+     * Uses a whitelist approach with predefined function templates
+     */
+    private createSafeFunction;
+}
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export declare const safeFunctionSerializer: SafeFunctionSerializer;
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export declare const serializeAction: <TOwner extends object, R = void>(action: ActionOrString<TOwner, R> | ErrorHandlerOrString<TOwner>, functionName?: string) => SafeSerializedAction | undefined;
+/**
+ * @deprecated host-application-level enforcement; this module will be removed in a follow-up task.
+ */
+export declare const deserializeAction: <TOwner extends object, R = void>(serializedAction: SafeSerializedAction | undefined) => ActionOrString<TOwner, R> | ErrorHandlerOrString<TOwner> | undefined;

package/types/state_machine.d.ts

@@ -0,0 +1,227 @@
+import { type Adapter, type MethodsOf, type PropertiesOf, type StateMachineConfig, type StateMachineOptions, type StateName, type StatePersistenceAdapter } from './types';
+interface StateInfo {
+    name: string;
+    display?: string;
+    isComposite: boolean;
+    regions?: string[];
+    parent?: string;
+    children?: string[];
+}
+interface QueuedEventInfo {
+    id: string;
+    event: string;
+    age: number;
+    type: 'internal' | 'external';
+}
+export declare class StateMachine<TOwner extends object, SMConfig extends StateMachineConfig<TOwner>> {
+    private logger;
+    private monitor;
+    private scheduler;
+    private errorHandler;
+    private states;
+    private events;
+    private stateAttribute;
+    private onError?;
+    private adaptee?;
+    private context?;
+    private historyMap;
+    private initialState;
+    private persistenceAdapter?;
+    private activeTimers;
+    private stateEntryTimes;
+    private externalQueue;
+    private internalQueue;
+    private isProcessing;
+    private eventIdCounter;
+    private transitionDepth;
+    private readonly MAX_TRANSITION_DEPTH;
+    private transitionTimeout?;
+    private errorState?;
+    private abortOnExitError?;
+    private maxQueueDepth;
+    private _isTransitioning;
+    private _targetState;
+    get isTransitioning(): boolean;
+    get targetState(): string | undefined;
+    set currentState(state: StateName);
+    get currentState(): string;
+    constructor(config: SMConfig, adaptee?: Adapter<PropertiesOf<TOwner>> | PropertiesOf<TOwner>, options?: StateMachineOptions);
+    setContext(context: MethodsOf<TOwner>): void;
+    private enqueueEvent;
+    private raiseEvent;
+    private scheduleProcessing;
+    private processQueues;
+    private executeQueuedTransition;
+    /**
+     * Fires an event to trigger a state transition.
+     *
+     * @param eventName - The name of the event to fire. Use '*' for wildcard events.
+     * @param args - Additional arguments to pass to guards, actions, and callbacks.
+     * @returns Promise<boolean> - True if a transition occurred, false otherwise.
+     *
+     * @throws StateMachineError if the event is invalid or no transition is possible (unless configured otherwise).
+     *
+     * @example
+     * const success = await sm.fireEvent('submit', payload);
+     */
+    fireEvent(eventName: keyof SMConfig['events'] | '*', ...args: any[]): Promise<boolean>;
+    getQueueDepth(): {
+        internal: number;
+        external: number;
+        total: number;
+    };
+    getQueuedEvents(): QueuedEventInfo[];
+    isProcessingEvents(): boolean;
+    /**
+     * Checks if an event can be fired in the current state.
+     *
+     * @param eventName - The name of the event to check.
+     * @param adaptee - Optional adapter/object to check against (defaults to internal adaptee).
+     * @returns boolean - True if the event has a valid transition from the current state (guards are not executed).
+     */
+    canFireEvent(eventName: keyof SMConfig['events'] | '*', adaptee?: Adapter<PropertiesOf<TOwner>>): boolean;
+    getAvailableEvents(adaptee?: Adapter<PropertiesOf<TOwner>>): string[];
+    reset(adaptee?: Adapter<PropertiesOf<TOwner>>): Promise<void>;
+    getStateHistory(): Record<string, string>;
+    getCurrentStateInfo(): StateInfo | undefined;
+    /**
+     * Checks if the machine is in a specific state.
+     * Supports hierarchical states (e.g. 'parent' matches 'parent.child').
+     *
+     * @param expectedState - The state name to check.
+     * @param adaptee - Optional adapter to check against.
+     * @returns boolean - True if the current state matches or is a substate of the expected state.
+     */
+    isInState(expectedState: StateName, adaptee?: Adapter<PropertiesOf<TOwner>>): boolean;
+    attachToObject(object: any, eventMap: {
+        [key: string]: string;
+    }): void;
+    saveState(adapter?: StatePersistenceAdapter): Promise<void>;
+    restoreState(adapter?: StatePersistenceAdapter): Promise<void>;
+    static fromData<TOwner extends object, SMConfig extends StateMachineConfig<TOwner>>(config: SMConfig, initialState?: string, context?: TOwner, options?: StateMachineOptions): StateMachine<TOwner, SMConfig>;
+    static fromJSON<TOwner extends object, SMConfig extends StateMachineConfig<TOwner>>(jsonData: string, obj?: TOwner | Adapter<TOwner>, options?: StateMachineOptions): StateMachine<TOwner, SMConfig>;
+    /**
+     * Securely deserializes a StateMachine from JSON string (Async).
+     * Verifies cryptographic hashes of serialized functions.
+     */
+    static fromSecureJSON<TOwner extends object, SMConfig extends StateMachineConfig<TOwner>>(jsonData: string, obj?: TOwner | Adapter<TOwner>, options?: StateMachineOptions): Promise<StateMachine<TOwner, SMConfig>>;
+    /**
+     * Deserialize states configuration (Async)
+     */
+    private static deserializeStatesAsync;
+    /**
+     * Deserialize states configuration
+     */
+    private static deserializeStates;
+    /**
+     * Deserialize events configuration (Async)
+     */
+    private static deserializeEventsAsync;
+    /**
+     * Deserialize events configuration
+     */
+    private static deserializeEvents;
+    /**
+     * Deserialize transition configuration (Async)
+     */
+    private static deserializeTransitionAsync;
+    /**
+     * Deserialize transition configuration
+     */
+    private static deserializeTransition;
+    /**
+     * Static method for deserializing actions (Async)
+     */
+    private static deserializeActionAsync;
+    /**
+     * Static method for deserializing actions (now using safe deserializer)
+     */
+    private static deserializeAction;
+    static fromJSONWithContext<TOwner extends object, SMConfig extends StateMachineConfig<TOwner>>(jsonData: string, context?: MethodsOf<TOwner>, options?: StateMachineOptions): StateMachine<TOwner, SMConfig>;
+    private setCurrentState;
+    private setCurrentStateInternal;
+    getCurrentState(adaptee?: Adapter<PropertiesOf<TOwner>>): string | undefined;
+    private setInitialState;
+    private getInitialCompositeState;
+    private getDirectChildren;
+    private getInitialStatesForRegions;
+    private validateCompositeState;
+    private processStates;
+    private processRegions;
+    private processError;
+    private callAction;
+    private getAllowedTransitions;
+    private isTransitionPossible;
+    private isParentState;
+    private applyTransition;
+    /**
+     * Execute exit actions for a state
+     */
+    private executeExitActions;
+    /**
+     * Execute enter actions for a state
+     */
+    private executeEnterActions;
+    /**
+     * Helper to set timer (native or scheduled)
+     */
+    private setTimer;
+    /**
+     * Helper to clear timer
+     */
+    private clearTimer;
+    /**
+     * Manage state history for transitions
+     */
+    private manageStateHistory;
+    private findParentStateWithHistory;
+    private updatePartialState;
+    private updateState;
+    /**
+     * Remove conflicting states from the state map
+     */
+    private removeConflictingStates;
+    /**
+     * Add region states to the state map
+     */
+    private addRegionStates;
+    /**
+     * Clean up root states from the state map
+     */
+    private cleanupRootStates;
+    private parseCompositeState;
+    private getRegionKey;
+    private resumeTimers;
+    toJSON(): string;
+    /**
+     * Securely serializes the StateMachine to JSON (Async).
+     * Generates cryptographic hashes for all functions.
+     */
+    toSecureJSON(): Promise<string>;
+    /**
+     * Serialize state with optimized performance (Async)
+     */
+    private serializeStateAsync;
+    /**
+     * Serialize state with optimized performance
+     */
+    private serializeState;
+    /**
+     * Serialize event with optimized performance (Async)
+     */
+    private serializeEventAsync;
+    /**
+     * Serialize transition (Async)
+     */
+    private serializeTransitionAsync;
+    /**
+     * Serialize event with optimized performance
+     */
+    private serializeEvent;
+    private serializeActionAsync;
+    /**
+     * Optimized action serialization using safe serializer
+     */
+    private serializeAction;
+}
+export {};