@catbee/utils 0.0.1

package/build/src/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./utils/array.utils"), exports);
+__exportStar(require("./utils/async.utils"), exports);
+__exportStar(require("./utils/cache.utils"), exports);
+__exportStar(require("./utils/context-store.utils"), exports);
+__exportStar(require("./utils/crypto.utils"), exports);
+__exportStar(require("./utils/dir.utils"), exports);
+__exportStar(require("./utils/env.utils"), exports);
+__exportStar(require("./utils/exception.utils"), exports);
+__exportStar(require("./utils/fs.utils"), exports);
+__exportStar(require("./utils/http-status-codes"), exports);
+__exportStar(require("./utils/id.utils"), exports);
+__exportStar(require("./utils/logger.utils"), exports);
+__exportStar(require("./utils/obj.utils"), exports);
+__exportStar(require("./utils/response.utils"), exports);
+__exportStar(require("./utils/string.utils"), exports);
+__exportStar(require("./utils/url.utils"), exports);
+__exportStar(require("./utils/validate.utils"), exports);
+__exportStar(require("./types/api-response"), exports);
+//# sourceMappingURL=index.js.map

package/build/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,sDAAoC;AACpC,sDAAoC;AACpC,8DAA4C;AAC5C,uDAAqC;AACrC,oDAAkC;AAClC,oDAAkC;AAClC,0DAAwC;AACxC,mDAAiC;AACjC,4DAA0C;AAC1C,mDAAiC;AACjC,uDAAqC;AACrC,oDAAkC;AAClC,yDAAuC;AACvC,uDAAqC;AACrC,oDAAkC;AAClC,yDAAuC;AAEvC,uDAAqC","sourcesContent":["export * from \"./utils/array.utils\";\nexport * from \"./utils/async.utils\";\nexport * from \"./utils/cache.utils\";\nexport * from \"./utils/context-store.utils\";\nexport * from \"./utils/crypto.utils\";\nexport * from \"./utils/dir.utils\";\nexport * from \"./utils/env.utils\";\nexport * from \"./utils/exception.utils\";\nexport * from \"./utils/fs.utils\";\nexport * from \"./utils/http-status-codes\";\nexport * from \"./utils/id.utils\";\nexport * from \"./utils/logger.utils\";\nexport * from \"./utils/obj.utils\";\nexport * from \"./utils/response.utils\";\nexport * from \"./utils/string.utils\";\nexport * from \"./utils/url.utils\";\nexport * from \"./utils/validate.utils\";\n\nexport * from \"./types/api-response\";\n"]}

package/build/src/types/api-response.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generic API response format.
+ * Used to wrap any successful or failed response from the server.
+ */
+export interface ApiResponse<T = any> {
+    /** Payload returned from the API. Can be any shape depending on the endpoint. */
+    data: T | null;
+    /** Indicates whether an error occurred (true = error, false = success). */
+    error: boolean;
+    /** Human-readable message to describe the result or error. */
+    message: string;
+    /** Unique request ID for traceability in logs (e.g., from a middleware). */
+    requestId: string;
+    /** ISO timestamp when the response was generated. */
+    timestamp: string;
+}
+/**
+ * Generic pagination structure used for paged lists (e.g., /users?page=1).
+ */
+export interface Pagination<T = any> {
+    /** List of records for the current page. */
+    content: T[];
+    /** Metadata about the pagination state. */
+    pagination: {
+        /** Total number of records across all pages. */
+        totalRecords: number;
+        /** Total number of pages available. */
+        totalPages: number;
+        /** Current page number (1-based index). */
+        page: number;
+        /** Number of records per page. */
+        limit: number;
+        /** Field by which the data is sorted. */
+        sortBy: string;
+        /** Sort order: ascending or descending. */
+        sortOrder: "asc" | "desc";
+    };
+}
+/**
+ * Alias for paginated API response.
+ * Allows semantic naming like `PaginationResponse<User>` or `PaginationResponse<Post>`.
+ */
+export type PaginationResponse<T = any> = Pagination<T>;
+//# sourceMappingURL=api-response.d.ts.map

package/build/src/types/api-response.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api-response.js.map

package/build/src/types/api-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.js","sourceRoot":"","sources":["../../../src/types/api-response.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Generic API response format.\n * Used to wrap any successful or failed response from the server.\n */\nexport interface ApiResponse<T = any> {\n  /** Payload returned from the API. Can be any shape depending on the endpoint. */\n  data: T | null;\n\n  /** Indicates whether an error occurred (true = error, false = success). */\n  error: boolean;\n\n  /** Human-readable message to describe the result or error. */\n  message: string;\n\n  /** Unique request ID for traceability in logs (e.g., from a middleware). */\n  requestId: string;\n\n  /** ISO timestamp when the response was generated. */\n  timestamp: string;\n}\n\n/**\n * Generic pagination structure used for paged lists (e.g., /users?page=1).\n */\nexport interface Pagination<T = any> {\n  /** List of records for the current page. */\n  content: T[];\n\n  /** Metadata about the pagination state. */\n  pagination: {\n    /** Total number of records across all pages. */\n    totalRecords: number;\n\n    /** Total number of pages available. */\n    totalPages: number;\n\n    /** Current page number (1-based index). */\n    page: number;\n\n    /** Number of records per page. */\n    limit: number;\n\n    /** Field by which the data is sorted. */\n    sortBy: string;\n\n    /** Sort order: ascending or descending. */\n    sortOrder: \"asc\" | \"desc\";\n  };\n}\n\n/**\n * Alias for paginated API response.\n * Allows semantic naming like `PaginationResponse<User>` or `PaginationResponse<Post>`.\n */\nexport type PaginationResponse<T = any> = Pagination<T>;\n"]}

package/build/src/utils/array.utils.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Splits an array into chunks of the specified size.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The array to split into chunks.
+ * @param {number} size - The number of elements per chunk.
+ * @returns {T[][]} A new array containing chunked arrays.
+ * @throws {TypeError} If array is not an array.
+ * @throws {Error} If chunk size is not a positive integer.
+ */
+export declare const chunk: <T>(array: T[], size: number) => T[][];
+/**
+ * Removes duplicate values from an array.
+ * Optionally enforces uniqueness by a key function.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.
+ * @returns {T[]} A new array with unique values.
+ */
+export declare function unique<T>(array: T[], keyFn?: (item: T) => unknown): T[];
+/**
+ * Deeply flattens a nested array to a single-level array.
+ *
+ * @template T The leaf type of array elements.
+ * @param {any[]} array - The (possibly deeply nested) input array.
+ * @returns {T[]} A deeply flattened array.
+ */
+export declare function flattenDeep<T>(array: any[]): T[];
+/**
+ * Returns a random element from an array, or undefined if empty.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.
+ */
+export declare function random<T>(array: T[]): T | undefined;
+/**
+ * Groups items in an array by a key or key function.
+ *
+ * @template T The type of array elements.
+ * @overload
+ * @param {T[]} array - The array to group.
+ * @param {keyof T} key - Property key to group by.
+ * @returns {Record<string, T[]>}
+ * @overload
+ * @param {T[]} array - The array to group.
+ * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.
+ * @returns {Record<K, T[]>}
+ * @param {T[]} array - The array to group.
+ * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Property key or key-generating function.
+ * @returns {Record<string | number | symbol, T[]>} An object mapping group keys to item arrays.
+ */
+export declare function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
+export declare function groupBy<T, K extends string | number | symbol>(array: T[], keyFn: (item: T) => K): Record<K, T[]>;
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @returns {T[]} A new shuffled array.
+ * @throws {TypeError} If array is not an array.
+ */
+export declare function shuffle<T>(array: T[]): T[];
+/**
+ * Returns an array of property values from an array of objects.
+ *
+ * @template T The type of array elements.
+ * @template K The object property to pluck.
+ * @param {T[]} array - The input array.
+ * @param {K} key - The property name to pluck.
+ * @returns {T[K][]} Array of property values.
+ */
+export declare function pluck<T, K extends keyof T>(array: T[], key: K): T[K][];
+/**
+ * Returns values in array A that are not in array B.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} a - First array.
+ * @param {T[]} b - Second array.
+ * @returns {T[]} Elements in A that are not in B.
+ */
+export declare function difference<T>(a: T[], b: T[]): T[];
+/**
+ * Returns common values between arrays A and B.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} a - First array.
+ * @param {T[]} b - Second array.
+ * @returns {T[]} Elements that exist in both arrays.
+ */
+export declare function intersect<T>(a: T[], b: T[]): T[];
+/**
+ * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).
+ * Missing/undefined keys are sorted to the "end" (asc) or "start" (desc).
+ *
+ * @template T The type of array elements (objects).
+ * @param {T[]} array - Array of objects to sort.
+ * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., "profile.age") or function.
+ * @param {"asc" | "desc"} [direction="asc"] - Sort direction: 'asc' or 'desc'.
+ * @returns {T[]} A new sorted array.
+ * @throws {TypeError} If array is not an array.
+ */
+export declare function mergeSort<T>(array: T[], key: string | ((item: T) => any), direction?: "asc" | "desc"): T[];
+//# sourceMappingURL=array.utils.d.ts.map

package/build/src/utils/array.utils.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunk = void 0;
+exports.unique = unique;
+exports.flattenDeep = flattenDeep;
+exports.random = random;
+exports.groupBy = groupBy;
+exports.shuffle = shuffle;
+exports.pluck = pluck;
+exports.difference = difference;
+exports.intersect = intersect;
+exports.mergeSort = mergeSort;
+const obj_utils_1 = require("./obj.utils");
+/**
+ * Splits an array into chunks of the specified size.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The array to split into chunks.
+ * @param {number} size - The number of elements per chunk.
+ * @returns {T[][]} A new array containing chunked arrays.
+ * @throws {TypeError} If array is not an array.
+ * @throws {Error} If chunk size is not a positive integer.
+ */
+const chunk = (array, size) => {
+    if (!Array.isArray(array))
+        throw new TypeError("Expected an array");
+    if (!array.length)
+        return [];
+    if (!Number.isInteger(size) || size <= 0)
+        throw new Error("Chunk size must be a positive integer");
+    return Array.from({ length: Math.ceil(array.length / size) }, (_, i) => array.slice(i * size, i * size + size));
+};
+exports.chunk = chunk;
+/**
+ * Removes duplicate values from an array.
+ * Optionally enforces uniqueness by a key function.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.
+ * @returns {T[]} A new array with unique values.
+ */
+function unique(array, keyFn) {
+    if (!Array.isArray(array) || array.length === 0)
+        return [];
+    if (!keyFn)
+        return Array.from(new Set(array));
+    const seen = new Set();
+    return array.filter((item) => {
+        const key = keyFn(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Deeply flattens a nested array to a single-level array.
+ *
+ * @template T The leaf type of array elements.
+ * @param {any[]} array - The (possibly deeply nested) input array.
+ * @returns {T[]} A deeply flattened array.
+ */
+function flattenDeep(array) {
+    if (!Array.isArray(array))
+        return [];
+    return array.reduce((acc, val) => {
+        if (Array.isArray(val)) {
+            acc.push(...flattenDeep(val));
+        }
+        else {
+            acc.push(val);
+        }
+        return acc;
+    }, []);
+}
+/**
+ * Returns a random element from an array, or undefined if empty.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.
+ */
+function random(array) {
+    if (!Array.isArray(array) || array.length === 0)
+        return undefined;
+    return array[Math.floor(Math.random() * array.length)];
+}
+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;
+    }, {});
+}
+/* eslint-enable no-redeclare */
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} array - The input array.
+ * @returns {T[]} A new shuffled array.
+ * @throws {TypeError} If array is not an array.
+ */
+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;
+}
+/**
+ * Returns an array of property values from an array of objects.
+ *
+ * @template T The type of array elements.
+ * @template K The object property to pluck.
+ * @param {T[]} array - The input array.
+ * @param {K} key - The property name to pluck.
+ * @returns {T[K][]} Array of property values.
+ */
+function pluck(array, key) {
+    if (!Array.isArray(array))
+        return [];
+    return array.map((item) => item[key]);
+}
+/**
+ * Returns values in array A that are not in array B.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} a - First array.
+ * @param {T[]} b - Second array.
+ * @returns {T[]} Elements in A that are not in B.
+ */
+function difference(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return [];
+    const setB = new Set(b);
+    return a.filter((item) => !setB.has(item));
+}
+/**
+ * Returns common values between arrays A and B.
+ *
+ * @template T The type of array elements.
+ * @param {T[]} a - First array.
+ * @param {T[]} b - Second array.
+ * @returns {T[]} Elements that exist in both arrays.
+ */
+function intersect(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return [];
+    const setB = new Set(b);
+    return a.filter((item) => setB.has(item));
+}
+/**
+ * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).
+ * Missing/undefined keys are sorted to the "end" (asc) or "start" (desc).
+ *
+ * @template T The type of array elements (objects).
+ * @param {T[]} array - Array of objects to sort.
+ * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., "profile.age") or function.
+ * @param {"asc" | "desc"} [direction="asc"] - Sort direction: 'asc' or 'desc'.
+ * @returns {T[]} A new sorted array.
+ * @throws {TypeError} If array is not an array.
+ */
+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) => (0, obj_utils_1.getValueByPath)(item, key);
+    const compare = (a, b) => {
+        const aVal = keyFn(a);
+        const bVal = keyFn(b);
+        // Sorts undefined/null last for "asc", first for "desc"
+        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;
+    };
+    const merge = (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));
+    };
+    const sort = (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);
+    };
+    return sort(array);
+}
+//# sourceMappingURL=array.utils.js.map

package/build/src/utils/array.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.utils.js","sourceRoot":"","sources":["../../../src/utils/array.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { getValueByPath } from \"./obj.utils\";\n\n/**\n * Splits an array into chunks of the specified size.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The array to split into chunks.\n * @param {number} size - The number of elements per chunk.\n * @returns {T[][]} A new array containing chunked arrays.\n * @throws {TypeError} If array is not an array.\n * @throws {Error} If chunk size is not a positive integer.\n */\nexport const chunk = <T>(array: T[], size: number): T[][] => {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected an array\");\n  if (!array.length) return [];\n  if (!Number.isInteger(size) || size <= 0)\n    throw new Error(\"Chunk size must be a positive integer\");\n  return Array.from({ length: Math.ceil(array.length / size) }, (_, i) =>\n    array.slice(i * size, i * size + size),\n  );\n};\n\n/**\n * Removes duplicate values from an array.\n * Optionally enforces uniqueness by a key function.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.\n * @returns {T[]} A new array with unique values.\n */\nexport function unique<T>(array: T[], keyFn?: (item: T) => unknown): T[] {\n  if (!Array.isArray(array) || array.length === 0) return [];\n  if (!keyFn) return Array.from(new Set(array));\n  const seen = new Set<unknown>();\n  return array.filter((item) => {\n    const key = keyFn(item);\n    if (seen.has(key)) return false;\n    seen.add(key);\n    return true;\n  });\n}\n\n/**\n * Deeply flattens a nested array to a single-level array.\n *\n * @template T The leaf type of array elements.\n * @param {any[]} array - The (possibly deeply nested) input array.\n * @returns {T[]} A deeply flattened array.\n */\nexport function flattenDeep<T>(array: any[]): T[] {\n  if (!Array.isArray(array)) return [];\n  return array.reduce<T[]>((acc, val) => {\n    if (Array.isArray(val)) {\n      acc.push(...flattenDeep<T>(val));\n    } else {\n      acc.push(val);\n    }\n    return acc;\n  }, []);\n}\n\n/**\n * Returns a random element from an array, or undefined if empty.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.\n */\nexport function random<T>(array: T[]): T | undefined {\n  if (!Array.isArray(array) || array.length === 0) return undefined;\n  return array[Math.floor(Math.random() * array.length)];\n}\n\n/* eslint-disable no-redeclare */\n/**\n * Groups items in an array by a key or key function.\n *\n * @template T The type of array elements.\n * @overload\n * @param {T[]} array - The array to group.\n * @param {keyof T} key - Property key to group by.\n * @returns {Record<string, T[]>}\n * @overload\n * @param {T[]} array - The array to group.\n * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.\n * @returns {Record<K, T[]>}\n * @param {T[]} array - The array to group.\n * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Property key or key-generating function.\n * @returns {Record<string | number | symbol, T[]>} An object mapping group keys to item arrays.\n */\nexport function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;\nexport function groupBy<T, K extends string | number | symbol>(\n  array: T[],\n  keyFn: (item: T) => K,\n): Record<K, T[]>;\nexport function groupBy<T>(\n  array: T[],\n  keyOrFn: keyof T | ((item: T) => string | number | symbol),\n): Record<string | number | symbol, T[]> {\n  if (!Array.isArray(array) || array.length === 0) return {};\n  const keyFn =\n    typeof keyOrFn === \"function\"\n      ? keyOrFn\n      : (item: T) => item[keyOrFn as keyof T];\n  return array.reduce(\n    (acc, item) => {\n      const key = keyFn(item) as string | number | symbol;\n      if (!acc[key]) acc[key] = [];\n      acc[key].push(item);\n      return acc;\n    },\n    {} as Record<string | number | symbol, T[]>,\n  );\n}\n/* eslint-enable no-redeclare */\n\n/**\n * Shuffles an array using the Fisher-Yates algorithm.\n *\n * @template T The type of array elements.\n * @param {T[]} array - The input array.\n * @returns {T[]} A new shuffled array.\n * @throws {TypeError} If array is not an array.\n */\nexport function shuffle<T>(array: T[]): T[] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected an array\");\n  const copy = array.slice();\n  for (let i = copy.length - 1; i > 0; i--) {\n    const j = Math.floor(Math.random() * (i + 1));\n    [copy[i], copy[j]] = [copy[j], copy[i]];\n  }\n  return copy;\n}\n\n/**\n * Returns an array of property values from an array of objects.\n *\n * @template T The type of array elements.\n * @template K The object property to pluck.\n * @param {T[]} array - The input array.\n * @param {K} key - The property name to pluck.\n * @returns {T[K][]} Array of property values.\n */\nexport function pluck<T, K extends keyof T>(array: T[], key: K): T[K][] {\n  if (!Array.isArray(array)) return [];\n  return array.map((item) => item[key]);\n}\n\n/**\n * Returns values in array A that are not in array B.\n *\n * @template T The type of array elements.\n * @param {T[]} a - First array.\n * @param {T[]} b - Second array.\n * @returns {T[]} Elements in A that are not in B.\n */\nexport function difference<T>(a: T[], b: T[]): T[] {\n  if (!Array.isArray(a) || !Array.isArray(b)) return [];\n  const setB = new Set(b);\n  return a.filter((item) => !setB.has(item));\n}\n\n/**\n * Returns common values between arrays A and B.\n *\n * @template T The type of array elements.\n * @param {T[]} a - First array.\n * @param {T[]} b - Second array.\n * @returns {T[]} Elements that exist in both arrays.\n */\nexport function intersect<T>(a: T[], b: T[]): T[] {\n  if (!Array.isArray(a) || !Array.isArray(b)) return [];\n  const setB = new Set(b);\n  return a.filter((item) => setB.has(item));\n}\n\n/**\n * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).\n * Missing/undefined keys are sorted to the \"end\" (asc) or \"start\" (desc).\n *\n * @template T The type of array elements (objects).\n * @param {T[]} array - Array of objects to sort.\n * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., \"profile.age\") or function.\n * @param {\"asc\" | \"desc\"} [direction=\"asc\"] - Sort direction: 'asc' or 'desc'.\n * @returns {T[]} A new sorted array.\n * @throws {TypeError} If array is not an array.\n */\nexport function mergeSort<T>(\n  array: T[],\n  key: string | ((item: T) => any),\n  direction: \"asc\" | \"desc\" = \"asc\",\n): T[] {\n  if (!Array.isArray(array)) throw new TypeError(\"Expected array\");\n  if (array.length <= 1) return array.slice();\n\n  const keyFn =\n    typeof key === \"function\"\n      ? key\n      : (item: T) => getValueByPath(item as object, key);\n\n  const compare = (a: T, b: T) => {\n    const aVal = keyFn(a);\n    const bVal = keyFn(b);\n    // Sorts undefined/null last for \"asc\", first for \"desc\"\n    if (aVal === bVal) return 0;\n    if (aVal == null) return direction === \"asc\" ? 1 : -1;\n    if (bVal == null) return direction === \"asc\" ? -1 : 1;\n    return direction === \"asc\" ? (aVal < bVal ? -1 : 1) : aVal > bVal ? -1 : 1;\n  };\n\n  const merge = (left: T[], right: T[]): T[] => {\n    const result: T[] = [];\n    let i = 0,\n      j = 0;\n    while (i < left.length && j < right.length) {\n      if (compare(left[i], right[j]) <= 0) result.push(left[i++]);\n      else result.push(right[j++]);\n    }\n    return result.concat(left.slice(i)).concat(right.slice(j));\n  };\n\n  const sort = (arr: T[]): T[] => {\n    if (arr.length <= 1) return arr;\n    const mid = Math.floor(arr.length / 2);\n    const left = sort(arr.slice(0, mid));\n    const right = sort(arr.slice(mid));\n    return merge(left, right);\n  };\n  return sort(array);\n}\n"]}

package/build/src/utils/async.utils.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 const 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[]>;
+//# sourceMappingURL=async.utils.d.ts.map