dartmind 17.0.0

package/dist/v10/recovery/RetryEngine.d.ts

@@ -0,0 +1,265 @@
+/**
+ * FlutterAI v10 - Retry Engine
+ *
+ * Configurable retry logic with multiple backoff strategies.
+ *
+ * Features:
+ * - Multiple backoff strategies (constant, linear, exponential, decorrelated jitter)
+ * - Retry budgets
+ * - Condition-based retries
+ * - Abort signals
+ * - Retry hooks
+ * - Circuit breaker integration
+ *
+ * @module v10/recovery/RetryEngine
+ */
+import { EventEmitter } from 'events';
+/**
+ * Backoff strategy types
+ */
+export type BackoffStrategy = 'constant' | 'linear' | 'exponential' | 'exponential_jitter' | 'decorrelated_jitter' | 'fibonacci' | 'custom';
+/**
+ * Retry state
+ */
+export type RetryState = 'idle' | 'retrying' | 'success' | 'exhausted' | 'aborted';
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    /** Maximum retry attempts */
+    maxAttempts?: number;
+    /** Backoff strategy */
+    backoff?: BackoffStrategy;
+    /** Initial delay in ms */
+    initialDelay?: number;
+    /** Maximum delay in ms */
+    maxDelay?: number;
+    /** Backoff multiplier (for exponential) */
+    multiplier?: number;
+    /** Jitter factor (0-1) */
+    jitter?: number;
+    /** Custom delay function */
+    delayFn?: (attempt: number, lastDelay: number) => number;
+    /** Condition to retry (return true to retry) */
+    retryCondition?: (error: Error, attempt: number) => boolean;
+    /** Timeout per attempt in ms */
+    attemptTimeout?: number;
+    /** Total timeout for all retries in ms */
+    totalTimeout?: number;
+    /** Abort signal */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Retry attempt info
+ */
+export interface RetryAttemptInfo {
+    attempt: number;
+    delay: number;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    error?: Error;
+    success: boolean;
+}
+/**
+ * Retry result
+ */
+export interface RetryResult<T> {
+    success: boolean;
+    result?: T;
+    error?: Error;
+    attempts: RetryAttemptInfo[];
+    totalAttempts: number;
+    totalDuration: number;
+    state: RetryState;
+}
+/**
+ * Retry budget configuration
+ */
+export interface RetryBudgetConfig {
+    /** Time window in ms */
+    window: number;
+    /** Maximum retries in window */
+    maxRetries: number;
+    /** Minimum success ratio to allow retries */
+    minSuccessRatio?: number;
+}
+/**
+ * Retry budget state
+ */
+export interface RetryBudgetState {
+    available: number;
+    used: number;
+    successes: number;
+    failures: number;
+    windowStart: number;
+    allowed: boolean;
+}
+/**
+ * Retry hooks
+ */
+export interface RetryHooks<T> {
+    /** Called before each attempt */
+    onAttempt?: (attempt: number, delay: number) => void | Promise<void>;
+    /** Called after successful attempt */
+    onSuccess?: (result: T, attempt: number) => void | Promise<void>;
+    /** Called after failed attempt */
+    onError?: (error: Error, attempt: number) => void | Promise<void>;
+    /** Called before delay */
+    onDelay?: (delay: number, attempt: number) => void | Promise<void>;
+    /** Called when retries exhausted */
+    onExhausted?: (lastError: Error, attempts: number) => void | Promise<void>;
+    /** Called when aborted */
+    onAbort?: (attempt: number) => void | Promise<void>;
+}
+/**
+ * Engine configuration
+ */
+export interface RetryEngineConfig {
+    /** Default retry config */
+    defaults?: RetryConfig;
+    /** Global retry budget */
+    budget?: RetryBudgetConfig;
+    /** Maximum concurrent retries */
+    maxConcurrent?: number;
+}
+/**
+ * Retry event
+ */
+export type RetryEvent = {
+    type: 'attempt_started';
+    attempt: number;
+    delay: number;
+} | {
+    type: 'attempt_success';
+    attempt: number;
+    duration: number;
+} | {
+    type: 'attempt_failed';
+    attempt: number;
+    error: Error;
+} | {
+    type: 'delay_started';
+    attempt: number;
+    delay: number;
+} | {
+    type: 'retries_exhausted';
+    attempts: number;
+    lastError: Error;
+} | {
+    type: 'retry_aborted';
+    attempt: number;
+} | {
+    type: 'budget_exceeded';
+    used: number;
+    max: number;
+};
+/**
+ * Retry engine with configurable backoff strategies
+ *
+ * @example
+ * ```typescript
+ * const retry = new RetryEngine();
+ *
+ * // Simple retry
+ * const result = await retry.execute(async () => {
+ *   return await fetchData();
+ * });
+ *
+ * // With custom config
+ * const result = await retry.execute(
+ *   async () => fetchData(),
+ *   {
+ *     maxAttempts: 5,
+ *     backoff: 'exponential_jitter',
+ *     initialDelay: 100,
+ *     maxDelay: 5000
+ *   }
+ * );
+ *
+ * // With hooks
+ * const result = await retry.execute(
+ *   async () => fetchData(),
+ *   { maxAttempts: 3 },
+ *   {
+ *     onError: (err, attempt) => console.log(`Attempt ${attempt} failed: ${err.message}`),
+ *     onSuccess: (result) => console.log('Success!', result)
+ *   }
+ * );
+ * ```
+ */
+export declare class RetryEngine extends EventEmitter {
+    private config;
+    private budgetState;
+    private activeRetries;
+    private lastDelay;
+    constructor(config?: RetryEngineConfig);
+    /**
+     * Execute a function with retry logic
+     */
+    execute<T>(fn: () => T | Promise<T>, config?: RetryConfig, hooks?: RetryHooks<T>): Promise<RetryResult<T>>;
+    /**
+     * Execute with a preset strategy
+     */
+    executeWithStrategy<T>(fn: () => T | Promise<T>, strategy: BackoffStrategy, hooks?: RetryHooks<T>): Promise<RetryResult<T>>;
+    /**
+     * Create a retryable version of a function
+     */
+    retryable<T extends (...args: unknown[]) => unknown>(fn: T, config?: RetryConfig): (...args: Parameters<T>) => Promise<RetryResult<ReturnType<T>>>;
+    /**
+     * Calculate delay for next attempt
+     */
+    calculateDelay(attempt: number, lastDelay: number, config: RetryConfig): number;
+    /**
+     * Get delay for a specific strategy and attempt
+     */
+    getDelay(strategy: BackoffStrategy, attempt: number, config?: Partial<RetryConfig>): number;
+    /**
+     * Check if retry is allowed by budget
+     */
+    checkBudget(name?: string): boolean;
+    /**
+     * Get budget state
+     */
+    getBudgetState(name?: string): RetryBudgetState;
+    /**
+     * Reset budget
+     */
+    resetBudget(name?: string): void;
+    /**
+     * Reset all budgets
+     */
+    resetAllBudgets(): void;
+    /**
+     * Get default configuration
+     */
+    getDefaults(): Required<RetryConfig>;
+    /**
+     * Update default configuration
+     */
+    setDefaults(config: Partial<RetryConfig>): void;
+    /**
+     * Get current active retries count
+     */
+    getActiveRetries(): number;
+    /**
+     * Create an abort controller for retries
+     */
+    createAbortController(): AbortController;
+    /**
+     * Wait for a specified delay
+     */
+    delay(ms: number): Promise<void>;
+    /**
+     * Shutdown the engine
+     */
+    shutdown(): void;
+    private mergeConfig;
+    private addJitter;
+    private sleep;
+    private executeWithTimeout;
+    private refreshBudget;
+    private recordBudgetSuccess;
+    private recordBudgetFailure;
+}
+//# sourceMappingURL=RetryEngine.d.ts.map

package/dist/v10/recovery/RetryEngine.d.ts.map

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