canxjs 1.6.1 → 1.6.2

package/dist/src/core/CircuitBreaker.d.ts

@@ -0,0 +1,121 @@
+/**
+ * CanxJS Circuit Breaker - Fault tolerance for external services
+ * @description Prevents cascading failures by detecting failures and short-circuiting requests
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitBreakerConfig {
+    /** Name for logging/metrics */
+    name?: string;
+    /** Number of failures before opening circuit */
+    failureThreshold?: number;
+    /** Number of successes in half-open to close circuit */
+    successThreshold?: number;
+    /** Time in ms before attempting half-open */
+    timeout?: number;
+    /** Sliding window size in ms for failure counting */
+    windowSize?: number;
+    /** Custom failure detector */
+    isFailure?: (error: unknown) => boolean;
+    /** Fallback function when circuit is open */
+    fallback?: <T>() => T | Promise<T>;
+    /** Enable metrics collection */
+    metrics?: boolean;
+}
+interface CircuitMetrics {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    rejectedRequests: number;
+    lastFailureTime?: Date;
+    lastSuccessTime?: Date;
+    stateChanges: {
+        state: CircuitState;
+        timestamp: Date;
+    }[];
+}
+/**
+ * Circuit Breaker implementation
+ * Implements the circuit breaker pattern for fault tolerance
+ */
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private failures;
+    private successCount;
+    private lastStateChange;
+    private metrics;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit metrics
+     */
+    getMetrics(): CircuitMetrics;
+    /**
+     * Check if circuit is allowing requests
+     */
+    isAllowed(): boolean;
+    /**
+     * Execute function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record a successful call
+     */
+    private onSuccess;
+    /**
+     * Record a failed call
+     */
+    private onFailure;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Remove failures outside the sliding window
+     */
+    private cleanupOldFailures;
+    /**
+     * Force circuit to open
+     */
+    forceOpen(): void;
+    /**
+     * Force circuit to close
+     */
+    forceClose(): void;
+    /**
+     * Reset circuit to initial state
+     */
+    reset(): void;
+}
+/**
+ * Circuit Breaker Error
+ */
+export declare class CircuitBreakerError extends Error {
+    readonly circuitName: string;
+    readonly circuitState: CircuitState;
+    constructor(message: string, circuitName: string, circuitState: CircuitState);
+}
+/**
+ * Get or create a circuit breaker
+ */
+export declare function getCircuitBreaker(name: string, config?: CircuitBreakerConfig): CircuitBreaker;
+/**
+ * Create a new circuit breaker
+ */
+export declare function createCircuitBreaker(config?: CircuitBreakerConfig): CircuitBreaker;
+/**
+ * Get all circuit breaker statuses
+ */
+export declare function getCircuitBreakerStatus(): Record<string, {
+    state: CircuitState;
+    metrics: CircuitMetrics;
+}>;
+/**
+ * Decorator for circuit breaker
+ */
+export declare function WithCircuitBreaker(nameOrConfig: string | CircuitBreakerConfig): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export default CircuitBreaker;
+//# sourceMappingURL=CircuitBreaker.d.ts.map

package/dist/src/core/CircuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/core/CircuitBreaker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACxC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnC,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,UAAU,cAAc;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,IAAI,CAAC;IACvB,eAAe,CAAC,EAAE,IAAI,CAAC;IACvB,YAAY,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;CAC1D;AAOD;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAqG;IACnH,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,OAAO,CAAiB;gBAEpB,MAAM,GAAE,oBAAyB;IAqB7C;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;OAEG;IACH,UAAU,IAAI,cAAc;IAI5B;;OAEG;IACH,SAAS,IAAI,OAAO;IAiBpB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA+BlD;;OAEG;IACH,OAAO,CAAC,SAAS;IAkBjB;;OAEG;IACH,OAAO,CAAC,SAAS;IAuBjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAiBpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAK1B;;OAEG;IACH,SAAS,IAAI,IAAI;IAIjB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,KAAK,IAAI,IAAI;CAad;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,WAAW,EAAE,MAAM;aACnB,YAAY,EAAE,YAAY;gBAF1C,OAAO,EAAE,MAAM,EACC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,YAAY;CAK7C;AAQD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAK7F;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,oBAAyB,GAAG,cAAc,CAMtF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC,CAS1G;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,IAC3D,QAAQ,GAAG,EAAE,aAAa,MAAM,EAAE,YAAY,kBAAkB,wBAWlF;AAED,eAAe,cAAc,CAAC"}

package/dist/src/core/CircuitBreaker.js

@@ -0,0 +1,250 @@
+/**
+ * CanxJS Circuit Breaker - Fault tolerance for external services
+ * @description Prevents cascading failures by detecting failures and short-circuiting requests
+ */
+/**
+ * Circuit Breaker implementation
+ * Implements the circuit breaker pattern for fault tolerance
+ */
+export class CircuitBreaker {
+    config;
+    state = 'CLOSED';
+    failures = [];
+    successCount = 0;
+    lastStateChange = new Date();
+    metrics;
+    constructor(config = {}) {
+        this.config = {
+            name: config.name ?? 'default',
+            failureThreshold: config.failureThreshold ?? 5,
+            successThreshold: config.successThreshold ?? 2,
+            timeout: config.timeout ?? 30000,
+            windowSize: config.windowSize ?? 60000,
+            isFailure: config.isFailure ?? (() => true),
+            metrics: config.metrics ?? true,
+            fallback: config.fallback,
+        };
+        this.metrics = {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            rejectedRequests: 0,
+            stateChanges: [{ state: 'CLOSED', timestamp: new Date() }],
+        };
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get circuit metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Check if circuit is allowing requests
+     */
+    isAllowed() {
+        this.cleanupOldFailures();
+        switch (this.state) {
+            case 'CLOSED':
+                return true;
+            case 'OPEN':
+                if (Date.now() - this.lastStateChange.getTime() >= this.config.timeout) {
+                    this.transitionTo('HALF_OPEN');
+                    return true;
+                }
+                return false;
+            case 'HALF_OPEN':
+                return true;
+        }
+    }
+    /**
+     * Execute function with circuit breaker protection
+     */
+    async execute(fn) {
+        this.metrics.totalRequests++;
+        if (!this.isAllowed()) {
+            this.metrics.rejectedRequests++;
+            if (this.config.fallback) {
+                return this.config.fallback();
+            }
+            throw new CircuitBreakerError(`Circuit breaker '${this.config.name}' is OPEN`, this.config.name, this.state);
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            if (this.config.isFailure(error)) {
+                this.onFailure(error);
+            }
+            else {
+                this.onSuccess();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Record a successful call
+     */
+    onSuccess() {
+        this.metrics.successfulRequests++;
+        this.metrics.lastSuccessTime = new Date();
+        switch (this.state) {
+            case 'HALF_OPEN':
+                this.successCount++;
+                if (this.successCount >= this.config.successThreshold) {
+                    this.transitionTo('CLOSED');
+                }
+                break;
+            case 'CLOSED':
+                // Reset failure count on success in closed state
+                this.failures = [];
+                break;
+        }
+    }
+    /**
+     * Record a failed call
+     */
+    onFailure(error) {
+        this.metrics.failedRequests++;
+        this.metrics.lastFailureTime = new Date();
+        this.failures.push({
+            timestamp: Date.now(),
+            error,
+        });
+        this.cleanupOldFailures();
+        switch (this.state) {
+            case 'CLOSED':
+                if (this.failures.length >= this.config.failureThreshold) {
+                    this.transitionTo('OPEN');
+                }
+                break;
+            case 'HALF_OPEN':
+                this.transitionTo('OPEN');
+                break;
+        }
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState) {
+        if (this.state === newState)
+            return;
+        console.log(`[CircuitBreaker:${this.config.name}] ${this.state} → ${newState}`);
+        this.state = newState;
+        this.lastStateChange = new Date();
+        this.metrics.stateChanges.push({ state: newState, timestamp: this.lastStateChange });
+        if (newState === 'CLOSED') {
+            this.failures = [];
+            this.successCount = 0;
+        }
+        else if (newState === 'HALF_OPEN') {
+            this.successCount = 0;
+        }
+    }
+    /**
+     * Remove failures outside the sliding window
+     */
+    cleanupOldFailures() {
+        const cutoff = Date.now() - this.config.windowSize;
+        this.failures = this.failures.filter(f => f.timestamp > cutoff);
+    }
+    /**
+     * Force circuit to open
+     */
+    forceOpen() {
+        this.transitionTo('OPEN');
+    }
+    /**
+     * Force circuit to close
+     */
+    forceClose() {
+        this.transitionTo('CLOSED');
+    }
+    /**
+     * Reset circuit to initial state
+     */
+    reset() {
+        this.state = 'CLOSED';
+        this.failures = [];
+        this.successCount = 0;
+        this.lastStateChange = new Date();
+        this.metrics = {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            rejectedRequests: 0,
+            stateChanges: [{ state: 'CLOSED', timestamp: new Date() }],
+        };
+    }
+}
+/**
+ * Circuit Breaker Error
+ */
+export class CircuitBreakerError extends Error {
+    circuitName;
+    circuitState;
+    constructor(message, circuitName, circuitState) {
+        super(message);
+        this.circuitName = circuitName;
+        this.circuitState = circuitState;
+        this.name = 'CircuitBreakerError';
+    }
+}
+// ============================================
+// Circuit Breaker Registry
+// ============================================
+const circuitRegistry = new Map();
+/**
+ * Get or create a circuit breaker
+ */
+export function getCircuitBreaker(name, config) {
+    if (!circuitRegistry.has(name)) {
+        circuitRegistry.set(name, new CircuitBreaker({ ...config, name }));
+    }
+    return circuitRegistry.get(name);
+}
+/**
+ * Create a new circuit breaker
+ */
+export function createCircuitBreaker(config = {}) {
+    const breaker = new CircuitBreaker(config);
+    if (config.name) {
+        circuitRegistry.set(config.name, breaker);
+    }
+    return breaker;
+}
+/**
+ * Get all circuit breaker statuses
+ */
+export function getCircuitBreakerStatus() {
+    const status = {};
+    for (const [name, breaker] of circuitRegistry) {
+        status[name] = {
+            state: breaker.getState(),
+            metrics: breaker.getMetrics(),
+        };
+    }
+    return status;
+}
+/**
+ * Decorator for circuit breaker
+ */
+export function WithCircuitBreaker(nameOrConfig) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const config = typeof nameOrConfig === 'string' ? { name: nameOrConfig } : nameOrConfig;
+        descriptor.value = async function (...args) {
+            const breaker = getCircuitBreaker(config.name ?? propertyKey, config);
+            return breaker.execute(() => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+export default CircuitBreaker;

package/dist/src/core/ClusterManager.d.ts

@@ -0,0 +1,122 @@
+/**
+ * CanxJS Cluster Manager - Multi-process clustering for enterprise scaling
+ * @description Enables horizontal scaling across all CPU cores
+ */
+export interface ClusterConfig {
+    /** Enable cluster mode */
+    enabled?: boolean;
+    /** Number of workers (default: CPU cores) */
+    workers?: number | 'auto';
+    /** Restart workers on crash */
+    restartOnCrash?: boolean;
+    /** Max restarts before giving up */
+    maxRestarts?: number;
+    /** Restart delay in ms */
+    restartDelay?: number;
+    /** Grace period for shutdown in ms */
+    gracePeriod?: number;
+    /** Enable sticky sessions (for WebSocket) */
+    stickySessions?: boolean;
+}
+interface WorkerInfo {
+    id: number;
+    pid: number;
+    status: 'starting' | 'running' | 'stopping' | 'dead';
+    restarts: number;
+    startedAt: Date;
+    lastHeartbeat?: Date;
+}
+type MessageHandler = (message: WorkerMessage) => void;
+interface WorkerMessage {
+    type: 'ready' | 'heartbeat' | 'shutdown' | 'metrics' | 'custom';
+    workerId?: number;
+    data?: unknown;
+}
+/**
+ * Cluster Manager for CanxJS
+ * Manages worker processes for horizontal scaling
+ */
+export declare class ClusterManager {
+    private config;
+    private workers;
+    private isShuttingDown;
+    private messageHandlers;
+    private workerProcesses;
+    private masterStartTime;
+    constructor(config?: ClusterConfig);
+    /**
+     * Check if running as primary/master process
+     */
+    get isPrimary(): boolean;
+    /**
+     * Check if running as worker process
+     */
+    get isWorker(): boolean;
+    /**
+     * Get current worker ID (if worker)
+     */
+    get workerId(): number | null;
+    /**
+     * Get number of configured workers
+     */
+    get workerCount(): number;
+    /**
+     * Start cluster with given app function
+     */
+    start(appFn: () => Promise<void> | void): Promise<void>;
+    /**
+     * Start primary/master process
+     */
+    private startPrimary;
+    /**
+     * Spawn a new worker process
+     */
+    private spawnWorker;
+    /**
+     * Handle worker exit
+     */
+    private handleWorkerExit;
+    /**
+     * Start worker process
+     */
+    private startWorker;
+    /**
+     * Setup signal handlers for graceful shutdown
+     */
+    private setupSignalHandlers;
+    /**
+     * Primary process main loop
+     */
+    private runPrimaryLoop;
+    /**
+     * Get cluster status
+     */
+    getStatus(): {
+        isPrimary: boolean;
+        uptime: number;
+        workers: WorkerInfo[];
+        totalRestarts: number;
+    };
+    /**
+     * Register message handler
+     */
+    onMessage(handler: MessageHandler): void;
+    /**
+     * Broadcast message to all workers
+     */
+    broadcast(message: WorkerMessage): void;
+}
+/**
+ * Initialize cluster mode
+ */
+export declare function initCluster(config?: ClusterConfig): ClusterManager;
+/**
+ * Get cluster manager instance
+ */
+export declare function cluster(): ClusterManager;
+/**
+ * Cluster mode decorator/wrapper
+ */
+export declare function withCluster(config: ClusterConfig, appFn: () => Promise<void> | void): Promise<void>;
+export default ClusterManager;
+//# sourceMappingURL=ClusterManager.d.ts.map

package/dist/src/core/ClusterManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClusterManager.d.ts","sourceRoot":"","sources":["../../../src/core/ClusterManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAED,KAAK,cAAc,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;AAEvD,UAAU,aAAa;IACrB,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,eAAe,CAAoB;gBAE/B,MAAM,GAAE,aAAkB;IActC;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAG5B;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D;;OAEG;YACW,YAAY;IAyB1B;;OAEG;YACW,WAAW;IA0CzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;OAEG;YACW,WAAW;IAWzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2C3B;;OAEG;YACW,cAAc;IAiB5B;;OAEG;IACH,SAAS,IAAI;QACX,SAAS,EAAE,OAAO,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,UAAU,EAAE,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACvB;IAUD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;CAQxC;AAOD;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,cAAc,CAKlE;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,cAAc,CAKxC;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,eAAe,cAAc,CAAC"}