specmem-hardwicksoftware 3.5.99

package/dist/utils/circuitBreaker.d.ts

@@ -0,0 +1,195 @@
+/**
+ * circuitBreaker.ts - Circuit Breaker Pattern for External Calls
+ *
+ * yo this protects us from cascading failures
+ * when the database is down we dont keep hammering it fr fr
+ * fail fast, recover gracefully
+ *
+ * Issue #44 fix - circuit breaker for external calls
+ */
+/**
+ * Circuit breaker states
+ */
+export declare enum CircuitState {
+    CLOSED = "CLOSED",// Normal operation - calls go through
+    OPEN = "OPEN",// Failing - calls blocked
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+    /** Name for logging */
+    name: string;
+    /** Error threshold percentage (0-100) to trip the breaker */
+    errorThresholdPercentage: number;
+    /** Minimum number of requests before error threshold is calculated */
+    requestVolumeThreshold: number;
+    /** Time in ms before attempting to close the circuit */
+    sleepWindowMs: number;
+    /** Timeout for individual calls in ms */
+    timeoutMs: number;
+    /** Number of successful calls in half-open state to close circuit */
+    successThreshold: number;
+}
+/**
+ * Circuit breaker stats
+ */
+export interface CircuitBreakerStats {
+    name: string;
+    state: CircuitState;
+    totalCalls: number;
+    successfulCalls: number;
+    failedCalls: number;
+    timedOutCalls: number;
+    rejectedCalls: number;
+    errorRate: number;
+    lastFailure: Date | null;
+    lastSuccess: Date | null;
+    lastStateChange: Date | null;
+}
+/**
+ * CircuitBreaker - prevents cascading failures
+ *
+ * Features that SAVE US:
+ * - Automatic state management
+ * - Configurable thresholds
+ * - Timeout wrapping
+ * - Statistics tracking
+ * - Gradual recovery (half-open state)
+ */
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private lastSuccessTime;
+    private lastStateChangeTime;
+    private halfOpenSuccesses;
+    private totalCalls;
+    private rejectedCalls;
+    private timedOutCalls;
+    private recentCalls;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute with timeout wrapper
+     */
+    private executeWithTimeout;
+    /**
+     * Record successful call
+     */
+    private recordSuccess;
+    /**
+     * Record failed call
+     */
+    private recordFailure;
+    /**
+     * Check if circuit should trip open
+     */
+    private shouldTrip;
+    /**
+     * Calculate current error rate
+     */
+    private calculateErrorRate;
+    /**
+     * Check if we should attempt to reset the circuit
+     */
+    private shouldAttemptReset;
+    /**
+     * Trim recent calls to rolling window
+     */
+    private trimRecentCalls;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Get current state
+     */
+    getState(): CircuitState;
+    /**
+     * Get statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Force close the circuit (for recovery scenarios)
+     */
+    forceClose(): void;
+    /**
+     * Force open the circuit (for maintenance scenarios)
+     */
+    forceOpen(): void;
+    /**
+     * Reset all statistics
+     */
+    reset(): void;
+}
+/**
+ * Circuit breaker error - thrown when circuit is open
+ */
+export declare class CircuitBreakerError extends Error {
+    readonly breakerName: string;
+    readonly isCircuitBreakerError = true;
+    constructor(message: string, breakerName: string);
+}
+/**
+ * Circuit breaker timeout error
+ */
+export declare class CircuitBreakerTimeoutError extends Error {
+    readonly breakerName: string;
+    readonly isTimeout = true;
+    constructor(message: string, breakerName: string);
+}
+/**
+ * Circuit breaker registry - manage multiple breakers
+ */
+declare class CircuitBreakerRegistry {
+    private breakers;
+    /**
+     * Get or create a circuit breaker
+     */
+    getBreaker(name: string, config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+    /**
+     * Get all breaker stats
+     */
+    getAllStats(): CircuitBreakerStats[];
+    /**
+     * Reset all breakers
+     */
+    resetAll(): void;
+    /**
+     * Remove a breaker
+     */
+    removeBreaker(name: string): boolean;
+    /**
+     * Clear all breakers
+     */
+    clear(): void;
+}
+/**
+ * Get the global circuit breaker registry
+ */
+export declare function getCircuitBreakerRegistry(): CircuitBreakerRegistry;
+/**
+ * Reset the global registry
+ */
+export declare function resetCircuitBreakerRegistry(): void;
+/**
+ * Convenience function - get or create a circuit breaker
+ */
+export declare function getCircuitBreaker(name: string, config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+/**
+ * Pre-configured circuit breaker for database operations
+ */
+export declare const DATABASE_BREAKER_CONFIG: Partial<CircuitBreakerConfig>;
+/**
+ * Pre-configured circuit breaker for external API calls
+ */
+export declare const API_BREAKER_CONFIG: Partial<CircuitBreakerConfig>;
+export {};
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/utils/circuitBreaker.d.ts.map

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

package/dist/utils/circuitBreaker.js

@@ -0,0 +1,374 @@
+/**
+ * circuitBreaker.ts - Circuit Breaker Pattern for External Calls
+ *
+ * yo this protects us from cascading failures
+ * when the database is down we dont keep hammering it fr fr
+ * fail fast, recover gracefully
+ *
+ * Issue #44 fix - circuit breaker for external calls
+ */
+import { logger } from './logger.js';
+/**
+ * Circuit breaker states
+ */
+export var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "CLOSED";
+    CircuitState["OPEN"] = "OPEN";
+    CircuitState["HALF_OPEN"] = "HALF_OPEN"; // Testing - allowing limited calls
+})(CircuitState || (CircuitState = {}));
+const DEFAULT_CONFIG = {
+    name: 'default',
+    errorThresholdPercentage: 50,
+    requestVolumeThreshold: 10,
+    sleepWindowMs: parseInt(process.env['SPECMEM_CIRCUIT_SLEEP_MS'] || '10000', 10), // 10 seconds default
+    timeoutMs: parseInt(process.env['SPECMEM_CIRCUIT_TIMEOUT_MS'] || '30000', 10), // 30 seconds default
+    successThreshold: 5
+};
+/**
+ * CircuitBreaker - prevents cascading failures
+ *
+ * Features that SAVE US:
+ * - Automatic state management
+ * - Configurable thresholds
+ * - Timeout wrapping
+ * - Statistics tracking
+ * - Gradual recovery (half-open state)
+ */
+export class CircuitBreaker {
+    config;
+    state = CircuitState.CLOSED;
+    failures = 0;
+    successes = 0;
+    lastFailureTime = null;
+    lastSuccessTime = null;
+    lastStateChangeTime = new Date();
+    halfOpenSuccesses = 0;
+    totalCalls = 0;
+    rejectedCalls = 0;
+    timedOutCalls = 0;
+    recentCalls = [];
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    async execute(fn) {
+        this.totalCalls++;
+        // Check if circuit is open
+        if (this.state === CircuitState.OPEN) {
+            if (this.shouldAttemptReset()) {
+                this.transitionTo(CircuitState.HALF_OPEN);
+            }
+            else {
+                this.rejectedCalls++;
+                logger.debug({
+                    breaker: this.config.name,
+                    state: this.state
+                }, 'circuit breaker rejected call');
+                throw new CircuitBreakerError(`Circuit breaker ${this.config.name} is OPEN`, this.config.name);
+            }
+        }
+        try {
+            // Execute with timeout
+            const result = await this.executeWithTimeout(fn);
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            this.recordFailure(error);
+            throw error;
+        }
+    }
+    /**
+     * Execute with timeout wrapper
+     */
+    async executeWithTimeout(fn) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.timedOutCalls++;
+                reject(new CircuitBreakerTimeoutError(`Operation timed out after ${this.config.timeoutMs}ms`, this.config.name));
+            }, this.config.timeoutMs);
+            fn()
+                .then((result) => {
+                clearTimeout(timeoutId);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Record successful call
+     */
+    recordSuccess() {
+        this.successes++;
+        this.lastSuccessTime = new Date();
+        // Track recent calls for rolling window
+        this.recentCalls.push({ success: true, timestamp: Date.now() });
+        this.trimRecentCalls();
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.config.successThreshold) {
+                this.transitionTo(CircuitState.CLOSED);
+            }
+        }
+        logger.trace({
+            breaker: this.config.name,
+            state: this.state,
+            successes: this.successes
+        }, 'circuit breaker success');
+    }
+    /**
+     * Record failed call
+     */
+    recordFailure(error) {
+        this.failures++;
+        this.lastFailureTime = new Date();
+        // Track recent calls for rolling window
+        this.recentCalls.push({ success: false, timestamp: Date.now() });
+        this.trimRecentCalls();
+        if (this.state === CircuitState.HALF_OPEN) {
+            // Any failure in half-open state opens the circuit again
+            this.transitionTo(CircuitState.OPEN);
+        }
+        else if (this.shouldTrip()) {
+            this.transitionTo(CircuitState.OPEN);
+        }
+        logger.debug({
+            breaker: this.config.name,
+            state: this.state,
+            failures: this.failures,
+            error: error instanceof Error ? error.message : 'unknown'
+        }, 'circuit breaker failure');
+    }
+    /**
+     * Check if circuit should trip open
+     */
+    shouldTrip() {
+        if (this.recentCalls.length < this.config.requestVolumeThreshold) {
+            return false;
+        }
+        const errorRate = this.calculateErrorRate();
+        return errorRate >= this.config.errorThresholdPercentage;
+    }
+    /**
+     * Calculate current error rate
+     */
+    calculateErrorRate() {
+        if (this.recentCalls.length === 0)
+            return 0;
+        const failures = this.recentCalls.filter(c => !c.success).length;
+        return (failures / this.recentCalls.length) * 100;
+    }
+    /**
+     * Check if we should attempt to reset the circuit
+     */
+    shouldAttemptReset() {
+        if (!this.lastFailureTime)
+            return true;
+        const elapsed = Date.now() - this.lastFailureTime.getTime();
+        return elapsed >= this.config.sleepWindowMs;
+    }
+    /**
+     * Trim recent calls to rolling window
+     */
+    trimRecentCalls() {
+        const windowSize = this.config.requestVolumeThreshold * 2;
+        if (this.recentCalls.length > windowSize) {
+            this.recentCalls = this.recentCalls.slice(-windowSize);
+        }
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.lastStateChangeTime = new Date();
+        if (newState === CircuitState.HALF_OPEN) {
+            this.halfOpenSuccesses = 0;
+        }
+        if (newState === CircuitState.CLOSED) {
+            this.failures = 0;
+            this.recentCalls = [];
+        }
+        logger.info({
+            breaker: this.config.name,
+            oldState,
+            newState
+        }, 'circuit breaker state change');
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        return {
+            name: this.config.name,
+            state: this.state,
+            totalCalls: this.totalCalls,
+            successfulCalls: this.successes,
+            failedCalls: this.failures,
+            timedOutCalls: this.timedOutCalls,
+            rejectedCalls: this.rejectedCalls,
+            errorRate: this.calculateErrorRate(),
+            lastFailure: this.lastFailureTime,
+            lastSuccess: this.lastSuccessTime,
+            lastStateChange: this.lastStateChangeTime
+        };
+    }
+    /**
+     * Force close the circuit (for recovery scenarios)
+     */
+    forceClose() {
+        this.transitionTo(CircuitState.CLOSED);
+        logger.warn({ breaker: this.config.name }, 'circuit breaker force closed');
+    }
+    /**
+     * Force open the circuit (for maintenance scenarios)
+     */
+    forceOpen() {
+        this.transitionTo(CircuitState.OPEN);
+        logger.warn({ breaker: this.config.name }, 'circuit breaker force opened');
+    }
+    /**
+     * Reset all statistics
+     */
+    reset() {
+        this.state = CircuitState.CLOSED;
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureTime = null;
+        this.lastSuccessTime = null;
+        this.lastStateChangeTime = new Date();
+        this.halfOpenSuccesses = 0;
+        this.totalCalls = 0;
+        this.rejectedCalls = 0;
+        this.timedOutCalls = 0;
+        this.recentCalls = [];
+        logger.info({ breaker: this.config.name }, 'circuit breaker reset');
+    }
+}
+/**
+ * Circuit breaker error - thrown when circuit is open
+ */
+export class CircuitBreakerError extends Error {
+    breakerName;
+    isCircuitBreakerError = true;
+    constructor(message, breakerName) {
+        super(message);
+        this.name = 'CircuitBreakerError';
+        this.breakerName = breakerName;
+    }
+}
+/**
+ * Circuit breaker timeout error
+ */
+export class CircuitBreakerTimeoutError extends Error {
+    breakerName;
+    isTimeout = true;
+    constructor(message, breakerName) {
+        super(message);
+        this.name = 'CircuitBreakerTimeoutError';
+        this.breakerName = breakerName;
+    }
+}
+/**
+ * Circuit breaker registry - manage multiple breakers
+ */
+class CircuitBreakerRegistry {
+    breakers = new Map();
+    /**
+     * Get or create a circuit breaker
+     */
+    getBreaker(name, config) {
+        let breaker = this.breakers.get(name);
+        if (!breaker) {
+            breaker = new CircuitBreaker({ ...config, name });
+            this.breakers.set(name, breaker);
+        }
+        return breaker;
+    }
+    /**
+     * Get all breaker stats
+     */
+    getAllStats() {
+        return Array.from(this.breakers.values()).map(b => b.getStats());
+    }
+    /**
+     * Reset all breakers
+     */
+    resetAll() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+    }
+    /**
+     * Remove a breaker
+     */
+    removeBreaker(name) {
+        return this.breakers.delete(name);
+    }
+    /**
+     * Clear all breakers
+     */
+    clear() {
+        this.breakers.clear();
+    }
+}
+// Singleton registry
+let registryInstance = null;
+/**
+ * Get the global circuit breaker registry
+ */
+export function getCircuitBreakerRegistry() {
+    if (!registryInstance) {
+        registryInstance = new CircuitBreakerRegistry();
+    }
+    return registryInstance;
+}
+/**
+ * Reset the global registry
+ */
+export function resetCircuitBreakerRegistry() {
+    if (registryInstance) {
+        registryInstance.clear();
+    }
+    registryInstance = null;
+}
+/**
+ * Convenience function - get or create a circuit breaker
+ */
+export function getCircuitBreaker(name, config) {
+    return getCircuitBreakerRegistry().getBreaker(name, config);
+}
+/**
+ * Pre-configured circuit breaker for database operations
+ */
+export const DATABASE_BREAKER_CONFIG = {
+    errorThresholdPercentage: 50,
+    requestVolumeThreshold: 10,
+    sleepWindowMs: 10000,
+    timeoutMs: 30000,
+    successThreshold: 3
+};
+/**
+ * Pre-configured circuit breaker for external API calls
+ */
+export const API_BREAKER_CONFIG = {
+    errorThresholdPercentage: 60,
+    requestVolumeThreshold: 5,
+    sleepWindowMs: 30000,
+    timeoutMs: 60000,
+    successThreshold: 2
+};
+//# sourceMappingURL=circuitBreaker.js.map

package/dist/utils/circuitBreaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.js","sourceRoot":"","sources":["../../src/utils/circuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;GAEG;AACH,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,6BAAa,CAAA;IACb,uCAAuB,CAAA,CAAC,mCAAmC;AAC7D,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB;AAoBD,MAAM,cAAc,GAAyB;IAC3C,IAAI,EAAE,SAAS;IACf,wBAAwB,EAAE,EAAE;IAC5B,sBAAsB,EAAE,EAAE;IAC1B,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,IAAI,OAAO,EAAE,EAAE,CAAC,EAAE,qBAAqB;IACtG,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,IAAI,OAAO,EAAE,EAAE,CAAC,EAAM,qBAAqB;IACxG,gBAAgB,EAAE,CAAC;CACpB,CAAC;AAmBF;;;;;;;;;GASG;AACH,MAAM,OAAO,cAAc;IACjB,MAAM,CAAuB;IAC7B,KAAK,GAAiB,YAAY,CAAC,MAAM,CAAC;IAC1C,QAAQ,GAAG,CAAC,CAAC;IACb,SAAS,GAAG,CAAC,CAAC;IACd,eAAe,GAAgB,IAAI,CAAC;IACpC,eAAe,GAAgB,IAAI,CAAC;IACpC,mBAAmB,GAAS,IAAI,IAAI,EAAE,CAAC;IACvC,iBAAiB,GAAG,CAAC,CAAC;IACtB,UAAU,GAAG,CAAC,CAAC;IACf,aAAa,GAAG,CAAC,CAAC;IAClB,aAAa,GAAG,CAAC,CAAC;IAClB,WAAW,GAAmD,EAAE,CAAC;IAEzE,YAAY,SAAwC,EAAE;QACpD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAI,EAAoB;QACnC,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,2BAA2B;QAC3B,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,CAAC,IAAI,EAAE,CAAC;YACrC,IAAI,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;gBAC9B,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;YAC5C,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,aAAa,EAAE,CAAC;gBACrB,MAAM,CAAC,KAAK,CAAC;oBACX,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;oBACzB,KAAK,EAAE,IAAI,CAAC,KAAK;iBAClB,EAAE,+BAA+B,CAAC,CAAC;gBACpC,MAAM,IAAI,mBAAmB,CAC3B,mBAAmB,IAAI,CAAC,MAAM,CAAC,IAAI,UAAU,EAC7C,IAAI,CAAC,MAAM,CAAC,IAAI,CACjB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,uBAAuB;YACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;YACjD,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAC1B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,kBAAkB,CAAI,EAAoB;QACtD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBAChC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACrB,MAAM,CAAC,IAAI,0BAA0B,CACnC,6BAA6B,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,EACtD,IAAI,CAAC,MAAM,CAAC,IAAI,CACjB,CAAC,CAAC;YACL,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAE1B,EAAE,EAAE;iBACD,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;gBACf,YAAY,CAAC,SAAS,CAAC,CAAC;gBACxB,OAAO,CAAC,MAAM,CAAC,CAAC;YAClB,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACf,YAAY,CAAC,SAAS,CAAC,CAAC;gBACxB,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,aAAa;QACnB,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,eAAe,GAAG,IAAI,IAAI,EAAE,CAAC;QAElC,wCAAwC;QACxC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,eAAe,EAAE,CAAC;QAEvB,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;gBAC3D,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QAED,MAAM,CAAC,KAAK,CAAC;YACX,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;YACzB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,EAAE,yBAAyB,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,KAAc;QAClC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,IAAI,IAAI,EAAE,CAAC;QAElC,wCAAwC;QACxC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,eAAe,EAAE,CAAC;QAEvB,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,CAAC,SAAS,EAAE,CAAC;YAC1C,yDAAyD;YACzD,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QAED,MAAM,CAAC,KAAK,CAAC;YACX,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;YACzB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SAC1D,EAAE,yBAAyB,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACK,UAAU;QAChB,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAAE,CAAC;YACjE,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5C,OAAO,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,wBAAwB,CAAC;IAC3D,CAAC;IAED;;OAEG;IACK,kBAAkB;QACxB,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QAE5C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QACjE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC;IACpD,CAAC;IAED;;OAEG;IACK,kBAAkB;QACxB,IAAI,CAAC,IAAI,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC;QAEvC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;QAC5D,OAAO,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;IAC9C,CAAC;IAED;;OAEG;IACK,eAAe;QACrB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,sBAAsB,GAAG,CAAC,CAAC;QAC1D,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;YACzC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,QAAsB;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,mBAAmB,GAAG,IAAI,IAAI,EAAE,CAAC;QAEtC,IAAI,QAAQ,KAAK,YAAY,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;QAC7B,CAAC;QAED,IAAI,QAAQ,KAAK,YAAY,CAAC,MAAM,EAAE,CAAC;YACrC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;YAClB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACxB,CAAC;QAED,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;YACzB,QAAQ;YACR,QAAQ;SACT,EAAE,8BAA8B,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;YACtB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,eAAe,EAAE,IAAI,CAAC,SAAS;YAC/B,WAAW,EAAE,IAAI,CAAC,QAAQ;YAC1B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE;YACpC,WAAW,EAAE,IAAI,CAAC,eAAe;YACjC,WAAW,EAAE,IAAI,CAAC,eAAe;YACjC,eAAe,EAAE,IAAI,CAAC,mBAAmB;SAC1C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,8BAA8B,CAAC,CAAC;IAC7E,CAAC;IAED;;OAEG;IACH,SAAS;QACP,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,8BAA8B,CAAC,CAAC;IAC7E,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,mBAAmB,GAAG,IAAI,IAAI,EAAE,CAAC;QACtC,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,uBAAuB,CAAC,CAAC;IACtE,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,WAAW,CAAS;IACpB,qBAAqB,GAAG,IAAI,CAAC;IAEtC,YAAY,OAAe,EAAE,WAAmB;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,WAAW,CAAS;IACpB,SAAS,GAAG,IAAI,CAAC;IAE1B,YAAY,OAAe,EAAE,WAAmB;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,sBAAsB;IAClB,QAAQ,GAAgC,IAAI,GAAG,EAAE,CAAC;IAE1D;;OAEG;IACH,UAAU,CAAC,IAAY,EAAE,MAAsC;QAC7D,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,IAAI,cAAc,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnE,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC7C,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,IAAY;QACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AAED,qBAAqB;AACrB,IAAI,gBAAgB,GAAkC,IAAI,CAAC;AAE3D;;GAEG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAClD,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B;IACzC,IAAI,gBAAgB,EAAE,CAAC;QACrB,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IACD,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAsC;IACpF,OAAO,yBAAyB,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAkC;IACpE,wBAAwB,EAAE,EAAE;IAC5B,sBAAsB,EAAE,EAAE;IAC1B,aAAa,EAAE,KAAK;IACpB,SAAS,EAAE,KAAK;IAChB,gBAAgB,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAkC;IAC/D,wBAAwB,EAAE,EAAE;IAC5B,sBAAsB,EAAE,CAAC;IACzB,aAAa,EAAE,KAAK;IACpB,SAAS,EAAE,KAAK;IAChB,gBAAgB,EAAE,CAAC;CACpB,CAAC"}

package/dist/utils/cleanupHandler.d.ts

@@ -0,0 +1,108 @@
+/**
+ * cleanupHandler.ts - Centralized Cleanup Handler for Event Listeners
+ *
+ * Provides utilities to register and manage cleanup handlers for
+ * event listeners, preventing memory leaks and ensuring graceful shutdown.
+ *
+ * Features:
+ * - Centralized cleanup registration
+ * - Automatic cleanup on process exit
+ * - Priority-based cleanup ordering
+ * - Error handling for failed cleanups
+ *
+ * @author hardwicksoftwareservices
+ */
+import { EventEmitter } from 'events';
+/**
+ * Cleanup handler function type
+ */
+export type CleanupFn = () => void | Promise<void>;
+/**
+ * Cleanup handler manager
+ * Centralized registry for cleanup handlers
+ */
+declare class CleanupHandlerManager {
+    private handlers;
+    private isShuttingDown;
+    private cleanupPromise;
+    private handlerIdCounter;
+    constructor();
+    /**
+     * Set up process exit handlers
+     */
+    private setupProcessHandlers;
+    /**
+     * Generate unique handler ID
+     */
+    private generateId;
+    /**
+     * Register a cleanup handler
+     *
+     * @param name Human-readable name for logging
+     * @param cleanup The cleanup function
+     * @param priority Lower = run first (default: 100)
+     * @returns Handler ID for removal
+     */
+    register(name: string, cleanup: CleanupFn, priority?: number): string;
+    /**
+     * Unregister a cleanup handler
+     *
+     * @param id Handler ID returned from register()
+     */
+    unregister(id: string): boolean;
+    /**
+     * Run all cleanup handlers
+     */
+    runAllCleanups(): Promise<void>;
+    /**
+     * Execute cleanup handlers in priority order
+     */
+    private executeCleanups;
+    /**
+     * Get count of registered handlers
+     */
+    getHandlerCount(): number;
+    /**
+     * Get registered handler names (for debugging)
+     */
+    getHandlerNames(): string[];
+    /**
+     * Check if shutdown is in progress
+     */
+    isInShutdown(): boolean;
+}
+/**
+ * Register a cleanup handler
+ */
+export declare function registerCleanupHandler(name: string, cleanup: CleanupFn, priority?: number): string;
+/**
+ * Unregister a cleanup handler
+ */
+export declare function unregisterCleanupHandler(id: string): boolean;
+/**
+ * Run all cleanup handlers
+ */
+export declare function runAllCleanups(): Promise<void>;
+/**
+ * Get the cleanup manager instance
+ */
+export declare function getCleanupManager(): CleanupHandlerManager;
+/**
+ * Helper to register cleanup for an event emitter
+ *
+ * Automatically removes event listeners when cleanup runs
+ */
+export declare function registerEventCleanup(emitter: EventEmitter, eventName: string, listener: (...args: unknown[]) => void, name?: string): string;
+/**
+ * Helper to safely add an error handler with cleanup
+ */
+export declare function addErrorHandler(emitter: EventEmitter, handler: (error: Error) => void, name?: string): string;
+/**
+ * Create a wrapped event listener that automatically cleans up
+ */
+export declare function createManagedListener<T extends (...args: unknown[]) => void>(emitter: EventEmitter, eventName: string, listener: T, name?: string): {
+    listener: T;
+    cleanup: () => void;
+};
+export {};
+//# sourceMappingURL=cleanupHandler.d.ts.map