@catbee/utils 0.0.1 → 0.0.2

package/build/esm/utils/async.utils.js

@@ -76,9 +76,9 @@ var __values = (this && this.__values) || function(o) {
  * @param {number} ms - The number of milliseconds to sleep.
  * @returns {Promise<void>} A Promise that resolves after the given time.
  */
-export var sleep = function (ms) {
+export function sleep(ms) {
     return new Promise(function (resolve) { return setTimeout(resolve, ms); });
-};
+}
 /**
  * Creates a debounced version of a function that delays its execution.
  * Provides `.cancel()` and `.flush()` methods.
@@ -471,4 +471,162 @@ export function runInSeries(tasks) {
         });
     });
 }
+/**
+ * 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
+ */
+export function memoizeAsync(fn, options) {
+    if (options === void 0) { options = {}; }
+    var cache = new Map();
+    var ttl = options.ttl, _a = options.keyFn, keyFn = _a === void 0 ? JSON.stringify : _a;
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return __awaiter(this, void 0, void 0, function () {
+            var key, cached, result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        key = keyFn(args);
+                        cached = cache.get(key);
+                        if (cached && (!ttl || Date.now() < cached.expires)) {
+                            return [2 /*return*/, cached.value];
+                        }
+                        return [4 /*yield*/, fn.apply(void 0, __spreadArray([], __read(args), false))];
+                    case 1:
+                        result = _a.sent();
+                        cache.set(key, {
+                            value: result,
+                            expires: ttl ? Date.now() + ttl : Infinity,
+                        });
+                        return [2 /*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
+ */
+export function abortable(promise, signal, abortValue) {
+    if (abortValue === void 0) { abortValue = new Error("Operation aborted"); }
+    if (signal.aborted) {
+        return Promise.reject(abortValue);
+    }
+    return Promise.race([
+        promise,
+        new Promise(function (_, reject) {
+            var abort = function () { return reject(abortValue); };
+            signal.addEventListener("abort", abort, { once: true });
+            promise.finally(function () { return 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]
+ */
+export function createDeferred() {
+    var resolve;
+    var reject;
+    var promise = new Promise(function (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
+ */
+export function waterfall(fns) {
+    var _this = this;
+    return function (initialValue) { return __awaiter(_this, void 0, void 0, function () {
+        var _this = this;
+        return __generator(this, function (_a) {
+            return [2 /*return*/, fns.reduce(function (acc, fn) { return __awaiter(_this, void 0, void 0, function () { var _a; return __generator(this, function (_b) {
+                    switch (_b.label) {
+                        case 0:
+                            _a = fn;
+                            return [4 /*yield*/, acc];
+                        case 1: return [2 /*return*/, _a.apply(void 0, [_b.sent()])];
+                    }
+                }); }); }, 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
+ */
+export function rateLimit(fn, maxCalls, interval) {
+    var calls = [];
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return __awaiter(this, void 0, void 0, function () {
+            var now, oldestCall, delay, currentTime_1, nextDelay;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        now = Date.now();
+                        calls.splice.apply(calls, __spreadArray([0,
+                            calls.length], __read(calls.filter(function (time) { return now - time < interval; })), false));
+                        if (!(calls.length >= maxCalls)) return [3 /*break*/, 3];
+                        oldestCall = calls[0];
+                        delay = interval - (now - oldestCall);
+                        return [4 /*yield*/, sleep(Math.max(1, delay))];
+                    case 1:
+                        _a.sent();
+                        currentTime_1 = Date.now();
+                        calls.splice.apply(calls, __spreadArray([0,
+                            calls.length], __read(calls.filter(function (time) { return currentTime_1 - time < interval; })), false));
+                        if (!(calls.length >= maxCalls)) return [3 /*break*/, 3];
+                        nextDelay = interval - (currentTime_1 - calls[0]);
+                        return [4 /*yield*/, sleep(Math.max(1, nextDelay))];
+                    case 2:
+                        _a.sent();
+                        calls.splice.apply(calls, __spreadArray([0,
+                            calls.length], __read(calls.filter(function (time) { return Date.now() - time < interval; })), false));
+                        _a.label = 3;
+                    case 3:
+                        calls.push(Date.now());
+                        return [2 /*return*/, fn.apply(void 0, __spreadArray([], __read(args), false))];
+                }
+            });
+        });
+    };
+}
 //# sourceMappingURL=async.utils.js.map

package/build/esm/utils/async.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"async.utils.js","sourceRoot":"","sources":["../../../src/utils/async.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Delays execution for a specified number of milliseconds.\n *\n * @param {number} ms - The number of milliseconds to sleep.\n * @returns {Promise<void>} A Promise that resolves after the given time.\n */\nexport const sleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Creates a debounced version of a function that delays its execution.\n * Provides `.cancel()` and `.flush()` methods.\n *\n * @template T\n * @param {T} fn - The function to debounce.\n * @param {number} delay - Delay in milliseconds.\n * @returns {T & { cancel: () => void; flush: () => void }} A debounced function.\n */\nexport function debounce<T extends (...args: any[]) => void>(\n  fn: T,\n  delay: number,\n) {\n  let timer: NodeJS.Timeout | null = null;\n  let pendingArgs: Parameters<T> | null = null;\n\n  function debounced(...args: Parameters<T>) {\n    pendingArgs = args;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(() => {\n      fn(...(pendingArgs as Parameters<T>));\n      timer = null;\n    }, delay);\n  }\n\n  debounced.cancel = () => {\n    if (timer) clearTimeout(timer);\n    timer = null;\n    pendingArgs = null;\n  };\n\n  debounced.flush = () => {\n    if (timer) {\n      clearTimeout(timer);\n      fn(...(pendingArgs as Parameters<T>));\n      timer = null;\n      pendingArgs = null;\n    }\n  };\n\n  return debounced as typeof debounced & {\n    cancel: () => void;\n    flush: () => void;\n  };\n}\n\n/**\n * Creates a throttled version of a function that limits its execution rate.\n * Allows control over leading/trailing invocation.\n *\n * @template T\n * @param {T} fn - The function to throttle.\n * @param {number} limit - Minimum time between calls in milliseconds.\n * @param {{ leading?: boolean, trailing?: boolean }} [opts] - Options for leading/trailing edge throttling.\n * @returns {(...args: Parameters<T>) => void} A throttled function.\n */\nexport function throttle<T extends (...args: any[]) => void>(\n  fn: T,\n  limit: number,\n  opts: { leading?: boolean; trailing?: boolean } = {\n    leading: true,\n    trailing: false,\n  },\n): (...args: Parameters<T>) => void {\n  let lastCall = 0;\n  let timer: NodeJS.Timeout | null = null;\n  let savedArgs: Parameters<T> | null = null;\n\n  return function (...args: Parameters<T>) {\n    const now = Date.now();\n    const { leading = true, trailing = false } = opts;\n\n    if (!lastCall && !leading) lastCall = now;\n\n    const remaining = limit - (now - lastCall);\n\n    if (remaining <= 0) {\n      if (timer) {\n        clearTimeout(timer);\n        timer = null;\n      }\n      lastCall = now;\n      fn(...args);\n    } else if (trailing) {\n      savedArgs = args;\n      if (!timer) {\n        timer = setTimeout(() => {\n          lastCall = leading ? Date.now() : 0;\n          timer = null;\n          if (savedArgs) fn(...savedArgs);\n        }, remaining);\n      }\n    }\n  };\n}\n\n/**\n * Retries an asynchronous function a given number of times with optional delay/backoff.\n *\n * @template T\n * @param {() => Promise<T>} fn - The async function to retry.\n * @param {number} [retries=3] - Number of retry attempts.\n * @param {number} [delay=500] - Delay in milliseconds between retries.\n * @param {boolean} [backoff=false] - Use exponential backoff between attempts.\n * @param {(error: unknown, attempt: number) => void} [onRetry] - Callback for each retry attempt.\n * @returns {Promise<T>} The result of the async function if successful.\n * @throws {*} The last encountered error if all retries fail.\n */\nexport async function retry<T>(\n  fn: () => Promise<T>,\n  retries = 3,\n  delay = 500,\n  backoff = false,\n  onRetry?: (error: unknown, attempt: number) => void,\n): Promise<T> {\n  for (let i = 0; i < retries; i++) {\n    try {\n      return await fn();\n    } catch (e) {\n      if (i === retries - 1) throw e;\n      if (onRetry) onRetry(e, i + 1);\n      await sleep(backoff ? delay * Math.pow(2, i) : delay);\n    }\n  }\n  throw new Error(\"Retry failed\"); // should never reach here\n}\n\n/**\n * Wraps a promise and rejects it if it doesn't resolve within the specified timeout.\n *\n * @template T\n * @param {Promise<T>} promise - The original promise.\n * @param {number} ms - Timeout in milliseconds.\n * @param {string} [message=\"Operation timed out\"] - Optional timeout message.\n * @returns {Promise<T>} A promise that resolves or rejects within the timeout.\n */\nexport function withTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  message = \"Operation timed out\",\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timeoutHandle = setTimeout(() => reject(new Error(message)), ms);\n    promise\n      .then((result) => {\n        clearTimeout(timeoutHandle);\n        resolve(result);\n      })\n      .catch((err) => {\n        clearTimeout(timeoutHandle);\n        reject(err);\n      });\n  });\n}\n\n/**\n * Executes async tasks in true batches.\n * Each batch runs in parallel, but batches run sequentially.\n * All tasks in a batch start at the same time, next batch waits for full completion.\n * NOTE: For more granular concurrency, use a \"queue\" or \"pooled\" approach.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - An array of functions that return Promises.\n * @param {number} limit - Number of tasks to run in parallel per batch.\n * @returns {Promise<T[]>} A promise that resolves to an array of resolved values.\n */\nexport async function runInBatches<T>(\n  tasks: (() => Promise<T>)[],\n  limit: number,\n): Promise<T[]> {\n  const results: T[] = [];\n  for (let i = 0; i < tasks.length; i += limit) {\n    const batch = tasks.slice(i, i + limit);\n    const batchResults = await Promise.all(batch.map((fn) => fn()));\n    results.push(...batchResults);\n  }\n  return results;\n}\n\n/**\n * Wraps a function and ensures it is only called once at a time.\n * Calls made while one is in progress will wait for the same Promise.\n * Optionally, new calls can be dropped while in progress (drop=true).\n *\n * @template TArgs\n * @template TResult\n * @param {(...args: TArgs) => Promise<TResult>} fn - The async function to wrap.\n * @param {boolean} [drop=false] - If true, new calls while one is pending are rejected.\n * @returns {(...args: TArgs) => Promise<TResult>} A wrapped function with singleton behavior.\n */\nexport function singletonAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => Promise<TResult>,\n  drop: boolean = false,\n): (...args: TArgs) => Promise<TResult> {\n  let promise: Promise<TResult> | null = null;\n\n  return async (...args: TArgs) => {\n    if (!promise) {\n      promise = fn(...args).finally(() => {\n        promise = null;\n      });\n    } else if (drop) {\n      return Promise.reject(new Error(\"Busy: function already running\"));\n    }\n    return promise;\n  };\n}\n\n/**\n * Resolves a list of async tasks in parallel, returning both resolved and rejected results.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.\n * @returns {Promise<PromiseSettledResult<T>[]>} Results including status and value/reason.\n */\nexport async function settleAll<T>(\n  tasks: (() => Promise<T>)[],\n): Promise<PromiseSettledResult<T>[]> {\n  return Promise.allSettled(tasks.map((task) => task()));\n}\n\nexport interface TaskQueue {\n  <T>(taskFn: () => Promise<T>): Promise<T>;\n  pause: () => void;\n  resume: () => void;\n  readonly length: number;\n  readonly isPaused: boolean;\n}\n\n/**\n * A simple task queue that executes async tasks with a concurrency limit.\n * Exposes pause, resume, and queue length getters.\n *\n * @param {number} limit - Maximum number of concurrent tasks.\n * @returns {function & { pause: () => void, resume: () => void, length: number, isPaused: boolean }}\n *   Enqueue function plus queue controls.\n */\nexport function createTaskQueue(limit: number): TaskQueue {\n  const queue: (() => Promise<void>)[] = [];\n  let activeCount = 0;\n  let paused = false;\n\n  const state = {\n    /**\n     * Pause task processing.\n     */\n    pause() {\n      paused = true;\n    },\n    /**\n     * Resume task processing.\n     */\n    resume() {\n      paused = false;\n      next();\n    },\n    /**\n     * The current length of the queue.\n     * @type {number}\n     */\n    get length() {\n      return queue.length;\n    },\n    /**\n     * Whether the queue is currently paused.\n     * @type {boolean}\n     */\n    get isPaused() {\n      return paused;\n    },\n  };\n\n  const next = () => {\n    if (paused || queue.length === 0 || activeCount >= limit) return;\n    const task = queue.shift()!;\n    activeCount++;\n    task().finally(() => {\n      activeCount--;\n      next();\n    });\n  };\n\n  /**\n   * Enqueues a new async task to the queue.\n   *\n   * @template T\n   * @param {() => Promise<T>} taskFn - The async task function.\n   * @returns {Promise<T>} Promise resolving when task completes.\n   */\n  const enqueue = async function <T>(taskFn: () => Promise<T>): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(async () => {\n        try {\n          const result = await taskFn();\n          resolve(result);\n        } catch (err) {\n          reject(err);\n        }\n      });\n      next();\n    });\n  };\n\n  enqueue.pause = state.pause;\n  enqueue.resume = state.resume;\n  Object.defineProperty(enqueue, \"length\", {\n    get: () => queue.length,\n  });\n  Object.defineProperty(enqueue, \"isPaused\", {\n    get: () => paused,\n  });\n\n  return enqueue as TaskQueue;\n}\n\n/**\n * Executes async functions sequentially and collects results.\n * Useful when order matters or tasks depend on each other.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.\n * @returns {Promise<T[]>} Array of resolved values.\n */\nexport async function runInSeries<T>(\n  tasks: (() => Promise<T>)[],\n): Promise<T[]> {\n  const results: T[] = [];\n  for (const task of tasks) {\n    results.push(await task());\n  }\n  return results;\n}\n"]}
+{"version":3,"file":"async.utils.js","sourceRoot":"","sources":["../../../src/utils/async.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Delays execution for a specified number of milliseconds.\n *\n * @param {number} ms - The number of milliseconds to sleep.\n * @returns {Promise<void>} A Promise that resolves after the given time.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Creates a debounced version of a function that delays its execution.\n * Provides `.cancel()` and `.flush()` methods.\n *\n * @template T\n * @param {T} fn - The function to debounce.\n * @param {number} delay - Delay in milliseconds.\n * @returns {T & { cancel: () => void; flush: () => void }} A debounced function.\n */\nexport function debounce<T extends (...args: any[]) => void>(\n  fn: T,\n  delay: number,\n) {\n  let timer: NodeJS.Timeout | null = null;\n  let pendingArgs: Parameters<T> | null = null;\n\n  function debounced(...args: Parameters<T>) {\n    pendingArgs = args;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(() => {\n      fn(...(pendingArgs as Parameters<T>));\n      timer = null;\n    }, delay);\n  }\n\n  debounced.cancel = () => {\n    if (timer) clearTimeout(timer);\n    timer = null;\n    pendingArgs = null;\n  };\n\n  debounced.flush = () => {\n    if (timer) {\n      clearTimeout(timer);\n      fn(...(pendingArgs as Parameters<T>));\n      timer = null;\n      pendingArgs = null;\n    }\n  };\n\n  return debounced as typeof debounced & {\n    cancel: () => void;\n    flush: () => void;\n  };\n}\n\n/**\n * Creates a throttled version of a function that limits its execution rate.\n * Allows control over leading/trailing invocation.\n *\n * @template T\n * @param {T} fn - The function to throttle.\n * @param {number} limit - Minimum time between calls in milliseconds.\n * @param {{ leading?: boolean, trailing?: boolean }} [opts] - Options for leading/trailing edge throttling.\n * @returns {(...args: Parameters<T>) => void} A throttled function.\n */\nexport function throttle<T extends (...args: any[]) => void>(\n  fn: T,\n  limit: number,\n  opts: { leading?: boolean; trailing?: boolean } = {\n    leading: true,\n    trailing: false,\n  },\n): (...args: Parameters<T>) => void {\n  let lastCall = 0;\n  let timer: NodeJS.Timeout | null = null;\n  let savedArgs: Parameters<T> | null = null;\n\n  return function (...args: Parameters<T>) {\n    const now = Date.now();\n    const { leading = true, trailing = false } = opts;\n\n    if (!lastCall && !leading) lastCall = now;\n\n    const remaining = limit - (now - lastCall);\n\n    if (remaining <= 0) {\n      if (timer) {\n        clearTimeout(timer);\n        timer = null;\n      }\n      lastCall = now;\n      fn(...args);\n    } else if (trailing) {\n      savedArgs = args;\n      if (!timer) {\n        timer = setTimeout(() => {\n          lastCall = leading ? Date.now() : 0;\n          timer = null;\n          if (savedArgs) fn(...savedArgs);\n        }, remaining);\n      }\n    }\n  };\n}\n\n/**\n * Retries an asynchronous function a given number of times with optional delay/backoff.\n *\n * @template T\n * @param {() => Promise<T>} fn - The async function to retry.\n * @param {number} [retries=3] - Number of retry attempts.\n * @param {number} [delay=500] - Delay in milliseconds between retries.\n * @param {boolean} [backoff=false] - Use exponential backoff between attempts.\n * @param {(error: unknown, attempt: number) => void} [onRetry] - Callback for each retry attempt.\n * @returns {Promise<T>} The result of the async function if successful.\n * @throws {*} The last encountered error if all retries fail.\n */\nexport async function retry<T>(\n  fn: () => Promise<T>,\n  retries = 3,\n  delay = 500,\n  backoff = false,\n  onRetry?: (error: unknown, attempt: number) => void,\n): Promise<T> {\n  for (let i = 0; i < retries; i++) {\n    try {\n      return await fn();\n    } catch (e) {\n      if (i === retries - 1) throw e;\n      if (onRetry) onRetry(e, i + 1);\n      await sleep(backoff ? delay * Math.pow(2, i) : delay);\n    }\n  }\n  throw new Error(\"Retry failed\"); // should never reach here\n}\n\n/**\n * Wraps a promise and rejects it if it doesn't resolve within the specified timeout.\n *\n * @template T\n * @param {Promise<T>} promise - The original promise.\n * @param {number} ms - Timeout in milliseconds.\n * @param {string} [message=\"Operation timed out\"] - Optional timeout message.\n * @returns {Promise<T>} A promise that resolves or rejects within the timeout.\n */\nexport function withTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  message = \"Operation timed out\",\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timeoutHandle = setTimeout(() => reject(new Error(message)), ms);\n    promise\n      .then((result) => {\n        clearTimeout(timeoutHandle);\n        resolve(result);\n      })\n      .catch((err) => {\n        clearTimeout(timeoutHandle);\n        reject(err);\n      });\n  });\n}\n\n/**\n * Executes async tasks in true batches.\n * Each batch runs in parallel, but batches run sequentially.\n * All tasks in a batch start at the same time, next batch waits for full completion.\n * NOTE: For more granular concurrency, use a \"queue\" or \"pooled\" approach.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - An array of functions that return Promises.\n * @param {number} limit - Number of tasks to run in parallel per batch.\n * @returns {Promise<T[]>} A promise that resolves to an array of resolved values.\n */\nexport async function runInBatches<T>(\n  tasks: (() => Promise<T>)[],\n  limit: number,\n): Promise<T[]> {\n  const results: T[] = [];\n  for (let i = 0; i < tasks.length; i += limit) {\n    const batch = tasks.slice(i, i + limit);\n    const batchResults = await Promise.all(batch.map((fn) => fn()));\n    results.push(...batchResults);\n  }\n  return results;\n}\n\n/**\n * Wraps a function and ensures it is only called once at a time.\n * Calls made while one is in progress will wait for the same Promise.\n * Optionally, new calls can be dropped while in progress (drop=true).\n *\n * @template TArgs\n * @template TResult\n * @param {(...args: TArgs) => Promise<TResult>} fn - The async function to wrap.\n * @param {boolean} [drop=false] - If true, new calls while one is pending are rejected.\n * @returns {(...args: TArgs) => Promise<TResult>} A wrapped function with singleton behavior.\n */\nexport function singletonAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => Promise<TResult>,\n  drop: boolean = false,\n): (...args: TArgs) => Promise<TResult> {\n  let promise: Promise<TResult> | null = null;\n\n  return async (...args: TArgs) => {\n    if (!promise) {\n      promise = fn(...args).finally(() => {\n        promise = null;\n      });\n    } else if (drop) {\n      return Promise.reject(new Error(\"Busy: function already running\"));\n    }\n    return promise;\n  };\n}\n\n/**\n * Resolves a list of async tasks in parallel, returning both resolved and rejected results.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.\n * @returns {Promise<PromiseSettledResult<T>[]>} Results including status and value/reason.\n */\nexport async function settleAll<T>(\n  tasks: (() => Promise<T>)[],\n): Promise<PromiseSettledResult<T>[]> {\n  return Promise.allSettled(tasks.map((task) => task()));\n}\n\nexport interface TaskQueue {\n  <T>(taskFn: () => Promise<T>): Promise<T>;\n  pause: () => void;\n  resume: () => void;\n  readonly length: number;\n  readonly isPaused: boolean;\n}\n\n/**\n * A simple task queue that executes async tasks with a concurrency limit.\n * Exposes pause, resume, and queue length getters.\n *\n * @param {number} limit - Maximum number of concurrent tasks.\n * @returns {function & { pause: () => void, resume: () => void, length: number, isPaused: boolean }}\n *   Enqueue function plus queue controls.\n */\nexport function createTaskQueue(limit: number): TaskQueue {\n  const queue: (() => Promise<void>)[] = [];\n  let activeCount = 0;\n  let paused = false;\n\n  const state = {\n    /**\n     * Pause task processing.\n     */\n    pause() {\n      paused = true;\n    },\n    /**\n     * Resume task processing.\n     */\n    resume() {\n      paused = false;\n      next();\n    },\n    /**\n     * The current length of the queue.\n     * @type {number}\n     */\n    get length() {\n      return queue.length;\n    },\n    /**\n     * Whether the queue is currently paused.\n     * @type {boolean}\n     */\n    get isPaused() {\n      return paused;\n    },\n  };\n\n  const next = () => {\n    if (paused || queue.length === 0 || activeCount >= limit) return;\n    const task = queue.shift()!;\n    activeCount++;\n    task().finally(() => {\n      activeCount--;\n      next();\n    });\n  };\n\n  /**\n   * Enqueues a new async task to the queue.\n   *\n   * @template T\n   * @param {() => Promise<T>} taskFn - The async task function.\n   * @returns {Promise<T>} Promise resolving when task completes.\n   */\n  const enqueue = async function <T>(taskFn: () => Promise<T>): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(async () => {\n        try {\n          const result = await taskFn();\n          resolve(result);\n        } catch (err) {\n          reject(err);\n        }\n      });\n      next();\n    });\n  };\n\n  enqueue.pause = state.pause;\n  enqueue.resume = state.resume;\n  Object.defineProperty(enqueue, \"length\", {\n    get: () => queue.length,\n  });\n  Object.defineProperty(enqueue, \"isPaused\", {\n    get: () => paused,\n  });\n\n  return enqueue as TaskQueue;\n}\n\n/**\n * Executes async functions sequentially and collects results.\n * Useful when order matters or tasks depend on each other.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.\n * @returns {Promise<T[]>} Array of resolved values.\n */\nexport async function runInSeries<T>(\n  tasks: (() => Promise<T>)[],\n): Promise<T[]> {\n  const results: T[] = [];\n  for (const task of tasks) {\n    results.push(await task());\n  }\n  return results;\n}\n\n/**\n * Memoizes an async function, caching results for repeated calls with identical arguments.\n * Optional TTL (time-to-live) for cached entries.\n *\n * @template T Function return type\n * @template Args Function arguments types\n * @param {(...args: Args) => Promise<T>} fn - The async function to memoize\n * @param {object} [options] - Memoization options\n * @param {number} [options.ttl] - Cache TTL in milliseconds (optional)\n * @param {(args: Args) => string} [options.keyFn] - Custom key generator function\n * @returns {(...args: Args) => Promise<T>} Memoized function\n */\nexport function memoizeAsync<T, Args extends any[]>(\n  fn: (...args: Args) => Promise<T>,\n  options: {\n    ttl?: number;\n    keyFn?: (args: Args) => string;\n  } = {},\n): (...args: Args) => Promise<T> {\n  const cache = new Map<string, { value: T; expires: number }>();\n  const { ttl, keyFn = JSON.stringify } = options;\n\n  return async function (...args: Args): Promise<T> {\n    const key = keyFn(args);\n    const cached = cache.get(key);\n\n    if (cached && (!ttl || Date.now() < cached.expires)) {\n      return cached.value;\n    }\n\n    const result = await fn(...args);\n    cache.set(key, {\n      value: result,\n      expires: ttl ? Date.now() + ttl : Infinity,\n    });\n\n    return result;\n  };\n}\n\n/**\n * Creates an abortable version of a promise that can be cancelled using an AbortController.\n *\n * @template T\n * @param {Promise<T>} promise - The promise to make abortable\n * @param {AbortSignal} signal - AbortSignal from AbortController\n * @param {any} [abortValue] - Value to use when rejecting on abort\n * @returns {Promise<T>} Promise that rejects if the signal is aborted\n */\nexport function abortable<T>(\n  promise: Promise<T>,\n  signal: AbortSignal,\n  abortValue: any = new Error(\"Operation aborted\"),\n): Promise<T> {\n  if (signal.aborted) {\n    return Promise.reject(abortValue);\n  }\n\n  return Promise.race([\n    promise,\n    new Promise<T>((_, reject) => {\n      const abort = () => reject(abortValue);\n      signal.addEventListener(\"abort\", abort, { once: true });\n      promise.finally(() => signal.removeEventListener(\"abort\", abort));\n    }),\n  ]);\n}\n\n/**\n * Creates a promise with external resolve/reject functions.\n * Useful for creating promises that can be resolved or rejected from outside.\n *\n * @template T\n * @returns {[Promise<T>, (value: T | PromiseLike<T>) => void, (reason?: any) => void]}\n *   Tuple of [promise, resolve, reject]\n */\nexport function createDeferred<T>(): [\n  Promise<T>,\n  (value: T | PromiseLike<T>) => void,\n  (reason?: any) => void,\n] {\n  let resolve!: (value: T | PromiseLike<T>) => void;\n  let reject!: (reason?: any) => void;\n\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n\n  return [promise, resolve, reject];\n}\n\n/**\n * Chains a series of async functions, passing the result of each to the next.\n * Similar to function composition but for async functions.\n *\n * @template T\n * @param {Array<(input: any) => Promise<any>>} fns - Array of async functions to compose\n * @returns {(input: any) => Promise<T>} Composed function\n */\nexport function waterfall<T>(\n  fns: Array<(input: any) => Promise<any>>,\n): (initialValue: any) => Promise<T> {\n  return async (initialValue: any): Promise<T> => {\n    return fns.reduce(\n      async (acc, fn) => fn(await acc),\n      Promise.resolve(initialValue),\n    ) as Promise<T>;\n  };\n}\n\n/**\n * Creates a rate limiter that ensures functions aren't called more than\n * a specified number of times per interval.\n *\n * @template T\n * @param {(...args: any[]) => Promise<T>} fn - Function to rate limit\n * @param {number} maxCalls - Maximum calls allowed per interval\n * @param {number} interval - Time interval in milliseconds\n * @returns {(...args: any[]) => Promise<T>} Rate limited function\n */\nexport function rateLimit<T>(\n  fn: (...args: any[]) => Promise<T>,\n  maxCalls: number,\n  interval: number,\n): (...args: any[]) => Promise<T> {\n  const calls: number[] = [];\n\n  return async function (...args: any[]): Promise<T> {\n    const now = Date.now();\n    calls.splice(\n      0,\n      calls.length,\n      ...calls.filter((time) => now - time < interval),\n    );\n\n    if (calls.length >= maxCalls) {\n      const oldestCall = calls[0];\n      const delay = interval - (now - oldestCall);\n      await sleep(Math.max(1, delay));\n      // Remove potentially stale entries after sleep\n      const currentTime = Date.now();\n      calls.splice(\n        0,\n        calls.length,\n        ...calls.filter((time) => currentTime - time < interval),\n      );\n\n      // If still at limit after sleep, wait for another cycle\n      if (calls.length >= maxCalls) {\n        const nextDelay = interval - (currentTime - calls[0]);\n        await sleep(Math.max(1, nextDelay));\n        calls.splice(\n          0,\n          calls.length,\n          ...calls.filter((time) => Date.now() - time < interval),\n        );\n      }\n    }\n\n    calls.push(Date.now());\n    return fn(...args);\n  };\n}\n"]}

package/build/esm/utils/cache.utils.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Options for configuring a TTLCache instance.
+ */
+export interface TTLCacheOptions {
+    /** Default time-to-live in milliseconds for cache entries */
+    ttlMs?: number;
+    /** Maximum number of entries to keep in cache (uses LRU eviction policy) */
+    maxSize?: number;
+    /** Auto-cleanup interval in milliseconds (disabled if 0 or negative) */
+    autoCleanupMs?: number;
+}
 /**
  * An in-memory cache with time-to-live (TTL) support for each entry.
  *
@@ -5,17 +16,19 @@
  * @typeParam V - Type of the value.
  *
  * @example
- * const cache = new TTLCache<string, number>(1000);
+ * const cache = new TTLCache<string, number>({ ttlMs: 1000 });
  * cache.set("x", 123);
  * const value = cache.get("x"); // 123
  */
 export declare class TTLCache<K, V> {
-    private ttlMs;
     private cache;
+    private ttlMs;
+    private maxSize?;
+    private cleanupInterval?;
     /**
-     * @param ttlMs - Default time-to-live in milliseconds for cache entries.
+     * @param options - Configuration options for the cache
      */
-    constructor(ttlMs?: number);
+    constructor(options?: TTLCacheOptions);
     /**
      * Sets a key-value pair in the cache with the default TTL.
      *
@@ -38,6 +51,15 @@ export declare class TTLCache<K, V> {
      * @returns The cached value, or undefined if not found or expired.
      */
     get(key: K): V | undefined;
+    /**
+     * Retrieves or computes a value if it's not in the cache or has expired.
+     *
+     * @param key - The key to retrieve
+     * @param producer - Function to generate the value if not cached
+     * @param ttlMs - Optional custom TTL for the computed value
+     * @returns The cached or computed value
+     */
+    getOrCompute(key: K, producer: () => Promise<V>, ttlMs?: number): Promise<V>;
     /**
      * Checks if the key exists and hasn't expired.
      *
@@ -62,6 +84,19 @@ export declare class TTLCache<K, V> {
      * @returns Number of items in the cache (may include expired keys).
      */
     size(): number;
+    /**
+     * Set multiple key-value pairs at once with the default TTL.
+     *
+     * @param entries - Array of [key, value] tuples to set
+     */
+    setMany(entries: [K, V][]): void;
+    /**
+     * Get multiple values at once.
+     *
+     * @param keys - Array of keys to retrieve
+     * @returns Array of values (undefined for keys that don't exist or expired)
+     */
+    getMany(keys: K[]): (V | undefined)[];
     /**
      * Removes all expired entries from the cache.
      *
@@ -86,5 +121,33 @@ export declare class TTLCache<K, V> {
      * @returns IterableIterator<V>
      */
     values(): IterableIterator<V>;
+    /**
+     * Extends the expiration of a key by the specified time or default TTL.
+     *
+     * @param key - The key to refresh
+     * @param ttlMs - Optional new TTL in milliseconds (uses default if not specified)
+     * @returns true if the key was found and refreshed, false otherwise
+     */
+    refresh(key: K, ttlMs?: number): boolean;
+    /**
+     * Returns a snapshot of cache stats.
+     *
+     * @returns Object containing cache statistics
+     */
+    stats(): {
+        size: number;
+        validEntries: number;
+        expiredEntries: number;
+        maxSize: number | undefined;
+    };
+    /**
+     * Stop the auto-cleanup interval if it's running.
+     */
+    destroy(): void;
+    /**
+     * Evict the least recently used entry from the cache.
+     * @private
+     */
+    private evictLRU;
 }
 //# sourceMappingURL=cache.utils.d.ts.map