cmp-standards 2.8.1 → 3.1.0

package/dist/utils/resilience.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Resilience Utilities
+ *
+ * Provides fault-tolerant patterns for network operations:
+ * - Retry with exponential backoff
+ * - Timeout protection
+ * - Circuit breaker pattern
+ * - Rate limiting helpers
+ *
+ * @version 2.9.1
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Base delay in milliseconds (default: 1000) */
+    baseDelay: number;
+    /** Maximum delay cap in milliseconds (default: 30000) */
+    maxDelay: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier: number;
+    /** Jitter factor 0-1 to randomize delays (default: 0.1) */
+    jitter: number;
+    /** Function to determine if error is retryable (default: all errors) */
+    isRetryable?: (error: unknown) => boolean;
+    /** Callback on each retry attempt */
+    onRetry?: (attempt: number, error: unknown, nextDelay: number) => void;
+}
+export interface TimeoutOptions<T> {
+    /** Timeout in milliseconds */
+    timeoutMs: number;
+    /** Fallback value if timeout occurs */
+    fallback?: T;
+    /** Error message for timeout */
+    message?: string;
+    /** Callback when timeout occurs */
+    onTimeout?: () => void;
+}
+export interface CircuitBreakerOptions {
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold: number;
+    /** Time in ms to wait before half-open state (default: 30000) */
+    resetTimeout: number;
+    /** Number of successes needed in half-open to close (default: 2) */
+    successThreshold: number;
+    /** Callback when circuit state changes */
+    onStateChange?: (state: CircuitState) => void;
+}
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export declare class RetryableError extends Error {
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, retryAfter?: number | undefined);
+}
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+export declare class CircuitOpenError extends Error {
+    readonly resetAt?: number | undefined;
+    constructor(message?: string, resetAt?: number | undefined);
+}
+/**
+ * Execute operation with retry logic and exponential backoff
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetch('https://api.example.com/data'),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * )
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Check if an HTTP status code is retryable
+ */
+export declare function isRetryableHttpStatus(status: number): boolean;
+/**
+ * Check if an error is a network/transient error
+ */
+export declare function isTransientError(error: unknown): boolean;
+/**
+ * Execute operation with timeout protection
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   fetch('https://api.example.com/data'),
+ *   { timeoutMs: 5000, fallback: null }
+ * )
+ * ```
+ */
+export declare function withTimeout<T>(promise: Promise<T>, options: TimeoutOptions<T>): Promise<T>;
+/**
+ * Create an AbortController with automatic timeout
+ */
+export declare function createTimeoutController(timeoutMs: number): {
+    controller: AbortController;
+    cleanup: () => void;
+};
+/**
+ * Circuit Breaker for protecting against cascade failures
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({ failureThreshold: 5 })
+ *
+ * try {
+ *   const result = await breaker.execute(() => riskyOperation())
+ * } catch (error) {
+ *   if (error instanceof CircuitOpenError) {
+ *     // Circuit is open, use fallback
+ *   }
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private options;
+    constructor(options?: Partial<CircuitBreakerOptions>);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit statistics
+     */
+    getStats(): {
+        state: CircuitState;
+        failures: number;
+        successes: number;
+        lastFailureTime: number;
+    };
+    /**
+     * Execute operation through circuit breaker
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Record successful operation
+     */
+    private onSuccess;
+    /**
+     * Record failed operation
+     */
+    private onFailure;
+    /**
+     * Transition to new state
+     */
+    private transitionTo;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Manually trip the circuit breaker
+     */
+    trip(): void;
+}
+/**
+ * Execute operation with retry, timeout, and circuit breaker
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker()
+ *
+ * const result = await withResilience(
+ *   () => fetch('https://api.example.com/data'),
+ *   {
+ *     retry: { maxRetries: 3 },
+ *     timeout: { timeoutMs: 5000 },
+ *     circuitBreaker: breaker
+ *   }
+ * )
+ * ```
+ */
+export declare function withResilience<T>(operation: () => Promise<T>, options: {
+    retry?: Partial<RetryOptions>;
+    timeout?: TimeoutOptions<T>;
+    circuitBreaker?: CircuitBreaker;
+}): Promise<T>;
+/**
+ * Simple mutex for protecting async initialization
+ *
+ * @example
+ * ```typescript
+ * const initMutex = new AsyncMutex()
+ * let instance: Client | null = null
+ *
+ * async function getInstance() {
+ *   if (instance) return instance
+ *   return initMutex.runExclusive(async () => {
+ *     if (instance) return instance // Double-check after acquiring lock
+ *     instance = await createClient()
+ *     return instance
+ *   })
+ * }
+ * ```
+ */
+export declare class AsyncMutex {
+    private locked;
+    private queue;
+    /**
+     * Check if mutex is currently locked
+     */
+    isLocked(): boolean;
+    /**
+     * Acquire the mutex lock
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release the mutex lock
+     */
+    release(): void;
+    /**
+     * Run operation exclusively (acquires and releases automatically)
+     */
+    runExclusive<T>(operation: () => Promise<T>): Promise<T>;
+}
+/**
+ * Execute cache operation safely (returns null on error instead of throwing)
+ */
+export declare function safeCacheGet<T>(operation: () => Promise<T | null>, context?: string): Promise<T | null>;
+/**
+ * Execute cache set operation safely (returns success boolean)
+ */
+export declare function safeCacheSet(operation: () => Promise<void>, context?: string): Promise<boolean>;
+export interface BatchResult<T, E = unknown> {
+    succeeded: T[];
+    failed: Array<{
+        item: unknown;
+        error: E;
+    }>;
+    total: number;
+    successRate: number;
+}
+/**
+ * Process items in batches with individual error handling
+ *
+ * @example
+ * ```typescript
+ * const result = await processBatch(
+ *   items,
+ *   async (item) => await processItem(item),
+ *   { chunkSize: 10, concurrency: 5 }
+ * )
+ * console.log(`Processed ${result.succeeded.length}/${result.total}`)
+ * ```
+ */
+export declare function processBatch<T, R>(items: T[], processor: (item: T, index: number) => Promise<R>, options?: {
+    chunkSize?: number;
+    concurrency?: number;
+    delayBetweenChunks?: number;
+    onProgress?: (processed: number, total: number) => void;
+}): Promise<BatchResult<R>>;
+//# sourceMappingURL=resilience.d.ts.map

package/dist/utils/resilience.d.ts.map

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