@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

package/build/src/utils/async.utils.js

@@ -0,0 +1,641 @@
+"use strict";
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreakerState = exports.CircuitBreakerOpenError = void 0;
+exports.sleep = sleep;
+exports.debounce = debounce;
+exports.throttle = throttle;
+exports.retry = retry;
+exports.withTimeout = withTimeout;
+exports.runInBatches = runInBatches;
+exports.singletonAsync = singletonAsync;
+exports.settleAll = settleAll;
+exports.createTaskQueue = createTaskQueue;
+exports.runInSeries = runInSeries;
+exports.memoizeAsync = memoizeAsync;
+exports.abortable = abortable;
+exports.createDeferred = createDeferred;
+exports.waterfall = waterfall;
+exports.rateLimit = rateLimit;
+exports.circuitBreaker = circuitBreaker;
+exports.runWithConcurrency = runWithConcurrency;
+const logger_utils_1 = require("./logger.utils");
+/**
+ * Delays execution for a specified number of milliseconds.
+ *
+ * @param {number} ms - The number of milliseconds to sleep.
+ * @returns {Promise<void>} A Promise that resolves after the given time.
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Creates a debounced version of a function that delays its execution.
+ * Provides `.cancel()` and `.flush()` methods.
+ *
+ * @template T
+ * @param {T} fn - The function to debounce.
+ * @param {number} delay - Delay in milliseconds.
+ * @returns {T & { cancel: () => void; flush: () => void }} A debounced function.
+ */
+function debounce(fn, delay) {
+    let timer = null;
+    let pendingArgs = null;
+    function debounced(...args) {
+        pendingArgs = args;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            fn(...pendingArgs);
+            timer = null;
+        }, delay);
+    }
+    debounced.cancel = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        pendingArgs = null;
+    };
+    debounced.flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            fn(...pendingArgs);
+            timer = null;
+            pendingArgs = null;
+        }
+    };
+    return debounced;
+}
+/**
+ * Creates a throttled version of a function that limits its execution rate.
+ * Allows control over leading/trailing invocation.
+ *
+ * @template T
+ * @param {T} fn - The function to throttle.
+ * @param {number} limit - Minimum time between calls in milliseconds.
+ * @param {{ leading?: boolean, trailing?: boolean }} [opts] - Options for leading/trailing edge throttling.
+ * @returns {(...args: Parameters<T>) => void} A throttled function.
+ */
+function throttle(fn, limit, opts = {
+    leading: true,
+    trailing: false
+}) {
+    let lastCall = 0;
+    let timer = null;
+    let savedArgs = null;
+    return function (...args) {
+        const now = Date.now();
+        const { leading = true, trailing = false } = opts;
+        if (!lastCall && !leading)
+            lastCall = now;
+        const remaining = limit - (now - lastCall);
+        if (remaining <= 0) {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            lastCall = now;
+            fn(...args);
+        }
+        else if (trailing) {
+            savedArgs = args;
+            if (!timer) {
+                timer = setTimeout(() => {
+                    lastCall = leading ? Date.now() : 0;
+                    timer = null;
+                    if (savedArgs)
+                        fn(...savedArgs);
+                }, remaining);
+            }
+        }
+    };
+}
+/**
+ * Retries an asynchronous function a given number of times with optional delay/backoff.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn - The async function to retry.
+ * @param {number} [retries=3] - Number of retry attempts.
+ * @param {number} [delay=500] - Delay in milliseconds between retries.
+ * @param {boolean} [backoff=false] - Use exponential backoff between attempts.
+ * @param {(error: unknown, attempt: number) => void} [onRetry] - Callback for each retry attempt.
+ * @returns {Promise<T>} The result of the async function if successful.
+ * @throws {*} The last encountered error if all retries fail.
+ */
+async function retry(fn, retries = 3, delay = 500, backoff = false, onRetry) {
+    for (let i = 0; i < retries; i++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (i === retries - 1)
+                throw e;
+            if (onRetry)
+                onRetry(e, i + 1);
+            await sleep(backoff ? delay * Math.pow(2, i) : delay);
+        }
+    }
+    throw new Error('Retry failed'); // should never reach here
+}
+/**
+ * Wraps a promise and rejects it if it doesn't resolve within the specified timeout.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The original promise.
+ * @param {number} ms - Timeout in milliseconds.
+ * @param {string} [message="Operation timed out"] - Optional timeout message.
+ * @returns {Promise<T>} A promise that resolves or rejects within the timeout.
+ */
+function withTimeout(promise, ms, message = 'Operation timed out') {
+    return new Promise((resolve, reject) => {
+        const timeoutHandle = setTimeout(() => reject(new Error(message)), ms);
+        promise
+            .then(result => {
+            clearTimeout(timeoutHandle);
+            resolve(result);
+        })
+            .catch(err => {
+            clearTimeout(timeoutHandle);
+            reject(err);
+        });
+    });
+}
+/**
+ * Executes async tasks in true batches.
+ * Each batch runs in parallel, but batches run sequentially.
+ * All tasks in a batch start at the same time, next batch waits for full completion.
+ * NOTE: For more granular concurrency, use a "queue" or "pooled" approach.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks - An array of functions that return Promises.
+ * @param {number} limit - Number of tasks to run in parallel per batch.
+ * @returns {Promise<T[]>} A promise that resolves to an array of resolved values.
+ */
+async function runInBatches(tasks, limit) {
+    const results = [];
+    for (let i = 0; i < tasks.length; i += limit) {
+        const batch = tasks.slice(i, i + limit);
+        const batchResults = await Promise.all(batch.map(fn => fn()));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Wraps a function and ensures it is only called once at a time.
+ * Calls made while one is in progress will wait for the same Promise.
+ * Optionally, new calls can be dropped while in progress (drop=true).
+ *
+ * @template TArgs
+ * @template TResult
+ * @param {(...args: TArgs) => Promise<TResult>} fn - The async function to wrap.
+ * @param {boolean} [drop=false] - If true, new calls while one is pending are rejected.
+ * @returns {(...args: TArgs) => Promise<TResult>} A wrapped function with singleton behavior.
+ */
+function singletonAsync(fn, drop = false) {
+    let promise = null;
+    return async (...args) => {
+        if (!promise) {
+            promise = fn(...args).finally(() => {
+                promise = null;
+            });
+        }
+        else if (drop) {
+            return Promise.reject(new Error('Busy: function already running'));
+        }
+        return promise;
+    };
+}
+/**
+ * Resolves a list of async tasks in parallel, returning both resolved and rejected results.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.
+ * @returns {Promise<PromiseSettledResult<T>[]>} Results including status and value/reason.
+ */
+async function settleAll(tasks) {
+    return Promise.allSettled(tasks.map(task => task()));
+}
+/**
+ * A simple task queue that executes async tasks with a concurrency limit.
+ * Exposes pause, resume, and queue length getters.
+ *
+ * @param {number} limit - Maximum number of concurrent tasks.
+ * @returns {function & { pause: () => void, resume: () => void, length: number, isPaused: boolean }}
+ *   Enqueue function plus queue controls.
+ */
+function createTaskQueue(limit) {
+    const queue = [];
+    let activeCount = 0;
+    let paused = false;
+    const state = {
+        /**
+         * Pause task processing.
+         */
+        pause() {
+            paused = true;
+        },
+        /**
+         * Resume task processing.
+         */
+        resume() {
+            paused = false;
+            next();
+        },
+        /**
+         * The current length of the queue.
+         * @type {number}
+         */
+        get length() {
+            return queue.length;
+        },
+        /**
+         * Whether the queue is currently paused.
+         * @type {boolean}
+         */
+        get isPaused() {
+            return paused;
+        }
+    };
+    const next = () => {
+        if (paused || queue.length === 0 || activeCount >= limit)
+            return;
+        const task = queue.shift();
+        activeCount++;
+        task().finally(() => {
+            activeCount--;
+            next();
+        });
+    };
+    /**
+     * Enqueues a new async task to the queue.
+     *
+     * @template T
+     * @param {() => Promise<T>} taskFn - The async task function.
+     * @returns {Promise<T>} Promise resolving when task completes.
+     */
+    const enqueue = async function (taskFn) {
+        return new Promise((resolve, reject) => {
+            queue.push(async () => {
+                try {
+                    const result = await taskFn();
+                    resolve(result);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+            next();
+        });
+    };
+    enqueue.pause = state.pause;
+    enqueue.resume = state.resume;
+    Object.defineProperty(enqueue, 'length', {
+        get: () => queue.length
+    });
+    Object.defineProperty(enqueue, 'isPaused', {
+        get: () => paused
+    });
+    return enqueue;
+}
+/**
+ * Executes async functions sequentially and collects results.
+ * Useful when order matters or tasks depend on each other.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.
+ * @returns {Promise<T[]>} Array of resolved values.
+ */
+async function runInSeries(tasks) {
+    const results = [];
+    for (const task of tasks) {
+        results.push(await task());
+    }
+    return results;
+}
+/**
+ * Memoizes an async function, caching results for repeated calls with identical arguments.
+ * Optional TTL (time-to-live) for cached entries.
+ *
+ * @template T Function return type
+ * @template Args Function arguments types
+ * @param {(...args: Args) => Promise<T>} fn - The async function to memoize
+ * @param {object} [options] - Memoization options
+ * @param {number} [options.ttl] - Cache TTL in milliseconds (optional)
+ * @param {(args: Args) => string} [options.keyFn] - Custom key generator function
+ * @returns {(...args: Args) => Promise<T>} Memoized function
+ */
+function memoizeAsync(fn, options = {}) {
+    const cache = new Map();
+    const { ttl, keyFn = JSON.stringify } = options;
+    return async function (...args) {
+        const key = keyFn(args);
+        const cached = cache.get(key);
+        if (cached && (!ttl || Date.now() < cached.expires)) {
+            return cached.value;
+        }
+        const result = await fn(...args);
+        cache.set(key, {
+            value: result,
+            expires: ttl ? Date.now() + ttl : Infinity
+        });
+        return result;
+    };
+}
+/**
+ * Creates an abortable version of a promise that can be cancelled using an AbortController.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The promise to make abortable
+ * @param {AbortSignal} signal - AbortSignal from AbortController
+ * @param {any} [abortValue] - Value to use when rejecting on abort
+ * @returns {Promise<T>} Promise that rejects if the signal is aborted
+ */
+function abortable(promise, signal, abortValue = new Error('Operation aborted')) {
+    if (signal.aborted) {
+        return Promise.reject(abortValue);
+    }
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            const abort = () => reject(abortValue);
+            signal.addEventListener('abort', abort, { once: true });
+            promise.finally(() => signal.removeEventListener('abort', abort));
+        })
+    ]);
+}
+/**
+ * Creates a promise with external resolve/reject functions.
+ * Useful for creating promises that can be resolved or rejected from outside.
+ *
+ * @template T
+ * @returns {[Promise<T>, (value: T | PromiseLike<T>) => void, (reason?: any) => void]}
+ *   Tuple of [promise, resolve, reject]
+ */
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return [promise, resolve, reject];
+}
+/**
+ * Chains a series of async functions, passing the result of each to the next.
+ * Similar to function composition but for async functions.
+ *
+ * @template T
+ * @param {Array<(input: any) => Promise<any>>} fns - Array of async functions to compose
+ * @returns {(input: any) => Promise<T>} Composed function
+ */
+function waterfall(fns) {
+    return async (initialValue) => {
+        return fns.reduce(async (acc, fn) => fn(await acc), Promise.resolve(initialValue));
+    };
+}
+/**
+ * Creates a rate limiter that ensures functions aren't called more than
+ * a specified number of times per interval.
+ *
+ * @template T
+ * @param {(...args: any[]) => Promise<T>} fn - Function to rate limit
+ * @param {number} maxCalls - Maximum calls allowed per interval
+ * @param {number} interval - Time interval in milliseconds
+ * @returns {(...args: any[]) => Promise<T>} Rate limited function
+ */
+function rateLimit(fn, maxCalls, interval) {
+    const calls = [];
+    return async function (...args) {
+        const now = Date.now();
+        calls.splice(0, calls.length, ...calls.filter(time => now - time < interval));
+        if (calls.length >= maxCalls) {
+            const oldestCall = calls[0];
+            const delay = interval - (now - oldestCall);
+            await sleep(Math.max(1, delay));
+            // Remove potentially stale entries after sleep
+            const currentTime = Date.now();
+            calls.splice(0, calls.length, ...calls.filter(time => currentTime - time < interval));
+            // If still at limit after sleep, wait for another cycle
+            if (calls.length >= maxCalls) {
+                const nextDelay = interval - (currentTime - calls[0]);
+                await sleep(Math.max(1, nextDelay));
+                calls.splice(0, calls.length, ...calls.filter(time => Date.now() - time < interval));
+            }
+        }
+        calls.push(Date.now());
+        return fn(...args);
+    };
+}
+/**
+ * Circuit breaker pattern implementation for protecting against cascading failures.
+ * Tracks failures and prevents calling the function when too many failures occur.
+ *
+ * @param fn - Function to protect with circuit breaker
+ * @param options - Circuit breaker options
+ * @returns Function wrapped with circuit breaker logic
+ *
+ * @example
+ * ```typescript
+ * const protectedFetch = circuitBreaker(
+ *   async (url) => {
+ *     const response = await fetch(url);
+ *     if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+ *     return response.json();
+ *   },
+ *   {
+ *     failureThreshold: 3,
+ *     resetTimeout: 30000,
+ *     onOpen: () => console.log('Circuit breaker opened'),
+ *     onClose: () => console.log('Circuit breaker closed')
+ *   }
+ * );
+ *
+ * // Will throw CircuitBreakerOpenError after failureThreshold consecutive failures
+ * try {
+ *   const data = await protectedFetch('https://api.example.com');
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerOpenError) {
+ *     console.log('Service is currently unavailable, please try again later');
+ *   }
+ * }
+ * ```
+ */
+class CircuitBreakerOpenError extends Error {
+    constructor(message = 'Circuit breaker is open') {
+        super(message);
+        this.name = 'CircuitBreakerOpenError';
+    }
+}
+exports.CircuitBreakerOpenError = CircuitBreakerOpenError;
+/**
+ * Circuit breaker states
+ */
+var CircuitBreakerState;
+(function (CircuitBreakerState) {
+    CircuitBreakerState["CLOSED"] = "CLOSED";
+    CircuitBreakerState["OPEN"] = "OPEN";
+    CircuitBreakerState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitBreakerState || (exports.CircuitBreakerState = CircuitBreakerState = {}));
+function circuitBreaker(fn, options = {}) {
+    const { failureThreshold = 5, resetTimeout = 10000, successThreshold = 1, onOpen, onClose, onHalfOpen } = options;
+    let state = CircuitBreakerState.CLOSED;
+    let failureCount = 0;
+    let successCount = 0;
+    let nextAttempt = Date.now();
+    return async function (...args) {
+        if (state === CircuitBreakerState.OPEN) {
+            if (Date.now() < nextAttempt) {
+                throw new CircuitBreakerOpenError();
+            }
+            // Move to half-open state
+            state = CircuitBreakerState.HALF_OPEN;
+            if (onHalfOpen)
+                onHalfOpen();
+        }
+        try {
+            const result = await fn(...args);
+            // On success in half-open state
+            if (state === CircuitBreakerState.HALF_OPEN) {
+                successCount++;
+                if (successCount >= successThreshold) {
+                    successCount = 0;
+                    failureCount = 0;
+                    state = CircuitBreakerState.CLOSED;
+                    if (onClose)
+                        onClose();
+                }
+            }
+            else {
+                // Reset failure count on success in closed state
+                failureCount = 0;
+            }
+            return result;
+        }
+        catch (error) {
+            // Track failures
+            failureCount++;
+            // Check if we need to open the circuit
+            if ((state === CircuitBreakerState.CLOSED || state === CircuitBreakerState.HALF_OPEN) &&
+                failureCount >= failureThreshold) {
+                state = CircuitBreakerState.OPEN;
+                nextAttempt = Date.now() + resetTimeout;
+                if (onOpen)
+                    onOpen();
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Run multiple async tasks with concurrency control.
+ *
+ * @param tasks - Array of async tasks to run
+ * @param options - Concurrency options
+ * @returns Promise that resolves when all tasks are complete
+ *
+ * @example
+ * ```typescript
+ *  const urls = ['https://example.com/1', 'https://example.com/2', many more ];
+ *
+ * // Process up to 5 requests at a time, with progress reporting
+ * const results = await runWithConcurrency(
+ *   urls.map(url => () => fetch(url).then(res => res.json())),
+ *   {
+ *     concurrency: 5,
+ *     onProgress: (completed, total) => {
+ *       console.log(`Progress: ${completed}/${total}`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+async function runWithConcurrency(tasks, options = {}) {
+    const { concurrency = 3, onProgress, signal } = options;
+    const results = [];
+    const totalTasks = tasks.length;
+    let completed = 0;
+    // If no tasks, return empty array
+    if (totalTasks === 0)
+        return results;
+    // Check if execution is already aborted
+    if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+        throw new Error('Aborted');
+    }
+    return new Promise((resolve, reject) => {
+        let taskIndex = 0;
+        // Process next task function
+        const processNext = async () => {
+            // Get current task index and increment
+            const currentTaskIndex = taskIndex++;
+            // Skip if we've processed all tasks
+            if (currentTaskIndex >= totalTasks)
+                return;
+            try {
+                // Run the task
+                const result = await tasks[currentTaskIndex]();
+                // Check if aborted during task execution
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                    reject(new Error('Aborted'));
+                    return;
+                }
+                // Store result and update counters
+                results[currentTaskIndex] = result;
+                completed++;
+                // Call progress callback if provided
+                if (onProgress) {
+                    try {
+                        onProgress(completed, totalTasks);
+                    }
+                    catch (err) {
+                        (0, logger_utils_1.getLogger)().error({ err }, 'Error in onProgress callback');
+                    }
+                }
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            // Check if all tasks are completed
+            if (completed === totalTasks) {
+                resolve(results);
+                return;
+            }
+            // Process next task
+            processNext();
+        };
+        // Start initial batch of tasks
+        const initialBatch = Math.min(concurrency, totalTasks);
+        for (let i = 0; i < initialBatch; i++) {
+            processNext();
+        }
+        // Set up abort handler
+        if (signal) {
+            signal.addEventListener('abort', () => {
+                reject(new Error('Aborted'));
+            }, { once: true });
+        }
+    });
+}
+//# sourceMappingURL=async.utils.js.map