@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/circuit-breaker/index.js

@@ -1,16 +1,48 @@
 /**
  * LAFS Circuit Breaker Module
  *
- * Provides circuit breaker pattern for resilient service calls
+ * Provides circuit breaker pattern for resilient service calls.
+ *
+ * @packageDocumentation
+ */
+/**
+ * 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 class CircuitBreakerError extends Error {
+    /**
+     * Creates a new CircuitBreakerError.
+     *
+     * @param message - Descriptive error message indicating why the call was rejected
+     */
     constructor(message) {
         super(message);
         this.name = 'CircuitBreakerError';
     }
 }
 /**
- * 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
@@ -35,14 +67,27 @@ export class CircuitBreakerError extends Error {
  */
 export class CircuitBreaker {
     config;
+    /** Current circuit state. */
     state = 'CLOSED';
+    /** Total failure count since last reset. */
     failures = 0;
+    /** Total success count since last reset. */
     successes = 0;
+    /** Timestamp of the most recent failure. */
     lastFailureTime;
+    /** Consecutive successes since the last failure. */
     consecutiveSuccesses = 0;
+    /** Lifetime call count. */
     totalCalls = 0;
+    /** Number of calls made while in the HALF_OPEN state. */
     halfOpenCalls = 0;
+    /** Timer handle for the scheduled OPEN-to-HALF_OPEN transition. */
     resetTimer;
+    /**
+     * Creates a new CircuitBreaker with the given configuration.
+     *
+     * @param config - Circuit breaker configuration with name, thresholds, and timeouts
+     */
     constructor(config) {
         this.config = config;
         this.config = {
@@ -50,11 +95,28 @@ export class CircuitBreaker {
             resetTimeout: 30000,
             halfOpenMaxCalls: 3,
             successThreshold: 2,
-            ...config
+            ...config,
         };
     }
     /**
-     * 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');
+     * });
+     * ```
      */
     async execute(fn) {
         this.totalCalls++;
@@ -83,13 +145,40 @@ export class CircuitBreaker {
         }
     }
     /**
-     * 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() {
         return this.state;
     }
     /**
-     * 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() {
         return {
@@ -98,22 +187,45 @@ export class CircuitBreaker {
             successes: this.successes,
             lastFailureTime: this.lastFailureTime,
             consecutiveSuccesses: this.consecutiveSuccesses,
-            totalCalls: this.totalCalls
+            totalCalls: this.totalCalls,
         };
     }
     /**
-     * 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() {
         this.transitionTo('OPEN');
     }
     /**
-     * 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() {
         this.transitionTo('CLOSED');
         this.reset();
     }
+    /** Records a successful call and may transition from HALF_OPEN to CLOSED. */
     onSuccess() {
         this.successes++;
         this.consecutiveSuccesses++;
@@ -124,6 +236,7 @@ export class CircuitBreaker {
             }
         }
     }
+    /** Records a failed call and may trip the circuit to OPEN. */
     onFailure() {
         this.failures++;
         this.consecutiveSuccesses = 0;
@@ -139,6 +252,7 @@ export class CircuitBreaker {
             }
         }
     }
+    /** Transitions the circuit to the given state, resetting HALF_OPEN call count when entering HALF_OPEN. */
     transitionTo(newState) {
         console.log(`Circuit breaker '${this.config.name}': ${this.state} -> ${newState}`);
         this.state = newState;
@@ -146,12 +260,14 @@ export class CircuitBreaker {
             this.halfOpenCalls = 0;
         }
     }
+    /** Returns `true` if enough time has elapsed since the last failure to attempt a reset. */
     shouldAttemptReset() {
         if (!this.lastFailureTime)
             return true;
         const elapsed = Date.now() - this.lastFailureTime.getTime();
         return elapsed >= (this.config.resetTimeout || 30000);
     }
+    /** Schedules a timer to transition from OPEN to HALF_OPEN after the configured reset timeout. */
     scheduleReset() {
         if (this.resetTimer) {
             clearTimeout(this.resetTimer);
@@ -162,6 +278,7 @@ export class CircuitBreaker {
             }
         }, this.config.resetTimeout || 30000);
     }
+    /** Resets all failure/success counters and clears the pending reset timer. */
     reset() {
         this.failures = 0;
         this.consecutiveSuccesses = 0;
@@ -173,7 +290,12 @@ export class CircuitBreaker {
     }
 }
 /**
- * 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
@@ -188,15 +310,65 @@ export class CircuitBreaker {
  * ```
  */
 export class CircuitBreakerRegistry {
+    /** Internal map of circuit breaker name to instance. */
     breakers = new Map();
+    /**
+     * 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, config) {
         const breaker = new CircuitBreaker({ ...config, name });
         this.breakers.set(name, breaker);
         return breaker;
     }
+    /**
+     * 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) {
         return this.breakers.get(name);
     }
+    /**
+     * 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, config) {
         let breaker = this.breakers.get(name);
         if (!breaker) {
@@ -204,6 +376,23 @@ export class CircuitBreakerRegistry {
         }
         return breaker;
     }
+    /**
+     * 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() {
         const metrics = {};
         this.breakers.forEach((breaker, name) => {
@@ -211,12 +400,34 @@ export class CircuitBreakerRegistry {
         });
         return metrics;
     }
+    /**
+     * 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() {
-        this.breakers.forEach(breaker => breaker.forceClose());
+        this.breakers.forEach((breaker) => {
+            breaker.forceClose();
+        });
     }
 }
 /**
- * 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
@@ -228,7 +439,7 @@ export class CircuitBreakerRegistry {
  */
 export function circuitBreakerMiddleware(config) {
     const breaker = new CircuitBreaker(config);
-    return async (req, res, next) => {
+    return async (_req, res, next) => {
         try {
             await breaker.execute(async () => {
                 next();
@@ -238,7 +449,7 @@ export function circuitBreakerMiddleware(config) {
             if (error instanceof CircuitBreakerError) {
                 res.status(503).json({
                     error: 'Service temporarily unavailable',
-                    reason: 'Circuit breaker is open'
+                    reason: 'Circuit breaker is open',
                 });
             }
             else {
@@ -247,3 +458,4 @@ export function circuitBreakerMiddleware(config) {
         }
     };
 }
+//# sourceMappingURL=index.js.map

package/dist/src/circuit-breaker/index.js.map

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

package/dist/src/cli.d.ts

@@ -14,3 +14,4 @@
  * @epic T034
  */
 export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;GAaG"}

package/dist/src/cli.js

@@ -13,18 +13,18 @@
  * @task T042
  * @epic T034
  */
-import { readFile } from "node:fs/promises";
-import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
+import { readFile } from 'node:fs/promises';
+import { runEnvelopeConformance, runFlagConformance } from './conformance.js';
 function parseArgs(argv) {
     const args = {};
     for (let i = 0; i < argv.length; i += 1) {
         const current = argv[i];
         const next = argv[i + 1];
-        if (current === "--envelope" && next) {
+        if (current === '--envelope' && next) {
             args.envelopePath = next;
             i += 1;
         }
-        else if (current === "--flags" && next) {
+        else if (current === '--flags' && next) {
             args.flagsPath = next;
             i += 1;
         }
@@ -32,7 +32,7 @@ function parseArgs(argv) {
     return args;
 }
 async function readJson(path) {
-    const content = await readFile(path, "utf8");
+    const content = await readFile(path, 'utf8');
     return JSON.parse(content);
 }
 async function main() {
@@ -40,14 +40,14 @@ async function main() {
     const reports = [];
     if (args.envelopePath) {
         const envelope = await readJson(args.envelopePath);
-        reports.push({ name: "envelope", report: runEnvelopeConformance(envelope) });
+        reports.push({ name: 'envelope', report: runEnvelopeConformance(envelope) });
     }
     if (args.flagsPath) {
         const flags = await readJson(args.flagsPath);
-        reports.push({ name: "flags", report: runFlagConformance(flags) });
+        reports.push({ name: 'flags', report: runFlagConformance(flags) });
     }
     if (reports.length === 0) {
-        throw new Error("Provide --envelope and/or --flags JSON files.");
+        throw new Error('Provide --envelope and/or --flags JSON files.');
     }
     console.log(JSON.stringify({ success: true, reports }, null, 2));
 }
@@ -55,9 +55,10 @@ main().catch((error) => {
     console.error(JSON.stringify({
         success: false,
         error: {
-            code: "E_INTERNAL_UNEXPECTED",
-            message: error instanceof Error ? error.message : String(error)
-        }
+            code: 'E_INTERNAL_UNEXPECTED',
+            message: error instanceof Error ? error.message : String(error),
+        },
     }, null, 2));
     process.exit(1);
 });
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAO9E,SAAS,SAAS,CAAC,IAAc;IAC/B,MAAM,IAAI,GAAY,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,IAAI,OAAO,KAAK,YAAY,IAAI,IAAI,EAAE,CAAC;YACrC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;aAAM,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,EAAE,CAAC;YACzC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,IAAY;IAClC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;AACxC,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9C,MAAM,OAAO,GAAc,EAAE,CAAC;IAE9B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,CAAC,KAAc,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CACX,IAAI,CAAC,SAAS,CACZ;QACE,OAAO,EAAE,KAAK;QACd,KAAK,EAAE;YACL,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAChE;KACF,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}