@catbee/utils/build/src/utils/array.utils.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/**
 * 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 function 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[];
/**
 * Combines multiple arrays into a single array of grouped elements.
 * Output array length equals the length of the shortest input array.
 *
 * @example zip([1, 2], ['a', 'b']) => [[1, 'a'], [2, 'b']]
 * @param {...Array<T>[]} arrays - Two or more arrays to zip together.
 * @returns {Array<T[]>} Array of grouped elements.
 */
export declare function zip<T>(...arrays: T[][]): T[][];
/**
 * Splits an array into two arrays based on a predicate function.
 *
 * @template T The type of array elements.
 * @param {T[]} array - The input array.
 * @param {(item: T, index: number, array: T[]) => boolean} predicate - Function to test each element.
 * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].
 */
export declare function partition<T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): [T[], T[]];
/**
 * Generates an array of numbers within a specified range.
 *
 * @param {number} start - Start of range (inclusive).
 * @param {number} end - End of range (exclusive).
 * @param {number} [step=1] - Step between numbers.
 * @returns {number[]} Array of numbers in range.
 */
export declare function range(start: number, end: number, step?: number): number[];
/**
 * Returns the first n elements of an array.
 *
 * @template T The type of array elements.
 * @param {T[]} array - The input array.
 * @param {number} [n=1] - Number of elements to take.
 * @returns {T[]} New array with first n elements.
 */
export declare function take<T>(array: T[], n?: number): T[];
/**
 * Takes elements from the array while predicate returns true.
 *
 * @template T The type of array elements.
 * @param {T[]} array - The input array.
 * @param {(item: T, index: number) => boolean} predicate - Function to test each element.
 * @returns {T[]} New array with taken elements.
 */
export declare function takeWhile<T>(array: T[], predicate: (item: T, index: number) => boolean): T[];
/**
 * Removes all falsy values from an array.
 * False, null, 0, "", undefined, and NaN are falsy.
 *
 * @template T The type of array elements.
 * @param {T[]} array - The input array.
 * @returns {NonNullable<T>[]} New array with falsy values removed.
 */
export declare function compact<T>(array: T[]): NonNullable<T>[];
/**
 * Counts array elements by a key function.
 *
 * @template T The type of array elements.
 * @param {T[]} array - The input array.
 * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.
 * @returns {Record<string, number>} Object with counts by key.
 */
export declare function countBy<T>(array: T[], keyFn: (item: T) => string | number | symbol): Record<string, number>;
//# sourceMappingURL=array.utils.d.ts.map