@catbee/utils 1.1.0 → 2.0.0-next.0

package/array/index.mjs

@@ -0,0 +1,228 @@
+/*
+ * 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 { getValueByPath } from '@catbee/utils/obj';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function chunk(array, size) {
+  if (!Array.isArray(array)) throw new TypeError("Expected an array");
+  if (array.length === 0) return [];
+  if (!Number.isInteger(size) || size <= 0) throw new Error("Chunk size must be a positive integer");
+  const result = [];
+  for (let i = 0; i < array.length; i += size) {
+    result.push(array.slice(i, i + size));
+  }
+  return result;
+}
+__name(chunk, "chunk");
+function unique(array, keyFn) {
+  if (!Array.isArray(array) || array.length === 0) return [];
+  if (!keyFn) return Array.from(new Set(array));
+  const seen = /* @__PURE__ */ new Set();
+  return array.filter((item) => {
+    const key = keyFn(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+__name(unique, "unique");
+function flattenDeep(array) {
+  if (!Array.isArray(array)) return [];
+  const result = [];
+  for (const val of array) {
+    if (Array.isArray(val)) {
+      result.push(...flattenDeep(val));
+    } else {
+      result.push(val);
+    }
+  }
+  return result;
+}
+__name(flattenDeep, "flattenDeep");
+function random(array) {
+  if (!Array.isArray(array) || array.length === 0) return void 0;
+  const idx = Math.floor(Math.random() * array.length);
+  return array[idx];
+}
+__name(random, "random");
+function groupBy(array, keyOrFn) {
+  if (!Array.isArray(array) || array.length === 0) return {};
+  const keyFn = typeof keyOrFn === "function" ? keyOrFn : (item) => item[keyOrFn];
+  return array.reduce((acc, item) => {
+    const key = keyFn(item);
+    if (!acc[key]) acc[key] = [];
+    acc[key].push(item);
+    return acc;
+  }, {});
+}
+__name(groupBy, "groupBy");
+function shuffle(array) {
+  if (!Array.isArray(array)) throw new TypeError("Expected an array");
+  const copy = array.slice();
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [
+      copy[j],
+      copy[i]
+    ];
+  }
+  return copy;
+}
+__name(shuffle, "shuffle");
+function pluck(array, key) {
+  if (!Array.isArray(array)) return [];
+  return array.map((item) => item[key]);
+}
+__name(pluck, "pluck");
+function difference(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return [];
+  const setB = new Set(b);
+  return a.filter((item) => !setB.has(item));
+}
+__name(difference, "difference");
+function intersect(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return [];
+  const setB = new Set(b);
+  return a.filter((item) => setB.has(item));
+}
+__name(intersect, "intersect");
+function mergeSort(array, key, direction = "asc") {
+  if (!Array.isArray(array)) throw new TypeError("Expected array");
+  if (array.length <= 1) return array.slice();
+  const keyFn = typeof key === "function" ? key : (item) => getValueByPath(item, key);
+  const compare = /* @__PURE__ */ __name((a, b) => {
+    const aVal = keyFn(a);
+    const bVal = keyFn(b);
+    if (aVal === bVal) return 0;
+    if (aVal == null) return direction === "asc" ? 1 : -1;
+    if (bVal == null) return direction === "asc" ? -1 : 1;
+    return direction === "asc" ? aVal < bVal ? -1 : 1 : aVal > bVal ? -1 : 1;
+  }, "compare");
+  const merge = /* @__PURE__ */ __name((left, right) => {
+    const result = [];
+    let i = 0, j = 0;
+    while (i < left.length && j < right.length) {
+      if (compare(left[i], right[j]) <= 0) result.push(left[i++]);
+      else result.push(right[j++]);
+    }
+    return result.concat(left.slice(i)).concat(right.slice(j));
+  }, "merge");
+  const sort = /* @__PURE__ */ __name((arr) => {
+    if (arr.length <= 1) return arr;
+    const mid = Math.floor(arr.length / 2);
+    const left = sort(arr.slice(0, mid));
+    const right = sort(arr.slice(mid));
+    return merge(left, right);
+  }, "sort");
+  return sort(array);
+}
+__name(mergeSort, "mergeSort");
+function zip(...arrays) {
+  if (arrays.length === 0) return [];
+  if (arrays.some((arr) => !Array.isArray(arr))) {
+    throw new TypeError("All arguments must be arrays");
+  }
+  const minLength = Math.min(...arrays.map((arr) => arr.length));
+  const result = [];
+  for (let i = 0; i < minLength; i++) {
+    result.push(arrays.map((arr) => arr[i]));
+  }
+  return result;
+}
+__name(zip, "zip");
+function partition(array, predicate) {
+  if (!Array.isArray(array)) return [
+    [],
+    []
+  ];
+  return array.reduce(([pass, fail], item, index) => {
+    return predicate(item, index, array) ? [
+      [
+        ...pass,
+        item
+      ],
+      fail
+    ] : [
+      pass,
+      [
+        ...fail,
+        item
+      ]
+    ];
+  }, [
+    [],
+    []
+  ]);
+}
+__name(partition, "partition");
+function range(start, end, step = 1) {
+  if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(step)) {
+    throw new TypeError("Arguments must be finite numbers");
+  }
+  if (step === 0) throw new Error("Step cannot be zero");
+  const isAscending = step > 0;
+  if (isAscending && start >= end || !isAscending && start <= end) {
+    return [];
+  }
+  const length = Math.max(Math.ceil((end - start) / step), 0);
+  const result = new Array(length);
+  for (let i = 0, value = start; i < length; i++, value += step) {
+    result[i] = value;
+  }
+  return result;
+}
+__name(range, "range");
+function take(array, n = 1) {
+  if (!Array.isArray(array) || n <= 0) return [];
+  return array.slice(0, n);
+}
+__name(take, "take");
+function takeWhile(array, predicate) {
+  if (!Array.isArray(array)) return [];
+  const result = [];
+  for (let i = 0; i < array.length; i++) {
+    if (!predicate(array[i], i)) break;
+    result.push(array[i]);
+  }
+  return result;
+}
+__name(takeWhile, "takeWhile");
+function compact(array) {
+  if (!Array.isArray(array)) return [];
+  return array.filter(Boolean);
+}
+__name(compact, "compact");
+function countBy(array, keyFn) {
+  if (!Array.isArray(array)) return {};
+  return array.reduce((acc, item) => {
+    const key = String(keyFn(item));
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+__name(countBy, "countBy");
+
+export { chunk, compact, countBy, difference, flattenDeep, groupBy, intersect, mergeSort, partition, pluck, random, range, shuffle, take, takeWhile, unique, zip };

package/async/async.utils.d.ts

@@ -0,0 +1,296 @@
+/*
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * 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.
+ */
+export declare function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): {
+    (...args: Parameters<T>): void;
+    cancel(): void;
+    flush(): void;
+} & {
+    cancel: () => void;
+    flush: () => void;
+};
+/**
+ * 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.
+ */
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, limit: number, opts?: {
+    leading?: boolean;
+    trailing?: boolean;
+}): (...args: Parameters<T>) => void;
+/**
+ * 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.
+ */
+export declare function retry<T>(fn: () => Promise<T>, retries?: number, delay?: number, backoff?: boolean, onRetry?: (error: unknown, attempt: number) => void): Promise<T>;
+/**
+ * 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.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+/**
+ * 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.
+ */
+export declare function runInBatches<T>(tasks: (() => Promise<T>)[], limit: number): Promise<T[]>;
+/**
+ * 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.
+ */
+export declare function singletonAsync<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, drop?: boolean): (...args: TArgs) => Promise<TResult>;
+/**
+ * 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.
+ */
+export declare function settleAll<T>(tasks: (() => Promise<T>)[]): Promise<PromiseSettledResult<T>[]>;
+export interface TaskQueue {
+    <T>(taskFn: () => Promise<T>): Promise<T>;
+    pause: () => void;
+    resume: () => void;
+    readonly length: number;
+    readonly isPaused: boolean;
+}
+/**
+ * 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.
+ */
+export declare function createTaskQueue(limit: number): TaskQueue;
+/**
+ * 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.
+ */
+export declare function runInSeries<T>(tasks: (() => Promise<T>)[]): Promise<T[]>;
+/**
+ * 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 declare function memoizeAsync<T, Args extends any[]>(fn: (...args: Args) => Promise<T>, options?: {
+    ttl?: number;
+    keyFn?: (args: Args) => string;
+}): (...args: Args) => Promise<T>;
+/**
+ * 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 declare function abortable<T>(promise: Promise<T>, signal: AbortSignal, abortValue?: any): Promise<T>;
+/**
+ * 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 declare function createDeferred<T>(): [Promise<T>, (value: T | PromiseLike<T>) => void, (reason?: any) => void];
+/**
+ * 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 declare function waterfall<T>(fns: Array<(input: any) => Promise<any>>): (initialValue: any) => Promise<T>;
+/**
+ * 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 declare function rateLimit<T>(fn: (...args: any[]) => Promise<T>, maxCalls: number, interval: number): (...args: any[]) => Promise<T>;
+/**
+ * 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');
+ *   }
+ * }
+ * ```
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Circuit breaker states
+ */
+export declare enum CircuitBreakerState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in milliseconds to wait before trying again (default: 10000) */
+    resetTimeout?: number;
+    /** Number of successful calls to close the circuit again (default: 1) */
+    successThreshold?: number;
+    /** Callback when circuit opens */
+    onOpen?: () => void;
+    /** Callback when circuit closes */
+    onClose?: () => void;
+    /** Callback when circuit enters half-open state */
+    onHalfOpen?: () => void;
+}
+export declare function circuitBreaker<T, Args extends any[]>(fn: (...args: Args) => Promise<T>, options?: CircuitBreakerOptions): (...args: Args) => Promise<T>;
+/**
+ * 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}`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, options?: {
+    /** Maximum number of tasks to run at once (default: 3) */
+    concurrency?: number;
+    /** Called whenever a task completes */
+    onProgress?: (completed: number, total: number) => void;
+    /** Abort signal to cancel execution */
+    signal?: AbortSignal;
+}): Promise<T[]>;
+/**
+ * Optionally requires a module, returning null if not found.
+ *
+ * @template T
+ * @param {string} name - The name of the module to require.
+ * @returns {T | null} The required module or null if not found.
+ */
+export declare function optionalRequire<T = any>(name: string): T | null;