@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/circuit-breaker/index.d.ts

@@ -1,29 +1,97 @@
 /**
  * LAFS Circuit Breaker Module
  *
- * Provides circuit breaker pattern for resilient service calls
+ * Provides circuit breaker pattern for resilient service calls.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Represents the three possible states of a circuit breaker.
+ *
+ * @remarks
+ * - `CLOSED` means the circuit is operating normally and requests pass through.
+ * - `OPEN` means the circuit has tripped due to failures and requests are rejected.
+ * - `HALF_OPEN` means the circuit is testing whether the downstream service has recovered.
  */
 export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/** Configuration options for a {@link CircuitBreaker} instance. */
 export interface CircuitBreakerConfig {
+    /** Unique identifier for this circuit breaker, used in log messages and metrics. */
     name: string;
+    /**
+     * Number of failures required to trip the circuit from CLOSED to OPEN.
+     * @defaultValue 5
+     */
     failureThreshold?: number;
+    /**
+     * Milliseconds to wait before transitioning from OPEN to HALF_OPEN.
+     * @defaultValue 30000
+     */
     resetTimeout?: number;
+    /**
+     * Maximum number of trial calls allowed while in the HALF_OPEN state.
+     * @defaultValue 3
+     */
     halfOpenMaxCalls?: number;
+    /**
+     * Consecutive successes required in HALF_OPEN to close the circuit.
+     * @defaultValue 2
+     */
     successThreshold?: number;
 }
+/** Snapshot of runtime metrics for a {@link CircuitBreaker}. */
 export interface CircuitBreakerMetrics {
+    /** Current state of the circuit breaker. */
     state: CircuitState;
+    /** Total number of recorded failures since the last reset. */
     failures: number;
+    /** Total number of recorded successes since the last reset. */
     successes: number;
+    /**
+     * Timestamp of the most recent failure, if any.
+     * @defaultValue undefined
+     */
     lastFailureTime?: Date;
+    /** Number of consecutive successes since the last failure. */
     consecutiveSuccesses: number;
+    /** Total number of calls made through this circuit breaker. */
     totalCalls: number;
 }
+/**
+ * Error thrown when a circuit breaker rejects a call.
+ *
+ * @remarks
+ * This error is raised when the circuit is in the OPEN state or when the
+ * HALF_OPEN call limit has been reached. Callers should catch this to
+ * implement fallback logic or return a 503 response.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await breaker.execute(() => fetch('/api'));
+ * } catch (err) {
+ *   if (err instanceof CircuitBreakerError) {
+ *     console.log('Circuit open, using fallback');
+ *   }
+ * }
+ * ```
+ */
 export declare class CircuitBreakerError extends Error {
+    /**
+     * Creates a new CircuitBreakerError.
+     *
+     * @param message - Descriptive error message indicating why the call was rejected
+     */
     constructor(message: string);
 }
 /**
- * Circuit breaker for protecting against cascading failures
+ * Circuit breaker for protecting against cascading failures.
+ *
+ * @remarks
+ * Implements the circuit breaker pattern with three states: CLOSED (normal),
+ * OPEN (rejecting calls), and HALF_OPEN (testing recovery). The breaker
+ * automatically transitions between states based on failure and success
+ * thresholds, and schedules reset timers when the circuit opens.
  *
  * @example
  * ```typescript
@@ -48,44 +116,134 @@ export declare class CircuitBreakerError extends Error {
  */
 export declare class CircuitBreaker {
     private config;
+    /** Current circuit state. */
     private state;
+    /** Total failure count since last reset. */
     private failures;
+    /** Total success count since last reset. */
     private successes;
+    /** Timestamp of the most recent failure. */
     private lastFailureTime?;
+    /** Consecutive successes since the last failure. */
     private consecutiveSuccesses;
+    /** Lifetime call count. */
     private totalCalls;
+    /** Number of calls made while in the HALF_OPEN state. */
     private halfOpenCalls;
+    /** Timer handle for the scheduled OPEN-to-HALF_OPEN transition. */
     private resetTimer?;
+    /**
+     * Creates a new CircuitBreaker with the given configuration.
+     *
+     * @param config - Circuit breaker configuration with name, thresholds, and timeouts
+     */
     constructor(config: CircuitBreakerConfig);
     /**
-     * Execute a function with circuit breaker protection
+     * Execute a function with circuit breaker protection.
+     *
+     * @remarks
+     * When the circuit is CLOSED, calls pass through normally. When OPEN, calls
+     * are rejected with a {@link CircuitBreakerError} unless the reset timeout has
+     * elapsed (triggering HALF_OPEN). In HALF_OPEN, a limited number of trial
+     * calls are permitted; successes may close the circuit while failures re-open it.
+     *
+     * @typeParam T - Return type of the wrapped function
+     * @param fn - Async function to execute under circuit breaker protection
+     * @returns The result of invoking `fn`
+     *
+     * @example
+     * ```typescript
+     * const result = await breaker.execute(async () => {
+     *   return await fetch('https://api.example.com/data');
+     * });
+     * ```
      */
     execute<T>(fn: () => Promise<T>): Promise<T>;
     /**
-     * Get current circuit breaker state
+     * Get the current circuit breaker state.
+     *
+     * @remarks
+     * Returns one of `'CLOSED'`, `'OPEN'`, or `'HALF_OPEN'`. Useful for
+     * dashboards or conditional logic that needs to know whether calls will
+     * be accepted.
+     *
+     * @returns The current {@link CircuitState}
+     *
+     * @example
+     * ```typescript
+     * if (breaker.getState() === 'OPEN') {
+     *   console.log('Circuit is open, requests will be rejected');
+     * }
+     * ```
      */
     getState(): CircuitState;
     /**
-     * Get circuit breaker metrics
+     * Get a snapshot of the circuit breaker's runtime metrics.
+     *
+     * @remarks
+     * Returns a copy of the internal counters including failure/success counts,
+     * the current state, and the timestamp of the last failure. Useful for
+     * monitoring and observability.
+     *
+     * @returns A {@link CircuitBreakerMetrics} snapshot
+     *
+     * @example
+     * ```typescript
+     * const metrics = breaker.getMetrics();
+     * console.log(`State: ${metrics.state}, Failures: ${metrics.failures}`);
+     * ```
      */
     getMetrics(): CircuitBreakerMetrics;
     /**
-     * Manually open the circuit breaker
+     * Manually open the circuit breaker, rejecting all subsequent calls.
+     *
+     * @remarks
+     * Forces the circuit into the OPEN state regardless of the current failure
+     * count. Useful for administrative controls or when an external signal
+     * indicates the downstream service is unavailable.
+     *
+     * @example
+     * ```typescript
+     * breaker.forceOpen();
+     * console.log(breaker.getState()); // 'OPEN'
+     * ```
      */
     forceOpen(): void;
     /**
-     * Manually close the circuit breaker
+     * Manually close the circuit breaker and reset all counters.
+     *
+     * @remarks
+     * Forces the circuit into the CLOSED state and clears failure/success
+     * counters and any pending reset timer. Useful for administrative recovery
+     * after a known issue has been resolved.
+     *
+     * @example
+     * ```typescript
+     * breaker.forceClose();
+     * console.log(breaker.getState()); // 'CLOSED'
+     * ```
      */
     forceClose(): void;
+    /** Records a successful call and may transition from HALF_OPEN to CLOSED. */
     private onSuccess;
+    /** Records a failed call and may trip the circuit to OPEN. */
     private onFailure;
+    /** Transitions the circuit to the given state, resetting HALF_OPEN call count when entering HALF_OPEN. */
     private transitionTo;
+    /** Returns `true` if enough time has elapsed since the last failure to attempt a reset. */
     private shouldAttemptReset;
+    /** Schedules a timer to transition from OPEN to HALF_OPEN after the configured reset timeout. */
     private scheduleReset;
+    /** Resets all failure/success counters and clears the pending reset timer. */
     private reset;
 }
 /**
- * Circuit breaker registry for managing multiple breakers
+ * Registry for managing multiple named circuit breakers.
+ *
+ * @remarks
+ * Provides centralized creation, lookup, and metrics aggregation for
+ * circuit breakers. Each breaker is stored by name and can be retrieved
+ * or lazily created via {@link CircuitBreakerRegistry.getOrCreate}.
  *
  * @example
  * ```typescript
@@ -100,15 +258,102 @@ export declare class CircuitBreaker {
  * ```
  */
 export declare class CircuitBreakerRegistry {
+    /** Internal map of circuit breaker name to instance. */
     private breakers;
+    /**
+     * Register a new circuit breaker with the given name and configuration.
+     *
+     * @remarks
+     * Creates a new {@link CircuitBreaker}, stores it in the registry, and
+     * returns it. If a breaker with the same name already exists, it is replaced.
+     *
+     * @param name - Unique name for the circuit breaker
+     * @param config - Configuration options (name is set automatically)
+     * @returns The newly created {@link CircuitBreaker}
+     *
+     * @example
+     * ```typescript
+     * const breaker = registry.add('user-service', { failureThreshold: 3 });
+     * ```
+     */
     add(name: string, config: Omit<CircuitBreakerConfig, 'name'>): CircuitBreaker;
+    /**
+     * Retrieve a circuit breaker by name.
+     *
+     * @remarks
+     * Returns `undefined` if no breaker with the given name has been registered.
+     *
+     * @param name - Name of the circuit breaker to look up
+     * @returns The matching {@link CircuitBreaker}, or `undefined` if not found
+     *
+     * @example
+     * ```typescript
+     * const breaker = registry.get('payment-api');
+     * if (breaker) {
+     *   await breaker.execute(() => callPaymentApi());
+     * }
+     * ```
+     */
     get(name: string): CircuitBreaker | undefined;
+    /**
+     * Retrieve an existing circuit breaker or create one if it does not exist.
+     *
+     * @remarks
+     * This is useful when callers want a breaker but do not know whether it
+     * has already been registered, avoiding duplicate creation.
+     *
+     * @param name - Name of the circuit breaker
+     * @param config - Configuration to use if a new breaker must be created
+     * @returns The existing or newly created {@link CircuitBreaker}
+     *
+     * @example
+     * ```typescript
+     * const breaker = registry.getOrCreate('cache-api', { failureThreshold: 10 });
+     * ```
+     */
     getOrCreate(name: string, config: Omit<CircuitBreakerConfig, 'name'>): CircuitBreaker;
+    /**
+     * Collect metrics from all registered circuit breakers.
+     *
+     * @remarks
+     * Returns a record keyed by breaker name with each value being the
+     * corresponding {@link CircuitBreakerMetrics} snapshot.
+     *
+     * @returns A record mapping breaker names to their current metrics
+     *
+     * @example
+     * ```typescript
+     * const allMetrics = registry.getAllMetrics();
+     * for (const [name, metrics] of Object.entries(allMetrics)) {
+     *   console.log(`${name}: ${metrics.state}`);
+     * }
+     * ```
+     */
     getAllMetrics(): Record<string, CircuitBreakerMetrics>;
+    /**
+     * Force-close all registered circuit breakers, resetting their counters.
+     *
+     * @remarks
+     * Iterates over every registered breaker and calls {@link CircuitBreaker.forceClose}.
+     * Useful for administrative recovery or test teardown.
+     *
+     * @example
+     * ```typescript
+     * registry.resetAll();
+     * ```
+     */
     resetAll(): void;
 }
 /**
- * Create a circuit breaker middleware for Express
+ * Create an Express middleware that wraps downstream handlers with a circuit breaker.
+ *
+ * @remarks
+ * Instantiates a {@link CircuitBreaker} from the provided config and wraps the
+ * `next()` call. When the circuit is open, the middleware responds with a 503
+ * status and a JSON error body instead of forwarding the request.
+ *
+ * @param config - Circuit breaker configuration for the middleware instance
+ * @returns An Express-compatible middleware function
  *
  * @example
  * ```typescript
@@ -118,4 +363,9 @@ export declare class CircuitBreakerRegistry {
  * }));
  * ```
  */
-export declare function circuitBreakerMiddleware(config: CircuitBreakerConfig): (req: any, res: any, next: any) => Promise<void>;
+export declare function circuitBreakerMiddleware(config: CircuitBreakerConfig): (_req: unknown, res: {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+    };
+}, next: () => void) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/circuit-breaker/index.d.ts.map

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