@vedmalex/statemachine 1.0.0-beta.1

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@vedmalex/statemachine",
+  "version": "1.0.0-beta.1",
+  "description": "Hierarchical state machine for TypeScript with monitoring, validation, and persistence (lite-only DI-free surface).",
+  "keywords": [
+    "state-machine",
+    "statemachine",
+    "hierarchical",
+    "lite",
+    "wasm-friendly"
+  ],
+  "author": "vedmalex (Vedanta-krit das)",
+  "license": "MIT",
+  "homepage": "https://github.com/vedmalex/statemachine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vedmalex/statemachine.git",
+    "directory": "packages/statemachine"
+  },
+  "bugs": {
+    "url": "https://github.com/vedmalex/statemachine/issues"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rm -rf dist types coverage tsconfig.tsbuildinfo",
+    "build": "npm run clean && tsup && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:cjs-smoke": "node test/cjs-smoke/smoke.cjs",
+    "test:deno-smoke": "deno run -A test/deno-smoke.ts",
+    "test:browser": "playwright test",
+    "knip": "knip --no-progress",
+    "api:check": "api-extractor run --local --verbose",
+    "prepublishOnly": "npm run build && node test/verify-dist.cjs"
+  },
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@microsoft/api-extractor": "^7.58.7",
+    "@playwright/test": "^1.59.1",
+    "@types/bun": "^1.2.16",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-istanbul": "^4.1.5",
+    "@vitest/coverage-v8": "^4.1.5",
+    "knip": "^6.11.0",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.19",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/adapters.d.ts

@@ -0,0 +1,30 @@
+import type { Adapter, StatePersistenceAdapter } from './types';
+/**
+ * Interface for a minimal state machine that can be updated from the adapter
+ */
+interface ISyncableStateMachine {
+    restoreState(): Promise<void>;
+}
+/**
+ * BroadcastChannelAdapter wraps any other adapter and synchronizes state across browser tabs/windows
+ */
+export declare class BroadcastChannelAdapter<T extends object> implements Adapter<T>, StatePersistenceAdapter {
+    adaptee: T;
+    private inner;
+    private channel;
+    private sm?;
+    constructor(inner: Adapter<T> & Partial<StatePersistenceAdapter>, channelName: string);
+    /**
+     * Bind a state machine instance to this adapter for automatic updates
+     */
+    bindStateMachine(sm: ISyncableStateMachine): void;
+    get(property: keyof T): T[keyof T];
+    set(property: keyof T, value: T[keyof T]): void;
+    save(state?: any): Promise<void>;
+    restore(): Promise<any>;
+    /**
+     * Close the underlying BroadcastChannel
+     */
+    destroy(): void;
+}
+export {};

package/types/config_validator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Configuration validation module for StateMachine library
+ * Validates StateMachine configurations to prevent runtime errors
+ */
+import type { StateMachineConfig } from './types';
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export interface ValidationError {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+    path: string;
+    details?: Record<string, any>;
+    suggestion?: string;
+    documentationUrl?: string;
+}
+export interface ValidationWarning extends ValidationError {
+    severity: 'warning';
+}
+interface ValidationContext {
+    addError(code: string, message: string, path: string, suggestion?: string): void;
+    addWarning(code: string, message: string, path: string, suggestion?: string): void;
+}
+type CustomRule<T extends object = any> = {
+    id: string;
+    validate: (config: StateMachineConfig<T>, context: ValidationContext) => void;
+};
+export interface ValidationConfig {
+    strictMode: boolean;
+    allowEmptyStates: boolean;
+    allowEmptyEvents: boolean;
+    maxStateDepth: number;
+    maxStatesCount: number;
+    maxEventsCount: number;
+    requireInitialState: boolean;
+    validateTransitionPaths: boolean;
+    validateActionReferences: boolean;
+    customRules?: CustomRule[];
+}
+export declare const DEFAULT_VALIDATION_CONFIG: ValidationConfig;
+export declare class ConfigValidator {
+    private config;
+    private errors;
+    private warnings;
+    constructor(config?: Partial<ValidationConfig>);
+    /**
+     * Validates a complete StateMachine configuration
+     */
+    validate<T extends object>(smConfig: StateMachineConfig<T>): ValidationResult;
+    /**
+     * Runs custom validation rules
+     */
+    private runCustomRules;
+    private validateBasicStructure;
+    private validateStates;
+    private validateState;
+    private validateEvents;
+    private validateEvent;
+    private validateTransition;
+    private validateStatePath;
+    private isValidStatePath;
+    private validateInitialState;
+    private validateCrossReferences;
+    private collectStateNames;
+    private validatePerformanceConstraints;
+    private countStates;
+    private addError;
+    private addWarning;
+}
+export declare function validateConfig<T extends object>(config: StateMachineConfig<T>, validationConfig?: Partial<ValidationConfig>): ValidationResult;
+export declare function validateConfigStrict<T extends object>(config: StateMachineConfig<T>): ValidationResult;
+export declare function isValidConfig<T extends object>(config: StateMachineConfig<T>): boolean;
+export {};

package/types/error_handling.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Enhanced error handling module for StateMachine library
+ * Provides comprehensive error context, recovery strategies, and error analytics
+ */
+import { type ErrorContext, StateMachineError } from './types';
+export interface ExtendedErrorContext extends ErrorContext {
+    timestamp: number;
+    machineId?: string;
+    currentStateHistory?: string[];
+    attemptedTransition?: {
+        from: string;
+        to: string;
+        event: string;
+    };
+    stackTrace?: string | undefined;
+    userAgent?: string | undefined;
+    sessionId?: string | undefined;
+    additionalData?: Record<string, any> | undefined;
+}
+export declare const ErrorSeverity: {
+    readonly LOW: "low";
+    readonly MEDIUM: "medium";
+    readonly HIGH: "high";
+    readonly CRITICAL: "critical";
+};
+export type ErrorSeverity = (typeof ErrorSeverity)[keyof typeof ErrorSeverity];
+export declare const ErrorCategory: {
+    readonly VALIDATION: "validation";
+    readonly TRANSITION: "transition";
+    readonly ACTION: "action";
+    readonly SERIALIZATION: "serialization";
+    readonly CONFIGURATION: "configuration";
+    readonly SECURITY: "security";
+    readonly PERFORMANCE: "performance";
+    readonly NETWORK: "network";
+    readonly UNKNOWN: "unknown";
+};
+export type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+export declare class EnhancedStateMachineError extends StateMachineError {
+    readonly severity: ErrorSeverity;
+    readonly category: ErrorCategory;
+    readonly extendedContext: ExtendedErrorContext;
+    readonly recoverable: boolean;
+    readonly errorCode: string;
+    constructor(message: string, context: ErrorContext, options?: {
+        severity?: ErrorSeverity;
+        category?: ErrorCategory;
+        recoverable?: boolean;
+        errorCode?: string;
+        additionalData?: Record<string, any>;
+        cause?: Error;
+    });
+    private generateErrorCode;
+    toJSON(): Record<string, any>;
+}
+export interface ErrorRecoveryStrategy {
+    name: string;
+    canRecover(error: EnhancedStateMachineError): boolean;
+    recover(error: EnhancedStateMachineError, context: any): Promise<boolean>;
+}
+export declare class RetryRecoveryStrategy implements ErrorRecoveryStrategy {
+    name: string;
+    private maxRetries;
+    private retryDelay;
+    constructor(maxRetries?: number, retryDelay?: number);
+    canRecover(error: EnhancedStateMachineError): boolean;
+    recover(error: EnhancedStateMachineError, context: any): Promise<boolean>;
+}
+export declare class FallbackStateRecoveryStrategy implements ErrorRecoveryStrategy {
+    name: string;
+    private fallbackState;
+    constructor(fallbackState?: string);
+    canRecover(error: EnhancedStateMachineError): boolean;
+    recover(error: EnhancedStateMachineError, context: any): Promise<boolean>;
+}
+export declare class ErrorAnalytics {
+    private errors;
+    private maxStoredErrors;
+    constructor(maxStoredErrors?: number);
+    recordError(error: EnhancedStateMachineError): void;
+    getErrorStats(): {
+        total: number;
+        bySeverity: Record<ErrorSeverity, number>;
+        byCategory: Record<ErrorCategory, number>;
+        recentErrors: number;
+        errorRate: number;
+    };
+    getTopErrors(limit?: number): Array<{
+        errorCode: string;
+        message: string;
+        count: number;
+        lastOccurrence: number;
+        severity: ErrorSeverity;
+        category: ErrorCategory;
+    }>;
+    clearErrors(): void;
+}
+export declare class ErrorHandler {
+    private recoveryStrategies;
+    private analytics;
+    private enabled;
+    constructor();
+    addRecoveryStrategy(strategy: ErrorRecoveryStrategy): void;
+    removeRecoveryStrategy(strategyName: string): void;
+    handleError(error: Error | EnhancedStateMachineError, context?: any): Promise<boolean>;
+    private convertToEnhancedError;
+    getAnalytics(): ErrorAnalytics;
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+}
+/**
+ * @internal — default factory for StateMachine.errorHandler injection slot.
+ * Returns a new ErrorHandler instance (NOT a singleton).
+ * Constructor at line 343 is public (verified).
+ */
+export declare function createDefaultErrorHandler(): import('./types').IErrorHandler;
+export declare function createEnhancedError(message: string, context: ErrorContext, options?: {
+    severity?: ErrorSeverity;
+    category?: ErrorCategory;
+    recoverable?: boolean;
+    additionalData?: Record<string, any>;
+}): EnhancedStateMachineError;
+export declare function isRecoverableError(error: Error): boolean;

package/types/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @packageDocumentation
+ *
+ * @vedmalex/statemachine — hierarchical state machine for TypeScript.
+ *
+ * @unstable — full surface defaults to @unstable per the package's STABILITY policy.
+ * Per-symbol @stable tags below mark firm exports for the 1.0.0-beta.x consumer contract.
+ *
+ * @see README.md for usage and stability policy.
+ */
+/**
+ * @stable — primary factory; the canonical consumer entry point.
+ * @category Stable
+ */
+export { createMachine } from './lite';
+/**
+ * @stable — class form for advanced consumers needing direct instance access.
+ * @category Stable
+ */
+export { StateMachine } from './state_machine';
+/**
+ * @stable — top-level machine configuration interface.
+ * @category Stable
+ */
+export type { StateMachineConfig } from './types';
+/**
+ * @stable — transition descriptor used in events.
+ * @category Stable
+ */
+export type { Transition } from './types';
+/**
+ * @stable — state node shape; consumed by States<T> map.
+ * @category Stable
+ */
+export type { State } from './types';
+/**
+ * @category Unstable
+ */
+export type { States, Events, Event, Adapter, StateMachineOptions, RegionsConfig, StateInvocation, StateName, EventName, RegionName, EventAction, ErrorHandler, ActionOrString, ErrorHandlerOrString, RegionStateName, NestedStateName, DeepNestedStateName, StatePaths, SimpleStateName, MethodsOf, PropertiesOf, KeysOf, ExtractAdaptee, ErrorContext, } from './types';
+export { MemoryAdapter, LocalStorageAdapter, SessionStorageAdapter, ServerAdapter, StateMachineError, isAdapter, } from './types';
+export { createEnhancedError, EnhancedStateMachineError, ErrorAnalytics, ErrorCategory, type ErrorCategory as ErrorCategoryType, ErrorHandler as EnhancedErrorHandler, type ErrorRecoveryStrategy, ErrorSeverity, type ErrorSeverity as ErrorSeverityType, type ExtendedErrorContext, FallbackStateRecoveryStrategy, isRecoverableError, RetryRecoveryStrategy, } from './error_handling';
+export { validateConfig, validateConfigStrict, isValidConfig, type ValidationResult, type ValidationError, type ValidationWarning, } from './config_validator';
+/**
+ * @category Unstable
+ * @unstable — observability injection contract; implement to collect per-machine metrics.
+ */
+export type { IMonitor } from './types';
+/**
+ * @category Unstable
+ * @unstable — timer scheduling injection contract; implement for WASM/host portability.
+ */
+export type { ITimerScheduler } from './types';
+/**
+ * @category Unstable
+ * @unstable — error-handler injection contract; implement to replace built-in recovery.
+ */
+export type { IErrorHandler } from './types';
+/**
+ * @category Unstable
+ * @unstable — logging injection contract; implement to route logs to host logging stack.
+ */
+export type { ILogger } from './types';
+/**
+ * @category Unstable
+ * @unstable — persistence adapter contract; implement to save/restore machine state.
+ */
+export type { StatePersistenceAdapter } from './types';
+/**
+ * @category Unstable
+ * @unstable — transition observability context passed to IMonitor.recordTransition.
+ */
+export type { TransitionContext } from './types';
+/**
+ * @category Unstable
+ * @unstable — aggregate observability snapshot returned by IMonitor.getMetrics.
+ */
+export type { MonitorMetricsSnapshot } from './types';

package/types/lite.d.ts

@@ -0,0 +1,6 @@
+import { StateMachine } from './state_machine';
+import { type Adapter, type StateMachineConfig, type StateMachineOptions } from './types';
+/**
+ * Public factory for @vedmalex/statemachine. DI-free; the only factory in this package.
+ */
+export declare function createMachine<T extends object>(config: StateMachineConfig<T>, owner?: T | Adapter<T>, options?: StateMachineOptions): StateMachine<T, any>;

package/types/logger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Professional logging system for StateMachine library
+ * Replaces console.log/console.error with configurable, structured logging
+ */
+export declare const LogLevel: {
+    readonly DEBUG: 0;
+    readonly INFO: 1;
+    readonly WARN: 2;
+    readonly ERROR: 3;
+    readonly FATAL: 4;
+    readonly OFF: 5;
+};
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+interface LogEntry {
+    timestamp: number;
+    level: LogLevel;
+    message: string;
+    context?: Record<string, any>;
+    error?: Error;
+    source: string;
+}
+interface LoggerConfig {
+    level: LogLevel;
+    enableConsole: boolean;
+    enableStructuredLogging: boolean;
+    timestampFormat: 'iso' | 'unix' | 'relative';
+    includeStackTrace: boolean;
+}
+export declare const DEFAULT_LOGGER_CONFIG: LoggerConfig;
+interface LogAppender {
+    append(entry: LogEntry): void;
+}
+export declare class ConsoleAppender implements LogAppender {
+    private config;
+    constructor(config: LoggerConfig);
+    append(entry: LogEntry): void;
+    private formatTimestamp;
+}
+export declare class MemoryAppender implements LogAppender {
+    private entries;
+    append(entry: LogEntry): void;
+    getEntries(): LogEntry[];
+    clear(): void;
+    getEntriesByLevel(level: LogLevel): LogEntry[];
+}
+export declare class Logger {
+    private config;
+    private appenders;
+    private source;
+    constructor(source: string, config?: Partial<LoggerConfig>);
+    addAppender(appender: LogAppender): void;
+    removeAppender(appender: LogAppender): void;
+    updateConfig(config: Partial<LoggerConfig>): void;
+    isLevelEnabled(level: LogLevel): boolean;
+    private log;
+    debug(message: string, context?: Record<string, any>): void;
+    info(message: string, context?: Record<string, any>): void;
+    warn(message: string, context?: Record<string, any>): void;
+    error(message: string, context?: Record<string, any>, error?: Error): void;
+    fatal(message: string, context?: Record<string, any>, error?: Error): void;
+    child(childSource: string, _additionalContext?: Record<string, any>): Logger;
+}
+export declare class LoggerFactory {
+    private static defaultConfig;
+    private static loggers;
+    static setDefaultConfig(config: Partial<LoggerConfig>): void;
+    static getLogger(source: string, config?: Partial<LoggerConfig>): Logger;
+    static clearLoggers(): void;
+}
+export declare const getLogger: typeof LoggerFactory.getLogger;
+export declare const setDefaultLogLevel: (level: LogLevel) => void;
+export declare const stateMachineLogger: Logger;
+export declare const securityLogger: Logger;
+export {};