@catbee/utils 1.0.5 → 2.0.0-next.0

package/async/index.mjs

@@ -0,0 +1,407 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
+ */
+
+import { getLogger } from '@catbee/utils/logger';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+__name(sleep, "sleep");
+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);
+  }
+  __name(debounced, "debounced");
+  debounced.cancel = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    pendingArgs = null;
+  };
+  debounced.flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      fn(...pendingArgs);
+      timer = null;
+      pendingArgs = null;
+    }
+  };
+  return debounced;
+}
+__name(debounce, "debounce");
+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);
+      }
+    }
+  };
+}
+__name(throttle, "throttle");
+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");
+}
+__name(retry, "retry");
+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);
+    });
+  });
+}
+__name(withTimeout, "withTimeout");
+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;
+}
+__name(runInBatches, "runInBatches");
+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;
+  };
+}
+__name(singletonAsync, "singletonAsync");
+async function settleAll(tasks) {
+  return Promise.allSettled(tasks.map((task) => task()));
+}
+__name(settleAll, "settleAll");
+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();
+    }};
+  const next = /* @__PURE__ */ __name(() => {
+    if (paused || queue.length === 0 || activeCount >= limit) return;
+    const task = queue.shift();
+    activeCount++;
+    task().finally(() => {
+      activeCount--;
+      next();
+    });
+  }, "next");
+  const enqueue = /* @__PURE__ */ __name(async function(taskFn) {
+    return new Promise((resolve, reject) => {
+      queue.push(async () => {
+        try {
+          const result = await taskFn();
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+      });
+      next();
+    });
+  }, "enqueue");
+  enqueue.pause = state.pause;
+  enqueue.resume = state.resume;
+  Object.defineProperty(enqueue, "length", {
+    get: /* @__PURE__ */ __name(() => queue.length, "get")
+  });
+  Object.defineProperty(enqueue, "isPaused", {
+    get: /* @__PURE__ */ __name(() => paused, "get")
+  });
+  return enqueue;
+}
+__name(createTaskQueue, "createTaskQueue");
+async function runInSeries(tasks) {
+  const results = [];
+  for (const task of tasks) {
+    results.push(await task());
+  }
+  return results;
+}
+__name(runInSeries, "runInSeries");
+function memoizeAsync(fn, options = {}) {
+  const cache = /* @__PURE__ */ 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;
+  };
+}
+__name(memoizeAsync, "memoizeAsync");
+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 = /* @__PURE__ */ __name(() => reject(abortValue), "abort");
+      signal.addEventListener("abort", abort, {
+        once: true
+      });
+      promise.finally(() => signal.removeEventListener("abort", abort));
+    })
+  ]);
+}
+__name(abortable, "abortable");
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return [
+    promise,
+    resolve,
+    reject
+  ];
+}
+__name(createDeferred, "createDeferred");
+function waterfall(fns) {
+  return async (initialValue) => {
+    return fns.reduce(async (acc, fn) => fn(await acc), Promise.resolve(initialValue));
+  };
+}
+__name(waterfall, "waterfall");
+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));
+      const currentTime = Date.now();
+      calls.splice(0, calls.length, ...calls.filter((time) => currentTime - time < interval));
+      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);
+  };
+}
+__name(rateLimit, "rateLimit");
+var CircuitBreakerOpenError = class extends Error {
+  static {
+    __name(this, "CircuitBreakerOpenError");
+  }
+  constructor(message = "Circuit breaker is open") {
+    super(message);
+    this.name = "CircuitBreakerOpenError";
+  }
+};
+var CircuitBreakerState = /* @__PURE__ */ (function(CircuitBreakerState2) {
+  CircuitBreakerState2["CLOSED"] = "CLOSED";
+  CircuitBreakerState2["OPEN"] = "OPEN";
+  CircuitBreakerState2["HALF_OPEN"] = "HALF_OPEN";
+  return CircuitBreakerState2;
+})({});
+function circuitBreaker(fn, options = {}) {
+  const { failureThreshold = 5, resetTimeout = 1e4, successThreshold = 1, onOpen, onClose, onHalfOpen } = options;
+  let state = "CLOSED";
+  let failureCount = 0;
+  let successCount = 0;
+  let nextAttempt = Date.now();
+  return async function(...args) {
+    if (state === "OPEN") {
+      if (Date.now() < nextAttempt) {
+        throw new CircuitBreakerOpenError();
+      }
+      state = "HALF_OPEN";
+      if (onHalfOpen) onHalfOpen();
+    }
+    try {
+      const result = await fn(...args);
+      if (state === "HALF_OPEN") {
+        successCount++;
+        if (successCount >= successThreshold) {
+          successCount = 0;
+          failureCount = 0;
+          state = "CLOSED";
+          if (onClose) onClose();
+        }
+      } else {
+        failureCount = 0;
+      }
+      return result;
+    } catch (error) {
+      failureCount++;
+      if ((state === "CLOSED" || state === "HALF_OPEN") && failureCount >= failureThreshold) {
+        state = "OPEN";
+        nextAttempt = Date.now() + resetTimeout;
+        if (onOpen) onOpen();
+      }
+      throw error;
+    }
+  };
+}
+__name(circuitBreaker, "circuitBreaker");
+async function runWithConcurrency(tasks, options = {}) {
+  const { concurrency = 3, onProgress, signal } = options;
+  const results = [];
+  const totalTasks = tasks.length;
+  let completed = 0;
+  if (totalTasks === 0) return results;
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+  return new Promise((resolve, reject) => {
+    let taskIndex = 0;
+    const processNext = /* @__PURE__ */ __name(async () => {
+      const currentTaskIndex = taskIndex++;
+      if (currentTaskIndex >= totalTasks) return;
+      try {
+        const result = await tasks[currentTaskIndex]();
+        if (signal?.aborted) {
+          reject(new Error("Aborted"));
+          return;
+        }
+        results[currentTaskIndex] = result;
+        completed++;
+        if (onProgress) {
+          try {
+            onProgress(completed, totalTasks);
+          } catch (err) {
+            getLogger().error({
+              err
+            }, "Error in onProgress callback");
+          }
+        }
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      if (completed === totalTasks) {
+        resolve(results);
+        return;
+      }
+      processNext();
+    }, "processNext");
+    const initialBatch = Math.min(concurrency, totalTasks);
+    for (let i = 0; i < initialBatch; i++) {
+      processNext();
+    }
+    if (signal) {
+      signal.addEventListener("abort", () => {
+        reject(new Error("Aborted"));
+      }, {
+        once: true
+      });
+    }
+  });
+}
+__name(runWithConcurrency, "runWithConcurrency");
+function optionalRequire(name) {
+  try {
+    return __require(name);
+  } catch {
+    return null;
+  }
+}
+__name(optionalRequire, "optionalRequire");
+
+export { CircuitBreakerOpenError, CircuitBreakerState, abortable, circuitBreaker, createDeferred, createTaskQueue, debounce, memoizeAsync, optionalRequire, rateLimit, retry, runInBatches, runInSeries, runWithConcurrency, settleAll, singletonAsync, sleep, throttle, waterfall, withTimeout };

package/cache/cache.utils.d.ts

@@ -0,0 +1,176 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
+ */
+
+/**
+ * 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.
+ *
+ * @typeParam K - Type of the key.
+ * @typeParam V - Type of the value.
+ *
+ * @example
+ * 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 cache;
+    private ttlMs;
+    private maxSize?;
+    private cleanupInterval?;
+    /**
+     * @param options - Configuration options for the cache
+     */
+    constructor(options?: TTLCacheOptions);
+    /**
+     * Sets a key-value pair in the cache with the default TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     */
+    set(key: K, value: V): void;
+    /**
+     * Sets a key-value pair in the cache with a custom TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     * @param ttlMs - Time-to-live in milliseconds.
+     */
+    setWithTTL(key: K, value: V, ttlMs: number): void;
+    /**
+     * Retrieves the value for a given key if it hasn't expired.
+     *
+     * @param key - The key to retrieve.
+     * @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.
+     *
+     * @param key - The key to check.
+     * @returns `true` if key exists and is valid, otherwise `false`.
+     */
+    has(key: K): boolean;
+    /**
+     * Deletes a key from the cache.
+     *
+     * @param key - The key to delete.
+     * @returns `true` if the key existed and was removed, `false` otherwise.
+     */
+    delete(key: K): boolean;
+    /**
+     * Clears all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).
+     *
+     * @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.
+     *
+     * @returns Number of entries removed.
+     */
+    cleanup(): number;
+    /**
+     * Returns an iterator of all current valid [key, value] pairs.
+     *
+     * @returns IterableIterator<[K, V]>
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterator of all current valid keys.
+     *
+     * @returns IterableIterator<K>
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Returns an iterator of all current valid values.
+     *
+     * @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;
+}