@takentrade/takentrade-libs 2.0.7 → 3.0.0

package/dist/resilience/circuit-breaker-stats.service.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreakerStatsService = void 0;
+const circuit_breaker_interface_1 = require("./circuit-breaker.interface");
+/**
+ * Circuit Breaker Statistics Service
+ *
+ * Handles statistics and state management for circuit breakers
+ */
+class CircuitBreakerStatsService {
+    /**
+     * Get statistics for a circuit breaker
+     *
+     * @param instance - Circuit breaker instance
+     * @returns Circuit breaker statistics
+     */
+    getStats(instance) {
+        const stats = instance.breaker.stats;
+        return {
+            fires: stats.fires,
+            failures: stats.failures,
+            successes: stats.successes,
+            rejects: stats.rejects,
+            timeouts: stats.timeouts,
+            cacheHits: stats.cacheHits,
+            cacheMisses: stats.cacheMisses,
+            semaphoreRejections: stats.semaphoreRejections,
+            percentiles: stats.percentiles,
+            latencyMean: stats.latencyMean,
+            latencyTimes: stats.latencyTimes,
+        };
+    }
+    /**
+     * Get all circuit breaker statistics
+     *
+     * @param breakers - Map of circuit breaker instances
+     * @returns Map of circuit breaker names to their statistics
+     */
+    getAllStats(breakers) {
+        const allStats = new Map();
+        for (const [name, instance] of breakers.entries()) {
+            allStats.set(name, this.getStats(instance));
+        }
+        return allStats;
+    }
+    /**
+     * Get the current state of a circuit breaker
+     *
+     * @param breaker - Circuit breaker instance
+     * @returns Current circuit state
+     */
+    getState(breaker) {
+        if (breaker.opened)
+            return circuit_breaker_interface_1.CircuitState.OPEN;
+        if (breaker.halfOpen)
+            return circuit_breaker_interface_1.CircuitState.HALF_OPEN;
+        return circuit_breaker_interface_1.CircuitState.CLOSED;
+    }
+    /**
+     * Check if a circuit breaker is open
+     *
+     * @param breaker - Circuit breaker instance
+     * @returns True if circuit is open
+     */
+    isOpen(breaker) {
+        return breaker.opened;
+    }
+}
+exports.CircuitBreakerStatsService = CircuitBreakerStatsService;

package/dist/resilience/circuit-breaker.interface.d.ts

@@ -0,0 +1,134 @@
+import CircuitBreaker from 'opossum';
+/**
+ * Circuit breaker state enum
+ */
+export declare enum CircuitState {
+    CLOSED = "closed",
+    OPEN = "open",
+    HALF_OPEN = "halfOpen"
+}
+/**
+ * Circuit breaker options based on Opossum configuration
+ * @see https://nodeshift.dev/opossum/
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * The time in milliseconds that action should be allowed to execute before timing out.
+     * @default 10000 (10 seconds)
+     */
+    timeout?: number;
+    /**
+     * The number of times the circuit can fail before opening.
+     * @default 50
+     */
+    errorThresholdPercentage?: number;
+    /**
+     * The time in milliseconds to wait before setting the breaker to halfOpen state.
+     * @default 30000 (30 seconds)
+     */
+    resetTimeout?: number;
+    /**
+     * The rolling statistical window in milliseconds.
+     * @default 10000 (10 seconds)
+     */
+    rollingCountTimeout?: number;
+    /**
+     * The number of buckets the rolling statistical window is divided into.
+     * @default 10
+     */
+    rollingCountBuckets?: number;
+    /**
+     * The name of the circuit breaker (for logging and metrics).
+     */
+    name?: string;
+    /**
+     * The capacity of the internal event bus.
+     * @default 100
+     */
+    capacity?: number;
+    /**
+     * Whether to enable snapshots for metrics.
+     * @default false
+     */
+    enableSnapshots?: boolean;
+    /**
+     * Whether to allow warm up period (ignore errors initially).
+     * @default false
+     */
+    allowWarmUp?: boolean;
+    /**
+     * The number of requests to allow during warm up.
+     * @default 0
+     */
+    volumeThreshold?: number;
+    /**
+     * Custom error filter function to determine if an error should trip the circuit.
+     */
+    errorFilter?: (error: any) => boolean;
+    /**
+     * Whether to cache the result of successful calls.
+     * @default false
+     */
+    cache?: boolean;
+    /**
+     * Cache TTL in milliseconds.
+     * @default 0
+     */
+    cacheTTL?: number;
+    /**
+     * Custom cache key generator function.
+     */
+    cacheGetKey?: (...args: any[]) => string;
+}
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+    fires: number;
+    failures: number;
+    successes: number;
+    rejects: number;
+    timeouts: number;
+    cacheHits: number;
+    cacheMisses: number;
+    semaphoreRejections: number;
+    percentiles: {
+        [percentile: number]: number;
+    };
+    latencyMean: number;
+    latencyTimes: number[];
+}
+/**
+ * Circuit breaker event types
+ */
+export declare enum CircuitBreakerEvent {
+    FIRE = "fire",
+    SUCCESS = "success",
+    FAILURE = "failure",
+    TIMEOUT = "timeout",
+    REJECT = "reject",
+    OPEN = "open",
+    CLOSE = "close",
+    HALF_OPEN = "halfOpen",
+    FALLBACK = "fallback",
+    SEMAPHORE_LOCKED = "semaphoreLocked",
+    HEALTH_CHECK_FAILED = "healthCheckFailed",
+    CACHE_HIT = "cacheHit",
+    CACHE_MISS = "cacheMiss"
+}
+/**
+ * Circuit breaker instance wrapper
+ */
+export interface CircuitBreakerInstance<T = any, R = any> {
+    breaker: CircuitBreaker<T[], R>;
+    name: string;
+    options: CircuitBreakerOptions;
+}
+/**
+ * Fallback function type
+ */
+export type FallbackFunction<T = any> = (...args: any[]) => T | Promise<T>;
+/**
+ * Health check function type
+ */
+export type HealthCheckFunction = () => Promise<boolean>;

package/dist/resilience/circuit-breaker.interface.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreakerEvent = exports.CircuitState = void 0;
+/**
+ * Circuit breaker state enum
+ */
+var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "closed";
+    CircuitState["OPEN"] = "open";
+    CircuitState["HALF_OPEN"] = "halfOpen";
+})(CircuitState || (exports.CircuitState = CircuitState = {}));
+/**
+ * Circuit breaker event types
+ */
+var CircuitBreakerEvent;
+(function (CircuitBreakerEvent) {
+    CircuitBreakerEvent["FIRE"] = "fire";
+    CircuitBreakerEvent["SUCCESS"] = "success";
+    CircuitBreakerEvent["FAILURE"] = "failure";
+    CircuitBreakerEvent["TIMEOUT"] = "timeout";
+    CircuitBreakerEvent["REJECT"] = "reject";
+    CircuitBreakerEvent["OPEN"] = "open";
+    CircuitBreakerEvent["CLOSE"] = "close";
+    CircuitBreakerEvent["HALF_OPEN"] = "halfOpen";
+    CircuitBreakerEvent["FALLBACK"] = "fallback";
+    CircuitBreakerEvent["SEMAPHORE_LOCKED"] = "semaphoreLocked";
+    CircuitBreakerEvent["HEALTH_CHECK_FAILED"] = "healthCheckFailed";
+    CircuitBreakerEvent["CACHE_HIT"] = "cacheHit";
+    CircuitBreakerEvent["CACHE_MISS"] = "cacheMiss";
+})(CircuitBreakerEvent || (exports.CircuitBreakerEvent = CircuitBreakerEvent = {}));

package/dist/{common/circuit-breaker → resilience}/circuit-breaker.module.js

@@ -13,6 +13,7 @@ let CircuitBreakerModule = class CircuitBreakerModule {
 };
 exports.CircuitBreakerModule = CircuitBreakerModule;
 exports.CircuitBreakerModule = CircuitBreakerModule = __decorate([
+    (0, common_1.Global)(),
     (0, common_1.Module)({
         providers: [circuit_breaker_service_1.CircuitBreakerService],
         exports: [circuit_breaker_service_1.CircuitBreakerService],

package/dist/resilience/circuit-breaker.service.d.ts

@@ -0,0 +1,119 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import CircuitBreaker from 'opossum';
+import { CircuitBreakerOptions, CircuitBreakerStats, CircuitState, FallbackFunction } from './circuit-breaker.interface';
+export declare class CircuitBreakerService implements OnModuleDestroy {
+    private readonly logger;
+    private readonly breakers;
+    private readonly factory;
+    private readonly statsService;
+    /**
+     * Create a new circuit breaker instance
+     *
+     * @param name - Unique identifier for the circuit breaker
+     * @param action - The async function to be protected
+     * @param options - Circuit breaker configuration options
+     * @returns Circuit breaker instance
+     */
+    createBreaker<T = any, R = any>(name: string, action: (...args: T[]) => Promise<R>, options?: CircuitBreakerOptions): CircuitBreaker<T[], R>;
+    /**
+     * Execute a protected function through the circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @param args - Arguments to pass to the protected function
+     * @returns Result of the protected function
+     */
+    fire<T = any>(name: string, ...args: any[]): Promise<T>;
+    /**
+     * Set a fallback function for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @param fallback - Fallback function to execute when circuit is open
+     */
+    setFallback<T = any>(name: string, fallback: FallbackFunction<T>): void;
+    /**
+     * Set a health check function for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @param healthCheck - Health check function
+     * @param interval - Health check interval in milliseconds (default: 5000)
+     */
+    setHealthCheck(name: string, healthCheck: () => Promise<void>, interval?: number): void;
+    /**
+     * Note: Caching should be configured during circuit breaker creation via options.
+     * This is a limitation of the current Opossum version.
+     */
+    /**
+     * Clear the cache for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     */
+    clearCache(name: string): void;
+    /**
+     * Get the current state of a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @returns Current circuit state
+     */
+    getState(name: string): CircuitState;
+    /**
+     * Check if a circuit breaker is open
+     *
+     * @param name - Circuit breaker name
+     * @returns True if circuit is open
+     */
+    isOpen(name: string): boolean;
+    /**
+     * Get statistics for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @returns Circuit breaker statistics
+     */
+    getStats(name: string): CircuitBreakerStats;
+    /**
+     * Get all circuit breaker statistics
+     *
+     * @returns Map of circuit breaker names to their statistics
+     */
+    getAllStats(): Map<string, CircuitBreakerStats>;
+    /**
+     * Manually open a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     */
+    open(name: string): void;
+    /**
+     * Manually close a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     */
+    close(name: string): void;
+    /**
+     * Reset a circuit breaker (clear stats and close)
+     *
+     * @param name - Circuit breaker name
+     */
+    reset(name: string): void;
+    /**
+     * Remove a circuit breaker instance
+     *
+     * @param name - Circuit breaker name
+     */
+    remove(name: string): void;
+    /**
+     * Get all circuit breaker names
+     *
+     * @returns Array of circuit breaker names
+     */
+    getBreakerNames(): string[];
+    /**
+     * Check if a circuit breaker exists
+     *
+     * @param name - Circuit breaker name
+     * @returns True if circuit breaker exists
+     */
+    hasBreaker(name: string): boolean;
+    /**
+     * Cleanup on module destroy
+     */
+    onModuleDestroy(): Promise<void>;
+}

package/dist/resilience/circuit-breaker.service.js

@@ -0,0 +1,234 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var CircuitBreakerService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreakerService = void 0;
+const common_1 = require("@nestjs/common");
+const circuit_breaker_factory_1 = require("./circuit-breaker-factory");
+const circuit_breaker_stats_service_1 = require("./circuit-breaker-stats.service");
+let CircuitBreakerService = CircuitBreakerService_1 = class CircuitBreakerService {
+    logger = new common_1.Logger(CircuitBreakerService_1.name);
+    breakers = new Map();
+    factory = new circuit_breaker_factory_1.CircuitBreakerFactory();
+    statsService = new circuit_breaker_stats_service_1.CircuitBreakerStatsService();
+    /**
+     * Create a new circuit breaker instance
+     *
+     * @param name - Unique identifier for the circuit breaker
+     * @param action - The async function to be protected
+     * @param options - Circuit breaker configuration options
+     * @returns Circuit breaker instance
+     */
+    createBreaker(name, action, options = {}) {
+        if (this.breakers.has(name)) {
+            this.logger.warn(`Circuit breaker '${name}' already exists. Returning existing instance.`);
+            return this.breakers.get(name).breaker;
+        }
+        const instance = this.factory.create(name, action, options);
+        this.breakers.set(name, instance);
+        return instance.breaker;
+    }
+    /**
+     * Execute a protected function through the circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @param args - Arguments to pass to the protected function
+     * @returns Result of the protected function
+     */
+    async fire(name, ...args) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found. Create it first using createBreaker()`);
+        }
+        return instance.breaker.fire(...args);
+    }
+    /**
+     * Set a fallback function for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @param fallback - Fallback function to execute when circuit is open
+     */
+    setFallback(name, fallback) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        instance.breaker.fallback(fallback);
+        this.logger.log(`Fallback function set for circuit breaker '${name}'`);
+    }
+    /**
+     * Set a health check function for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @param healthCheck - Health check function
+     * @param interval - Health check interval in milliseconds (default: 5000)
+     */
+    setHealthCheck(name, healthCheck, interval = 5000) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        instance.breaker.healthCheck(healthCheck, interval);
+        this.logger.log(`Health check set for circuit breaker '${name}' with ${interval}ms interval`);
+    }
+    /**
+     * Note: Caching should be configured during circuit breaker creation via options.
+     * This is a limitation of the current Opossum version.
+     */
+    /**
+     * Clear the cache for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     */
+    clearCache(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        instance.breaker.clearCache();
+        this.logger.debug(`Cache cleared for circuit breaker '${name}'`);
+    }
+    /**
+     * Get the current state of a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @returns Current circuit state
+     */
+    getState(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        return this.statsService.getState(instance.breaker);
+    }
+    /**
+     * Check if a circuit breaker is open
+     *
+     * @param name - Circuit breaker name
+     * @returns True if circuit is open
+     */
+    isOpen(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        return this.statsService.isOpen(instance.breaker);
+    }
+    /**
+     * Get statistics for a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     * @returns Circuit breaker statistics
+     */
+    getStats(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        return this.statsService.getStats(instance);
+    }
+    /**
+     * Get all circuit breaker statistics
+     *
+     * @returns Map of circuit breaker names to their statistics
+     */
+    getAllStats() {
+        return this.statsService.getAllStats(this.breakers);
+    }
+    /**
+     * Manually open a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     */
+    open(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        instance.breaker.open();
+        this.logger.warn(`Circuit breaker '${name}' manually opened`);
+    }
+    /**
+     * Manually close a circuit breaker
+     *
+     * @param name - Circuit breaker name
+     */
+    close(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        instance.breaker.close();
+        this.logger.log(`Circuit breaker '${name}' manually closed`);
+    }
+    /**
+     * Reset a circuit breaker (clear stats and close)
+     *
+     * @param name - Circuit breaker name
+     */
+    reset(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            throw new Error(`Circuit breaker '${name}' not found`);
+        }
+        instance.breaker.close();
+        this.logger.log(`Circuit breaker '${name}' reset`);
+    }
+    /**
+     * Remove a circuit breaker instance
+     *
+     * @param name - Circuit breaker name
+     */
+    remove(name) {
+        const instance = this.breakers.get(name);
+        if (!instance) {
+            return;
+        }
+        instance.breaker.shutdown();
+        this.breakers.delete(name);
+        this.logger.log(`Circuit breaker '${name}' removed`);
+    }
+    /**
+     * Get all circuit breaker names
+     *
+     * @returns Array of circuit breaker names
+     */
+    getBreakerNames() {
+        return Array.from(this.breakers.keys());
+    }
+    /**
+     * Check if a circuit breaker exists
+     *
+     * @param name - Circuit breaker name
+     * @returns True if circuit breaker exists
+     */
+    hasBreaker(name) {
+        return this.breakers.has(name);
+    }
+    /**
+     * Cleanup on module destroy
+     */
+    async onModuleDestroy() {
+        this.logger.log('Shutting down all circuit breakers...');
+        for (const [name, instance] of this.breakers.entries()) {
+            try {
+                instance.breaker.shutdown();
+                this.logger.log(`Circuit breaker '${name}' shut down successfully`);
+            }
+            catch (error) {
+                this.logger.error(`Error shutting down circuit breaker '${name}':`, error);
+            }
+        }
+        this.breakers.clear();
+        this.logger.log('All circuit breakers shut down');
+    }
+};
+exports.CircuitBreakerService = CircuitBreakerService;
+exports.CircuitBreakerService = CircuitBreakerService = CircuitBreakerService_1 = __decorate([
+    (0, common_1.Injectable)()
+], CircuitBreakerService);

package/dist/resilience/index.d.ts

@@ -0,0 +1,3 @@
+export * from './circuit-breaker.module';
+export * from './circuit-breaker.service';
+export * from './circuit-breaker.interface';

package/dist/resilience/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./circuit-breaker.module"), exports);
+__exportStar(require("./circuit-breaker.service"), exports);
+__exportStar(require("./circuit-breaker.interface"), exports);