@juspay/neurolink 9.1.0 → 9.2.0

package/dist/utils/async/retry.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Retry Utilities
+ *
+ * Provides retry logic with exponential backoff for resilient async operations.
+ */
+/**
+ * Configuration options for retry operations.
+ */
+export interface RetryOptions {
+    /**
+     * Maximum number of retry attempts (not including the initial attempt).
+     * @default 3
+     */
+    maxRetries: number;
+    /**
+     * Initial delay between retries in milliseconds.
+     * @default 1000
+     */
+    baseDelayMs: number;
+    /**
+     * Maximum delay cap in milliseconds.
+     * @default 30000
+     */
+    maxDelayMs: number;
+    /**
+     * Multiplier for exponential backoff.
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Function to determine if a retry should be attempted.
+     * Return false to stop retrying immediately.
+     */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    /**
+     * Callback invoked before each retry attempt.
+     * Useful for logging or metrics.
+     */
+    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
+}
+/**
+ * Default retry configuration.
+ */
+export declare const DEFAULT_RETRY_OPTIONS: RetryOptions;
+/**
+ * Calculate exponential backoff delay with optional jitter.
+ *
+ * Uses the formula: min(baseDelay * 2^(attempt-1) + jitter, maxDelay)
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param maxDelayMs - Maximum delay cap in milliseconds
+ * @param addJitter - Whether to add random jitter (default: true)
+ * @returns Calculated delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Without jitter
+ * calculateBackoff(1, 1000, 30000, false); // 1000ms
+ * calculateBackoff(2, 1000, 30000, false); // 2000ms
+ * calculateBackoff(3, 1000, 30000, false); // 4000ms
+ *
+ * // With jitter (adds up to 10% random delay)
+ * calculateBackoff(3, 1000, 30000, true); // ~4000-4400ms
+ * ```
+ */
+export declare function calculateBackoff(attempt: number, baseDelayMs: number, maxDelayMs: number, addJitter?: boolean): number;
+/**
+ * Error thrown when all retry attempts are exhausted.
+ */
+export declare class RetryExhaustedError extends Error {
+    readonly attempts: number;
+    readonly lastError: Error;
+    /**
+     * Creates a new RetryExhaustedError.
+     *
+     * @param message - Error message
+     * @param attempts - Total number of attempts made
+     * @param lastError - The last error that caused the final failure
+     */
+    constructor(message: string, attempts: number, lastError: Error);
+}
+/**
+ * Retry an async function with exponential backoff.
+ *
+ * Executes the provided function and retries on failure according to
+ * the specified options. Uses exponential backoff between retries.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry configuration (merged with defaults)
+ * @returns Promise that resolves with the function result
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const data = await retry(() => fetchFromAPI());
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const data = await retry(
+ *   () => fetchFromAPI(),
+ *   {
+ *     maxRetries: 5,
+ *     baseDelayMs: 500,
+ *     maxDelayMs: 10000,
+ *     onRetry: (err, attempt, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms: ${err.message}`);
+ *     },
+ *     shouldRetry: (err) => {
+ *       // Only retry on network errors
+ *       return err.name === 'NetworkError';
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Create a retry wrapper with pre-configured options.
+ *
+ * Useful for creating reusable retry strategies.
+ *
+ * @param defaultOptions - Default retry options for the wrapper
+ * @returns A retry function with the specified defaults
+ *
+ * @example
+ * ```typescript
+ * const apiRetry = createRetry({
+ *   maxRetries: 5,
+ *   baseDelayMs: 100,
+ *   onRetry: (err, attempt) => logger.warn(`API retry ${attempt}`)
+ * });
+ *
+ * // Use the configured retry
+ * const data = await apiRetry(() => fetchFromAPI());
+ * ```
+ */
+export declare function createRetry(defaultOptions: Partial<RetryOptions>): <T>(fn: () => Promise<T>, overrideOptions?: Partial<RetryOptions>) => Promise<T>;

package/dist/utils/async/retry.js

@@ -0,0 +1,171 @@
+/**
+ * Retry Utilities
+ *
+ * Provides retry logic with exponential backoff for resilient async operations.
+ */
+import { delay } from "./delay.js";
+/**
+ * Default retry configuration.
+ */
+export const DEFAULT_RETRY_OPTIONS = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+};
+/**
+ * Calculate exponential backoff delay with optional jitter.
+ *
+ * Uses the formula: min(baseDelay * 2^(attempt-1) + jitter, maxDelay)
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param maxDelayMs - Maximum delay cap in milliseconds
+ * @param addJitter - Whether to add random jitter (default: true)
+ * @returns Calculated delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Without jitter
+ * calculateBackoff(1, 1000, 30000, false); // 1000ms
+ * calculateBackoff(2, 1000, 30000, false); // 2000ms
+ * calculateBackoff(3, 1000, 30000, false); // 4000ms
+ *
+ * // With jitter (adds up to 10% random delay)
+ * calculateBackoff(3, 1000, 30000, true); // ~4000-4400ms
+ * ```
+ */
+export function calculateBackoff(attempt, baseDelayMs, maxDelayMs, addJitter = true) {
+    const exponentialDelay = baseDelayMs * 2 ** (attempt - 1);
+    if (addJitter) {
+        // Add up to 10% jitter to prevent thundering herd
+        const jitter = Math.random() * 0.1 * exponentialDelay;
+        return Math.min(exponentialDelay + jitter, maxDelayMs);
+    }
+    return Math.min(exponentialDelay, maxDelayMs);
+}
+/**
+ * Error thrown when all retry attempts are exhausted.
+ */
+export class RetryExhaustedError extends Error {
+    attempts;
+    lastError;
+    /**
+     * Creates a new RetryExhaustedError.
+     *
+     * @param message - Error message
+     * @param attempts - Total number of attempts made
+     * @param lastError - The last error that caused the final failure
+     */
+    constructor(message, attempts, lastError) {
+        super(message);
+        this.attempts = attempts;
+        this.lastError = lastError;
+        this.name = "RetryExhaustedError";
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, RetryExhaustedError);
+        }
+    }
+}
+/**
+ * Retry an async function with exponential backoff.
+ *
+ * Executes the provided function and retries on failure according to
+ * the specified options. Uses exponential backoff between retries.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry configuration (merged with defaults)
+ * @returns Promise that resolves with the function result
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const data = await retry(() => fetchFromAPI());
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const data = await retry(
+ *   () => fetchFromAPI(),
+ *   {
+ *     maxRetries: 5,
+ *     baseDelayMs: 500,
+ *     maxDelayMs: 10000,
+ *     onRetry: (err, attempt, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms: ${err.message}`);
+ *     },
+ *     shouldRetry: (err) => {
+ *       // Only retry on network errors
+ *       return err.name === 'NetworkError';
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function retry(fn, options = {}) {
+    const config = {
+        ...DEFAULT_RETRY_OPTIONS,
+        ...options,
+    };
+    const { maxRetries, baseDelayMs, maxDelayMs, backoffMultiplier = 2, shouldRetry = () => true, onRetry, } = config;
+    let lastError = new Error("Retry failed");
+    let currentDelay = baseDelayMs;
+    // Total attempts = initial attempt + retries
+    const totalAttempts = maxRetries + 1;
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            lastError = err;
+            // Check if we've exhausted all retries
+            if (attempt >= totalAttempts) {
+                throw new RetryExhaustedError(`All ${totalAttempts} retry attempts exhausted`, totalAttempts, err);
+            }
+            // Check if we should retry this error
+            if (!shouldRetry(err, attempt)) {
+                throw err;
+            }
+            // Calculate delay with exponential backoff (capped at maxDelay)
+            const delayMs = Math.min(currentDelay, maxDelayMs);
+            // Notify about retry
+            if (onRetry) {
+                onRetry(err, attempt, delayMs);
+            }
+            // Wait before next attempt
+            await delay(delayMs);
+            // Increase delay for next iteration
+            currentDelay = currentDelay * backoffMultiplier;
+        }
+    }
+    // This should never be reached, but TypeScript needs it
+    throw new RetryExhaustedError(`All ${totalAttempts} retry attempts exhausted`, totalAttempts, lastError || new Error("Unknown retry failure"));
+}
+/**
+ * Create a retry wrapper with pre-configured options.
+ *
+ * Useful for creating reusable retry strategies.
+ *
+ * @param defaultOptions - Default retry options for the wrapper
+ * @returns A retry function with the specified defaults
+ *
+ * @example
+ * ```typescript
+ * const apiRetry = createRetry({
+ *   maxRetries: 5,
+ *   baseDelayMs: 100,
+ *   onRetry: (err, attempt) => logger.warn(`API retry ${attempt}`)
+ * });
+ *
+ * // Use the configured retry
+ * const data = await apiRetry(() => fetchFromAPI());
+ * ```
+ */
+export function createRetry(defaultOptions) {
+    return (fn, overrideOptions) => {
+        return retry(fn, { ...defaultOptions, ...overrideOptions });
+    };
+}

package/dist/utils/async/withTimeout.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Timeout Utilities
+ *
+ * Wrapper functions for adding timeout protection to async operations.
+ */
+/**
+ * Error thrown when an operation times out.
+ */
+export declare class TimeoutError extends Error {
+    readonly timeoutMs: number;
+    /**
+     * Creates a new TimeoutError.
+     *
+     * @param message - Error message describing the timeout
+     * @param timeoutMs - The timeout duration that was exceeded
+     */
+    constructor(message: string, timeoutMs: number);
+}
+/**
+ * Execute a promise with timeout protection.
+ *
+ * Wraps a promise and rejects with a TimeoutError if the operation
+ * takes longer than the specified duration.
+ *
+ * @param promise - The promise to wrap with timeout
+ * @param ms - Maximum time to wait in milliseconds
+ * @param message - Optional custom error message for timeout
+ * @returns Promise that resolves with the result or rejects on timeout
+ * @throws {TimeoutError} If the operation exceeds the timeout duration
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   fetchData(),
+ *   5000,
+ *   'Data fetch timed out'
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = await withTimeout(slowOperation(), 3000);
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     console.log(`Timed out after ${error.timeoutMs}ms`);
+ *   }
+ * }
+ * ```
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+/**
+ * Execute a function with timeout protection.
+ *
+ * Alternative signature that accepts a function instead of a promise,
+ * useful when you want to delay starting the operation.
+ *
+ * @param fn - Async function to execute
+ * @param ms - Maximum time to wait in milliseconds
+ * @param message - Optional custom error message for timeout
+ * @returns Promise that resolves with the function result or rejects on timeout
+ * @throws {TimeoutError} If the operation exceeds the timeout duration
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeoutFn(
+ *   () => fetchData(),
+ *   5000,
+ *   'Data fetch timed out'
+ * );
+ * ```
+ */
+export declare function withTimeoutFn<T>(fn: () => Promise<T>, ms: number, message?: string): Promise<T>;

package/dist/utils/async/withTimeout.js

@@ -0,0 +1,96 @@
+/**
+ * Timeout Utilities
+ *
+ * Wrapper functions for adding timeout protection to async operations.
+ */
+/**
+ * Error thrown when an operation times out.
+ */
+export class TimeoutError extends Error {
+    timeoutMs;
+    /**
+     * Creates a new TimeoutError.
+     *
+     * @param message - Error message describing the timeout
+     * @param timeoutMs - The timeout duration that was exceeded
+     */
+    constructor(message, timeoutMs) {
+        super(message);
+        this.timeoutMs = timeoutMs;
+        this.name = "TimeoutError";
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TimeoutError);
+        }
+    }
+}
+/**
+ * Execute a promise with timeout protection.
+ *
+ * Wraps a promise and rejects with a TimeoutError if the operation
+ * takes longer than the specified duration.
+ *
+ * @param promise - The promise to wrap with timeout
+ * @param ms - Maximum time to wait in milliseconds
+ * @param message - Optional custom error message for timeout
+ * @returns Promise that resolves with the result or rejects on timeout
+ * @throws {TimeoutError} If the operation exceeds the timeout duration
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   fetchData(),
+ *   5000,
+ *   'Data fetch timed out'
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const data = await withTimeout(slowOperation(), 3000);
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     console.log(`Timed out after ${error.timeoutMs}ms`);
+ *   }
+ * }
+ * ```
+ */
+export async function withTimeout(promise, ms, message) {
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new TimeoutError(message || `Operation timed out after ${ms}ms`, ms));
+        }, ms);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Execute a function with timeout protection.
+ *
+ * Alternative signature that accepts a function instead of a promise,
+ * useful when you want to delay starting the operation.
+ *
+ * @param fn - Async function to execute
+ * @param ms - Maximum time to wait in milliseconds
+ * @param message - Optional custom error message for timeout
+ * @returns Promise that resolves with the function result or rejects on timeout
+ * @throws {TimeoutError} If the operation exceeds the timeout duration
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeoutFn(
+ *   () => fetchData(),
+ *   5000,
+ *   'Data fetch timed out'
+ * );
+ * ```
+ */
+export async function withTimeoutFn(fn, ms, message) {
+    return withTimeout(fn(), ms, message);
+}