observability-toolkit 2.0.0 → 2.1.1

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

@@ -0,0 +1,251 @@
+/**
+ * Circuit breaker pattern implementation for resilient I/O operations
+ *
+ * Prevents cascading failures by temporarily stopping requests to a failing service.
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Service failing, requests are rejected immediately
+ * - HALF-OPEN: Testing if service recovered, allows one request through
+ *
+ * ## Thread Safety
+ * This implementation is safe for Node.js single-threaded event loop.
+ * The half-open slot claim uses synchronous check-and-set which is atomic
+ * within a single event loop tick (no await/yield between check and set).
+ * NOT safe for worker_threads without additional synchronization.
+ *
+ * ## OTel Metrics (P3-2)
+ * When OTEL_ENABLED=true, state transitions are exported as OTel metrics:
+ * - obs_toolkit.circuit_breaker.state: State value (0=closed, 1=half-open, 2=open)
+ */
+import { z } from 'zod';
+import { CIRCUIT_BREAKER } from '../core/constants.js';
+import { createLogger } from '../core/logger.js';
+import { recordCircuitBreakerState } from '../observability/metrics.js';
+const logger = createLogger('circuit-breaker');
+const HTTP_TOO_MANY_REQUESTS = 429;
+const RATE_LIMIT_ERROR_NAMES = [
+    'RateLimitError',
+    'ThrottlingException',
+    'TooManyRequestsError',
+    'RateLimitExceeded',
+];
+const RATE_LIMIT_ERROR_CODES = [
+    'ThrottlingException',
+    'TooManyRequestsException',
+    'ProvisionedThroughputExceededException',
+];
+const RATE_LIMIT_MESSAGE_PATTERN = /\brate[_\s-]?limit|\b429\b|\bthrottl|\btoo[\s]{1,10}many[\s]{1,10}requests\b/i;
+/**
+ * Check whether an error represents a rate-limit / throttling response.
+ * Useful as a `failureFilter` to exempt transient 429s from tripping the breaker.
+ */
+export function isRateLimitError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if (RATE_LIMIT_ERROR_NAMES.includes(error.name)) {
+        return true;
+    }
+    const errorWithStatus = error;
+    if (errorWithStatus.statusCode === HTTP_TOO_MANY_REQUESTS || errorWithStatus.status === HTTP_TOO_MANY_REQUESTS) {
+        return true;
+    }
+    if (errorWithStatus.code !== undefined &&
+        RATE_LIMIT_ERROR_CODES.includes(errorWithStatus.code)) {
+        return true;
+    }
+    if (error.message && typeof error.message === 'string') {
+        return RATE_LIMIT_MESSAGE_PATTERN.test(error.message);
+    }
+    return false;
+}
+export const circuitStateSchema = z.enum(['closed', 'open', 'half-open']);
+export const circuitBreakerOptionsSchema = z.object({
+    /** Number of consecutive failures before opening circuit (default: 3) */
+    maxFailures: z.number().int().positive().optional(),
+    /** Time in ms before attempting recovery (default: 60_000) */
+    resetMs: z.number().int().positive().optional(),
+    /** Name for logging purposes */
+    name: z.string().min(1).optional(),
+});
+/**
+ * Circuit breaker for I/O operations (API calls, file operations, LLM judge calls)
+ *
+ * Manual usage:
+ * ```ts
+ * const breaker = new CircuitBreaker({ name: 'local-file' });
+ *
+ * if (!breaker.canRequest()) {
+ *   return []; // Circuit is open, fail fast
+ * }
+ *
+ * try {
+ *   const result = await riskyOperation();
+ *   breaker.recordSuccess();
+ *   return result;
+ * } catch (error) {
+ *   breaker.recordFailure();
+ *   throw error;
+ * }
+ * ```
+ *
+ * Wrapped usage:
+ * ```ts
+ * const breaker = new CircuitBreaker({
+ *   name: 'judge',
+ *   failureFilter: (e) => !isRateLimitError(e),
+ * });
+ * const result = await breaker.evaluate(() => callLLM(), () => fallbackScore());
+ * ```
+ */
+export class CircuitBreaker {
+    failures = 0;
+    lastFailure = 0;
+    state = 'closed';
+    /** Prevents multiple concurrent requests during half-open state */
+    halfOpenRequestInFlight = false;
+    openCount = 0;
+    resetCount = 0;
+    maxFailures;
+    resetMs;
+    name;
+    failureFilter;
+    constructor(options = {}) {
+        this.maxFailures = options.maxFailures ?? CIRCUIT_BREAKER.MAX_FAILURES;
+        this.resetMs = options.resetMs ?? CIRCUIT_BREAKER.RESET_MS;
+        this.name = options.name ?? 'circuit-breaker';
+        this.failureFilter = options.failureFilter;
+    }
+    /**
+     * Atomically claim the half-open slot for testing recovery.
+     * Returns true if this caller won the slot, false if another caller already has it.
+     *
+     * Thread safety: This is atomic in Node.js single-threaded event loop because
+     * there's no await/yield between the check and set operations.
+     */
+    claimHalfOpenSlot() {
+        // Atomic in single-threaded Node.js: no async between check and set
+        if (this.halfOpenRequestInFlight) {
+            return false;
+        }
+        this.halfOpenRequestInFlight = true;
+        return true;
+    }
+    /**
+     * Check if a request can proceed
+     * Returns false if circuit is open (and not ready to retry)
+     * In half-open state, only one request is allowed through at a time
+     */
+    canRequest() {
+        if (this.state === 'open') {
+            if (Date.now() - this.lastFailure > this.resetMs) {
+                // Atomically claim half-open slot - only one request tests recovery
+                if (!this.claimHalfOpenSlot()) {
+                    return false; // Another request is already testing recovery
+                }
+                logger.info(`${this.name}: entering HALF-OPEN state (reset timeout elapsed)`);
+                this.state = 'half-open';
+                recordCircuitBreakerState(this.name, 'half-open');
+                return true;
+            }
+            return false;
+        }
+        // In half-open state, reject if a request is already in flight
+        if (this.state === 'half-open' && this.halfOpenRequestInFlight) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Record a successful operation
+     * Closes the circuit if in half-open state
+     */
+    recordSuccess() {
+        this.halfOpenRequestInFlight = false;
+        const wasHalfOpen = this.state === 'half-open';
+        if (wasHalfOpen) {
+            logger.info(`${this.name}: CLOSED after successful request`);
+        }
+        this.failures = 0;
+        this.state = 'closed';
+        if (wasHalfOpen) {
+            recordCircuitBreakerState(this.name, 'closed');
+        }
+    }
+    /**
+     * Record a failed operation
+     * Opens the circuit after maxFailures consecutive failures
+     */
+    recordFailure() {
+        this.halfOpenRequestInFlight = false;
+        this.failures++;
+        this.lastFailure = Date.now();
+        if (this.failures >= this.maxFailures && this.state !== 'open') {
+            const previousState = this.state;
+            this.state = 'open';
+            this.openCount++;
+            logger.warn(`${this.name}: OPENED after ${this.failures} consecutive failures (was: ${previousState})`);
+            recordCircuitBreakerState(this.name, 'open');
+        }
+    }
+    /**
+     * Execute an async function with circuit breaker protection.
+     * Applies `failureFilter` when set — filtered errors are rethrown but not counted.
+     * Delegates to `fallback` when the circuit is open, or throws if no fallback.
+     */
+    async evaluate(fn, fallback) {
+        if (!this.canRequest()) {
+            if (fallback) {
+                return fallback();
+            }
+            throw new Error(`Circuit breaker open - ${this.name} temporarily unavailable`);
+        }
+        try {
+            const result = await fn();
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            const shouldCount = this.failureFilter ? this.failureFilter(error) : true;
+            if (shouldCount) {
+                this.recordFailure();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get current failure count
+     */
+    getFailureCount() {
+        return this.failures;
+    }
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats() {
+        return { openCount: this.openCount, resetCount: this.resetCount };
+    }
+    /**
+     * Reset circuit to closed state (useful for testing)
+     */
+    reset() {
+        this.failures = 0;
+        this.lastFailure = 0;
+        this.state = 'closed';
+        this.halfOpenRequestInFlight = false;
+        this.resetCount++;
+    }
+    /**
+     * Check if a half-open request is in flight (for testing)
+     */
+    isHalfOpenRequestInFlight() {
+        return this.halfOpenRequestInFlight;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/lib/resilience/circuit-breaker.js.map

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

package/dist/lib/resilience/circuit-breaker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.test.d.ts","sourceRoot":"","sources":["../../../src/lib/resilience/circuit-breaker.test.ts"],"names":[],"mappings":""}

package/dist/lib/resilience/circuit-breaker.test.js

@@ -0,0 +1,266 @@
+import { describe, it, beforeAll as before, afterAll as after, beforeEach } from 'vitest';
+import * as assert from 'node:assert';
+import { CircuitBreaker } from './circuit-breaker.js';
+import { CIRCUIT_BREAKER, } from '../core/constants.js';
+import { ONE_MILLION, } from '../core/units.js';
+import { COUNT_TWO } from '../../test-helpers/test-constants.js';
+describe('CircuitBreaker', () => {
+    describe('initial state', () => {
+        it('should start in closed state', () => {
+            const breaker = new CircuitBreaker();
+            assert.strictEqual(breaker.getState(), 'closed');
+            assert.strictEqual(breaker.getFailureCount(), 0);
+        });
+        it('should allow requests when closed', () => {
+            const breaker = new CircuitBreaker();
+            assert.strictEqual(breaker.canRequest(), true);
+        });
+    });
+    describe('failure handling', () => {
+        it('should track consecutive failures', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getFailureCount(), 1);
+            assert.strictEqual(breaker.getState(), 'closed');
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getFailureCount(), COUNT_TWO);
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+        it('should open after maxFailures consecutive failures', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            assert.strictEqual(breaker.getFailureCount(), CIRCUIT_BREAKER.MAX_FAILURES);
+        });
+        it('should reject requests when open', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.canRequest(), false);
+        });
+    });
+    describe('success handling', () => {
+        it('should reset failure count on success', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getFailureCount(), COUNT_TWO);
+            breaker.recordSuccess();
+            assert.strictEqual(breaker.getFailureCount(), 0);
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+        it('should stay closed after partial failures followed by success', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordSuccess();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Should still be closed (only 2 consecutive failures)
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+    });
+    describe('half-open state', () => {
+        let originalDateNow;
+        let currentTime;
+        before(() => {
+            originalDateNow = Date.now;
+        });
+        beforeEach(() => {
+            currentTime = ONE_MILLION;
+            Date.now = () => currentTime;
+        });
+        after(() => {
+            Date.now = originalDateNow;
+        });
+        it('should transition to half-open after reset timeout', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            // Advance time past reset period
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            // Should transition to half-open and allow request
+            assert.strictEqual(breaker.canRequest(), true);
+            assert.strictEqual(breaker.getState(), 'half-open');
+        });
+        it('should close on success in half-open state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Advance time and allow half-open
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            breaker.canRequest();
+            assert.strictEqual(breaker.getState(), 'half-open');
+            // Success should close the circuit
+            breaker.recordSuccess();
+            assert.strictEqual(breaker.getState(), 'closed');
+            assert.strictEqual(breaker.getFailureCount(), 0);
+        });
+        it('should reopen on failure in half-open state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Advance time and allow half-open
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            breaker.canRequest();
+            assert.strictEqual(breaker.getState(), 'half-open');
+            // Failure should reopen
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+        it('should not allow request before reset timeout', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            // Advance time but not past reset period
+            currentTime += CIRCUIT_BREAKER.RESET_MS / COUNT_TWO;
+            assert.strictEqual(breaker.canRequest(), false);
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+    });
+    describe('reset', () => {
+        it('should reset to initial state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            // Reset
+            breaker.reset();
+            assert.strictEqual(breaker.getState(), 'closed');
+            assert.strictEqual(breaker.getFailureCount(), 0);
+            assert.strictEqual(breaker.canRequest(), true);
+        });
+        it('should reset halfOpenRequestInFlight flag', () => {
+            const originalDateNow = Date.now;
+            let currentTime = ONE_MILLION;
+            Date.now = () => currentTime;
+            try {
+                const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+                // Open and transition to half-open
+                breaker.recordFailure();
+                breaker.recordFailure();
+                breaker.recordFailure();
+                currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+                breaker.canRequest();
+                // Flag should be set
+                assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+                // Reset should clear it
+                breaker.reset();
+                assert.strictEqual(breaker.isHalfOpenRequestInFlight(), false);
+            }
+            finally {
+                Date.now = originalDateNow;
+            }
+        });
+    });
+    describe('half-open race condition prevention (H2)', () => {
+        let originalDateNow;
+        let currentTime;
+        before(() => {
+            originalDateNow = Date.now;
+        });
+        beforeEach(() => {
+            currentTime = ONE_MILLION;
+            Date.now = () => currentTime;
+        });
+        after(() => {
+            Date.now = originalDateNow;
+        });
+        it('should only allow one request through during half-open state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Advance time past reset period
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            // First request should be allowed (transitions to half-open)
+            assert.strictEqual(breaker.canRequest(), true);
+            assert.strictEqual(breaker.getState(), 'half-open');
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+            // Second concurrent request should be rejected
+            assert.strictEqual(breaker.canRequest(), false);
+            assert.strictEqual(breaker.getState(), 'half-open');
+        });
+        it('should clear halfOpenRequestInFlight on success', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open and transition to half-open
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            breaker.canRequest();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+            // Success should clear the flag
+            breaker.recordSuccess();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), false);
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+        it('should clear halfOpenRequestInFlight on failure', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open and transition to half-open
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            breaker.canRequest();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+            // Failure should clear the flag
+            breaker.recordFailure();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), false);
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+        it('should allow next request after half-open failure and timeout', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: CIRCUIT_BREAKER.RESET_MS });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // First half-open attempt
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            assert.strictEqual(breaker.canRequest(), true);
+            breaker.recordFailure();
+            // Should be open again
+            assert.strictEqual(breaker.getState(), 'open');
+            // Wait for another reset period
+            currentTime += CIRCUIT_BREAKER.RESET_MS + 1;
+            // Should allow another half-open request
+            assert.strictEqual(breaker.canRequest(), true);
+            assert.strictEqual(breaker.getState(), 'half-open');
+        });
+    });
+    describe('configuration', () => {
+        it('should use custom maxFailures', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 5 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'closed');
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+        it('should use custom name in logging', () => {
+            const breaker = new CircuitBreaker({ name: 'test-breaker' });
+            // Name is used internally for logging, verify it doesn't throw
+            breaker.recordFailure();
+            breaker.recordSuccess();
+        });
+    });
+});
+//# sourceMappingURL=circuit-breaker.test.js.map

package/dist/lib/resilience/circuit-breaker.test.js.map

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

package/dist/lib/resilience/toon-encoder.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TOON (Token-Oriented Object Notation) encoding utilities
+ * Provides 40-60% token reduction for uniform array responses
+ */
+import { z } from 'zod';
+export declare const responseFormatSchema: z.ZodEnum<{
+    json: "json";
+    toon: "toon";
+}>;
+export type ResponseFormat = z.infer<typeof responseFormatSchema>;
+/** Maximum elements to encode in toToon (prevents process freezing on large arrays) */
+export declare const MAX_TOON_ELEMENTS = 10000;
+/**
+ * Encode data to TOON format
+ * @param data - Data to encode (typically an array of objects)
+ * @param maxElements - Maximum elements to encode (default: 10000)
+ * @returns TOON-encoded string
+ * @throws Error if data exceeds maxElements (prevents process freezing)
+ *
+ * Security: Logs encoding failures for debugging instead of silently falling back
+ */
+export declare function toToon<T>(data: T[], maxElements?: number): string;
+/**
+ * Check if TOON format is beneficial for the given data
+ * TOON works best with uniform arrays of objects
+ * @param data - Data to check
+ * @param maxElements - Maximum elements to consider (default: MAX_TOON_ELEMENTS)
+ * @returns true if TOON would be beneficial
+ */
+export declare function isToonBeneficial(data: unknown[], maxElements?: number): boolean;
+//# sourceMappingURL=toon-encoder.d.ts.map

package/dist/lib/resilience/toon-encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon-encoder.d.ts","sourceRoot":"","sources":["../../../src/lib/resilience/toon-encoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,oBAAoB;;;EAA2B,CAAC;AAE7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAGlE,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,GAAE,MAA0B,GAAG,MAAM,CAkBpF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,WAAW,GAAE,MAA0B,GAAG,OAAO,CAkBlG"}

package/dist/lib/resilience/toon-encoder.js

@@ -0,0 +1,66 @@
+/**
+ * TOON (Token-Oriented Object Notation) encoding utilities
+ * Provides 40-60% token reduction for uniform array responses
+ */
+import { z } from 'zod';
+import { encode as toonEncode } from '@toon-format/toon';
+import { createLogger } from '../core/logger.js';
+const configLog = createLogger('config');
+export const responseFormatSchema = z.enum(['json', 'toon']);
+const MIN_TOON_BENEFICIAL_LENGTH = 2;
+/** Maximum elements to encode in toToon (prevents process freezing on large arrays) */
+export const MAX_TOON_ELEMENTS = 10000;
+/**
+ * Encode data to TOON format
+ * @param data - Data to encode (typically an array of objects)
+ * @param maxElements - Maximum elements to encode (default: 10000)
+ * @returns TOON-encoded string
+ * @throws Error if data exceeds maxElements (prevents process freezing)
+ *
+ * Security: Logs encoding failures for debugging instead of silently falling back
+ */
+export function toToon(data, maxElements = MAX_TOON_ELEMENTS) {
+    if (Array.isArray(data) && data.length > 0) {
+        // M4: Prevent process freezing on million-element arrays
+        if (data.length > maxElements) {
+            throw new Error(`TOON encoding limit exceeded: ${data.length} elements > ${maxElements} max`);
+        }
+        try {
+            return toonEncode(data);
+        }
+        catch (error) {
+            // Log warning for debugging - silent fallback makes issues hard to diagnose
+            configLog.warn('TOON encoding failed, falling back to JSON', { error: error instanceof Error ? error.message : String(error) });
+            return JSON.stringify(data);
+        }
+    }
+    return JSON.stringify(data);
+}
+/**
+ * Check if TOON format is beneficial for the given data
+ * TOON works best with uniform arrays of objects
+ * @param data - Data to check
+ * @param maxElements - Maximum elements to consider (default: MAX_TOON_ELEMENTS)
+ * @returns true if TOON would be beneficial
+ */
+export function isToonBeneficial(data, maxElements = MAX_TOON_ELEMENTS) {
+    // M4: Early exit for oversized arrays to avoid expensive key comparisons
+    if (!Array.isArray(data) || data.length < MIN_TOON_BENEFICIAL_LENGTH || data.length > maxElements)
+        return false;
+    // Check if all items are objects with same keys
+    const firstItem = data[0];
+    if (typeof firstItem !== 'object' || firstItem === null)
+        return false;
+    // M8: Cache first keys string to avoid repeated Object.keys() calls
+    const firstKeys = Object.keys(firstItem).sort().join(',');
+    // Use for loop with early exit instead of .every() for better performance
+    for (let i = 1; i < data.length; i++) {
+        const item = data[i];
+        if (typeof item !== 'object' || item === null)
+            return false;
+        if (Object.keys(item).sort().join(',') !== firstKeys)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=toon-encoder.js.map

package/dist/lib/resilience/toon-encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon-encoder.js","sourceRoot":"","sources":["../../../src/lib/resilience/toon-encoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;AAEzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAG7D,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAErC,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAI,IAAS,EAAE,cAAsB,iBAAiB;IAC1E,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,yDAAyD;QACzD,IAAI,IAAI,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,CAAC,MAAM,eAAe,WAAW,MAAM,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4EAA4E;YAC5E,SAAS,CAAC,IAAI,CACZ,4CAA4C,EAC5C,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAClE,CAAC;YACF,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe,EAAE,cAAsB,iBAAiB;IACvF,yEAAyE;IACzE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,0BAA0B,IAAI,IAAI,CAAC,MAAM,GAAG,WAAW;QAAE,OAAO,KAAK,CAAC;IAEhH,gDAAgD;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEtE,oEAAoE;IACpE,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE1D,0EAA0E;IAC1E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC5D,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/lib/resilience/toon-encoder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon-encoder.test.d.ts","sourceRoot":"","sources":["../../../src/lib/resilience/toon-encoder.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}