@cleocode/lafs 2026.4.0 → 2026.4.4

package/dist/src/budgetEnforcement.js

@@ -6,15 +6,31 @@
  */
 import { TokenEstimator } from './tokenEstimator.js';
 /**
- * Budget exceeded error code from LAFS error registry
+ * Budget exceeded error code from LAFS error registry.
+ *
+ * @remarks
+ * Used as the `code` field in {@link LAFSError} when a response exceeds
+ * its declared MVI token budget.
  */
 const BUDGET_EXCEEDED_CODE = 'E_MVI_BUDGET_EXCEEDED';
 /**
- * Default category for budget exceeded errors
+ * Default category for budget exceeded errors.
+ *
+ * @remarks
+ * Budget violations are treated as validation errors since they represent
+ * a contract violation between the caller's budget declaration and the response size.
  */
 const BUDGET_ERROR_CATEGORY = 'VALIDATION';
 /**
- * Create a budget exceeded error object
+ * Create a budget exceeded error object.
+ *
+ * @param estimated - Estimated token count of the response
+ * @param budget - Maximum allowed token count
+ * @returns A {@link LAFSError} with code `E_MVI_BUDGET_EXCEEDED` and detailed metadata
+ *
+ * @remarks
+ * The error details include the exact token counts, the absolute overage,
+ * and the percentage by which the budget was exceeded.
  */
 function createBudgetExceededError(estimated, budget) {
     return {
@@ -32,8 +48,17 @@ function createBudgetExceededError(estimated, budget) {
     };
 }
 /**
- * Truncate a result to fit within budget.
- * Returns the truncated result and whether truncation occurred.
+ * Truncate a result to fit within a token budget.
+ *
+ * @param result - The result payload (object, array, or `null`)
+ * @param targetTokens - Maximum allowed token count
+ * @param estimator - Token estimator instance for measuring sizes
+ * @returns Object containing the truncated result and a flag indicating if truncation occurred
+ *
+ * @remarks
+ * Delegates to array or object-specific truncation strategies. Arrays are
+ * truncated by removing trailing items via binary search; objects are truncated
+ * by removing trailing top-level keys.
  */
 function truncateResult(result, targetTokens, estimator) {
     if (result === null) {
@@ -52,7 +77,18 @@ function truncateResult(result, targetTokens, estimator) {
     return truncateObject(result, targetChars, targetTokens, estimator);
 }
 /**
- * Truncate an array to fit within budget.
+ * Truncate an array to fit within a token budget.
+ *
+ * @param arr - Array of result objects
+ * @param targetChars - Target character count (used for sizing heuristic)
+ * @param targetTokens - Target token budget
+ * @param estimator - Token estimator instance
+ * @returns Object containing the truncated array and a flag indicating if truncation occurred
+ *
+ * @remarks
+ * Uses binary search to find the maximum number of items that fit within
+ * the budget. Appends `_truncated` and `remainingItems` metadata to the
+ * last item when truncation occurs.
  */
 function truncateArray(arr, targetChars, targetTokens, estimator) {
     if (arr.length === 0) {
@@ -101,7 +137,18 @@ function truncateArray(arr, targetChars, targetTokens, estimator) {
     return { result: truncated, wasTruncated: true };
 }
 /**
- * Truncate an object to fit within budget.
+ * Truncate an object to fit within a token budget.
+ *
+ * @param obj - Object to truncate
+ * @param targetChars - Target character count (used for sizing heuristic)
+ * @param targetTokens - Target token budget
+ * @param estimator - Token estimator instance
+ * @returns Object containing the truncated object and a flag indicating if truncation occurred
+ *
+ * @remarks
+ * Uses binary search over the object's keys to find the maximum number of
+ * top-level properties that fit within the budget. Truncated results include
+ * `_truncated` and `_truncatedFields` metadata.
  */
 function truncateObject(obj, targetChars, targetTokens, estimator) {
     const keys = Object.keys(obj);
@@ -154,9 +201,23 @@ function truncateObject(obj, targetChars, targetTokens, estimator) {
  * Apply budget enforcement to an envelope.
  *
  * @param envelope - The LAFS envelope to check
- * @param budget - Maximum allowed tokens
- * @param options - Budget enforcement options
- * @returns Enforce result with potentially modified envelope
+ * @param budget - Maximum allowed token count
+ * @param options - Budget enforcement options (truncation, callbacks)
+ * @returns Enforcement result with the (possibly modified) envelope, budget status, and token estimates
+ *
+ * @remarks
+ * When the envelope is within budget, the token estimate is attached to metadata.
+ * When exceeded, behavior depends on `options.truncateOnExceed`: if enabled,
+ * truncation is attempted first; otherwise, the result is replaced with a
+ * budget-exceeded error. The `onBudgetExceeded` callback fires before truncation.
+ *
+ * @example
+ * ```typescript
+ * const result = applyBudgetEnforcement(envelope, 1000, { truncateOnExceed: true });
+ * if (!result.withinBudget) {
+ *   console.warn("Budget exceeded:", result.estimatedTokens);
+ * }
+ * ```
  */
 export function applyBudgetEnforcement(envelope, budget, options = {}) {
     const { truncateOnExceed = false, onBudgetExceeded } = options;
@@ -235,9 +296,14 @@ export function applyBudgetEnforcement(envelope, budget, options = {}) {
 /**
  * Create a budget enforcement middleware function.
  *
- * @param budget - Maximum allowed tokens for response
- * @param options - Budget enforcement options
- * @returns Middleware function that enforces budget
+ * @param budget - Maximum allowed token count for the response
+ * @param options - Budget enforcement options (truncation, callbacks)
+ * @returns Async middleware function that enforces the token budget
+ *
+ * @remarks
+ * Wraps the next handler in the chain, applying {@link applyBudgetEnforcement}
+ * to its output. The returned envelope may be truncated or replaced with an
+ * error depending on the enforcement result.
  *
  * @example
  * ```typescript
@@ -258,8 +324,20 @@ export function withBudget(budget, options = {}) {
  * Check if an envelope has exceeded its budget without modifying it.
  *
  * @param envelope - The LAFS envelope to check
- * @param budget - Maximum allowed tokens
- * @returns Budget check result
+ * @param budget - Maximum allowed token count
+ * @returns Object with `exceeded` flag, `estimated` token count, and `remaining` budget
+ *
+ * @remarks
+ * A read-only budget check that does not alter the envelope. Useful for
+ * pre-flight checks or logging before deciding how to handle overages.
+ *
+ * @example
+ * ```typescript
+ * const { exceeded, estimated, remaining } = checkBudget(envelope, 500);
+ * if (exceeded) {
+ *   console.warn(`Over budget by ${estimated - 500} tokens`);
+ * }
+ * ```
  */
 export function checkBudget(envelope, budget) {
     const estimator = new TokenEstimator();
@@ -273,9 +351,19 @@ export function checkBudget(envelope, budget) {
 /**
  * Synchronous version of withBudget for non-async contexts.
  *
- * @param budget - Maximum allowed tokens for response
- * @param options - Budget enforcement options
- * @returns Middleware function that enforces budget synchronously
+ * @param budget - Maximum allowed token count for the response
+ * @param options - Budget enforcement options (truncation, callbacks)
+ * @returns Synchronous middleware function that enforces the token budget
+ *
+ * @remarks
+ * Identical to {@link withBudget} but operates synchronously. Use this when the
+ * next handler in the chain is guaranteed to return synchronously.
+ *
+ * @example
+ * ```typescript
+ * const middleware = withBudgetSync(500);
+ * const result = middleware(envelope, () => nextEnvelope);
+ * ```
  */
 export function withBudgetSync(budget, options = {}) {
     return (envelope, next) => {
@@ -288,10 +376,19 @@ export function withBudgetSync(budget, options = {}) {
  * Higher-order function that wraps a handler with budget enforcement.
  *
  * @param handler - The handler function to wrap
+ * @typeParam TArgs - Tuple type representing the handler's parameter list
+ * @typeParam TResult - Return type of the handler, must extend LAFSEnvelope
+ * @param handler - The handler function to wrap with budget enforcement
  * @param budget - Maximum allowed tokens
  * @param options - Budget enforcement options
  * @returns Wrapped handler with budget enforcement
  *
+ * @remarks
+ * The returned function has the same parameter signature as the original handler
+ * but always returns a `Promise<LAFSEnvelope>`. When the budget is exceeded and
+ * `truncateOnExceed` is enabled, the envelope is truncated to fit; otherwise an
+ * `E_MVI_BUDGET_EXCEEDED` error envelope is returned.
+ *
  * @example
  * ```typescript
  * const myHandler = async (request: Request) => ({ success: true, result: { data } });
@@ -308,7 +405,23 @@ export function wrapWithBudget(handler, budget, options = {}) {
 }
 /**
  * Compose multiple middleware functions into a single middleware.
- * Middleware is executed in order (left to right).
+ *
+ * @param middlewares - Middleware functions to compose (executed left to right)
+ * @returns A single middleware function that chains all provided middlewares
+ *
+ * @remarks
+ * Middleware is executed in array order (left to right). Each middleware receives
+ * the envelope and a `next` function that invokes the subsequent middleware.
+ * The final middleware's `next` call invokes the original terminal handler.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = composeMiddleware(
+ *   withBudget(1000),
+ *   loggingMiddleware,
+ * );
+ * const result = await pipeline(envelope, () => finalEnvelope);
+ * ```
  */
 export function composeMiddleware(...middlewares) {
     return async (envelope, next) => {

package/dist/src/budgetEnforcement.js.map

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/circuit-breaker/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,IAAI,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,cAAc;IAUb,OAAO,CAAC,MAAM;IAT1B,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,eAAe,CAAC,CAAO;IAC/B,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAC,CAAiB;gBAEhB,MAAM,EAAE,oBAAoB;IAUhD;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BlD;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;OAEG;IACH,UAAU,IAAI,qBAAqB;IAWnC;;OAEG;IACH,SAAS,IAAI,IAAI;IAIjB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,KAAK;CAUd;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAqC;IAErD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,GAAG,cAAc;IAM7E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,GAAG,cAAc;IAQrF,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAQtD,QAAQ,IAAI,IAAI;CAKjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,oBAAoB,IAIjE,MAAM,OAAO,EACb,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,EACpE,MAAM,MAAM,IAAI,mBAiBnB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/circuit-breaker/index.ts"],"names":[],"mappings":"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"}