@catbee/utils 1.1.0 → 2.0.0-next.1

package/async/index.mjs

@@ -0,0 +1,463 @@
+/*
+ * 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(() => {
+      try {
+        fn(...pendingArgs);
+      } catch (err) {
+        getLogger().error({
+          err
+        }, "Error in debounced function");
+      }
+      timer = null;
+    }, delay);
+  }
+  __name(debounced, "debounced");
+  debounced.cancel = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    pendingArgs = null;
+  };
+  debounced.flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      try {
+        fn(...pendingArgs);
+      } catch (err) {
+        getLogger().error({
+          err
+        }, "Error in debounced.flush");
+      }
+      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;
+      try {
+        fn(...args);
+      } catch (err) {
+        getLogger().error({
+          err
+        }, "Error in throttled function");
+      }
+    } else if (trailing) {
+      savedArgs = args;
+      if (!timer) {
+        timer = setTimeout(() => {
+          lastCall = leading ? Date.now() : 0;
+          timer = null;
+          if (savedArgs) {
+            try {
+              fn(...savedArgs);
+            } catch (err) {
+              getLogger().error({
+                err
+              }, "Error in throttled trailing call");
+            }
+          }
+        }, 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) {
+      throw new Error("Function is already in progress");
+    }
+    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 } = options;
+  const generateKey = /* @__PURE__ */ __name((args) => {
+    try {
+      return options.keyFn?.(args) ?? JSON.stringify(args);
+    } catch {
+      getLogger().warn("memoizeAsync: key generation failed, falling back to JSON.stringify");
+      return JSON.stringify(args);
+    }
+  }, "generateKey");
+  return async (...args) => {
+    const key = generateKey(args);
+    const cached = cache.get(key);
+    if (cached && 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);
+        signal.removeEventListener("abort", abort);
+      }, "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 fails = 0;
+  let halfSuccess = 0;
+  let unlockAt = 0;
+  const reset = /* @__PURE__ */ __name(() => {
+    fails = 0;
+    halfSuccess = 0;
+    state = "CLOSED";
+    onClose?.();
+  }, "reset");
+  const open = /* @__PURE__ */ __name(() => {
+    state = "OPEN";
+    unlockAt = Date.now() + resetTimeout;
+    onOpen?.();
+  }, "open");
+  const halfOpen = /* @__PURE__ */ __name(() => {
+    state = "HALF_OPEN";
+    onHalfOpen?.();
+  }, "halfOpen");
+  return async (...args) => {
+    const now = Date.now();
+    if (state === "OPEN" && now < unlockAt) {
+      throw new CircuitBreakerOpenError();
+    }
+    if (state === "OPEN" && now >= unlockAt) {
+      halfOpen();
+    }
+    try {
+      const res = await fn(...args);
+      if (state === "HALF_OPEN") {
+        halfSuccess++;
+        if (halfSuccess >= successThreshold) {
+          reset();
+        } else {
+          state = "HALF_OPEN";
+        }
+      } else {
+        fails = 0;
+      }
+      return res;
+    } catch (err) {
+      fails++;
+      if (state === "HALF_OPEN" || state === "CLOSED") {
+        if (fails >= failureThreshold) {
+          open();
+        }
+      }
+      throw err;
+    }
+  };
+}
+__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;
+    let rejected = false;
+    const processNext = /* @__PURE__ */ __name(async () => {
+      if (rejected) return;
+      const currentTaskIndex = taskIndex++;
+      if (currentTaskIndex >= totalTasks) return;
+      try {
+        const result = await tasks[currentTaskIndex]();
+        if (signal?.aborted) {
+          rejected = true;
+          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) {
+        rejected = true;
+        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", () => {
+        rejected = true;
+        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 };