@catbee/utils 2.0.0-next.0 → 2.0.0

package/array/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 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
@@ -22,4 +22,347 @@
  * SOFTWARE.
  */
 
-export * from './array.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.
+ */
+declare function chunk<T>(array: readonly 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.
+ */
+declare function unique<T>(array: readonly T[], keyFn?: (item: T) => unknown): T[];
+/**
+ * Deeply flattens a nested array to a single-level array (iterative, stack-based).
+ *
+ * @template T The leaf type of array elements.
+ * @param {readonly unknown[]} array - The (possibly deeply nested) input array.
+ * @returns {T[]} A deeply flattened array.
+ */
+declare function flattenDeep<T>(array: readonly unknown[]): T[];
+/**
+ * Returns a random element from an array, or undefined if empty. Uses crypto-secure randomness
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * securePick(['a','b','c']); // -> 'b'
+ * ```
+ */
+declare function random<T>(array: readonly T[]): T | undefined;
+type StrNumSym = string | number | symbol;
+/**
+ * Groups items in an array by a nested 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, readonly T[]>}
+ * @overload
+ * @param {T[]} array - The array to group.
+ * @param {(item: T) => StrNumSym} keyFn - Function to generate group key from item.
+ * @returns {Record<K, readonly T[]>}
+ * @param {T[]} array - The array to group.
+ * @param {keyof T | ((item: T) => StrNumSym)} keyOrFn - Nested property key or key selector.
+ * @returns {Record<StrNumSym, readonly T[]>} Grouped result object.
+ */
+declare function groupBy<T>(array: T[], key: keyof T): Record<string, readonly T[]>;
+declare function groupBy<T, K extends StrNumSym>(array: T[], keyFn: (item: T) => K): Record<K, readonly T[]>;
+/**
+ * Shuffles an array using the Fisher-Yates algorithm. Uses crypto-secure randomness.
+ *
+ * @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.
+ */
+declare function shuffle<T>(array: readonly T[]): T[];
+/**
+ * Returns an array of property values from an array of objects. Returns undefined for missing properties.
+ *
+ * @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.
+ */
+declare function pluck<T, K extends keyof T>(array: readonly 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.
+ */
+declare function difference<T>(a: readonly T[], b: readonly 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.
+ */
+declare function intersect<T>(a: readonly T[], b: readonly 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").
+ * Optionally accepts a custom compare function or collator.
+ *
+ * @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'.
+ * @param {(a: T, b: T) => number} [compareFn] - Optional custom compare function.
+ * @returns {T[]} A new sorted array.
+ * @throws {TypeError} If array is not an array.
+ */
+declare function mergeSort<T>(array: readonly T[], key: string | ((item: T) => unknown), direction?: 'asc' | 'desc', compareFn?: (a: T, b: T) => number): T[];
+/**
+ * Combines multiple arrays into a single array of grouped elements.
+ * Output length equals the length of the shortest input array.
+ *
+ * This implementation ensures type safety and avoids holes in output.
+ *
+ * @example
+ * ```ts
+ * 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.
+ */
+declare function zip<T>(...arrays: ReadonlyArray<T>[]): T[][];
+/**
+ * Splits an array into two arrays based on a predicate function.
+ * Supports type-guard narrowing via overload.
+ *
+ * @template T The type of array elements.
+ * @overload
+ * @param {readonly T[]} array - The input array.
+ * @param {(item: T, index: number, array: readonly T[]) => item is U} predicate - Type guard predicate.
+ * @returns {[U[], Exclude<T, U>[]]} A tuple of two arrays: [matched, unmatched].
+ * @overload
+ * @param {readonly T[]} array - The input array.
+ * @param {(item: T, index: number, array: readonly T[]) => boolean} predicate - Boolean predicate.
+ * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].
+ */
+declare function partition<T, U extends T>(array: readonly T[], predicate: (item: T, index: number, array: readonly T[]) => item is U): [U[], Exclude<T, U>[]];
+declare function partition<T>(array: readonly T[], predicate: (item: T, index: number, array: readonly 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.
+ */
+declare function range(start: number, end: number, step?: number): number[];
+/**
+ * Returns the first `n` elements from 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.
+ */
+declare function take<T>(array: readonly T[], n?: number): T[];
+/**
+ * Takes elements from an array while predicate returns true.
+ *
+ * @template T The type of array elements.
+ * @param {readonly T[]} array - Input array.
+ * @param {(item: T, index: number) => boolean} predicate - Condition function.
+ * @returns {T[]} New array with taken elements.
+ *
+ * @example
+ * ```ts
+ * takeWhile([1,2,3,4], (n) => n < 3); // -> [1,2]
+ * ```
+ */
+declare function takeWhile<T>(array: readonly 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.
+ */
+declare function compact<T>(array: readonly 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) => StrNumSym} keyFn - Function to generate count key.
+ * @returns {Record<string, number>} Object with counts by key.
+ */
+declare function countBy<T>(array: readonly T[], keyFn: (item: T) => StrNumSym): Record<string, number>;
+/**
+ * Toggles an item in array (adds if not present, removes if present).
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {T} item
+ * @returns {T[]} New array with item toggled.
+ *
+ * @example
+ * ```ts
+ * toggle([1,2,3], 2); // -> [1,3]
+ * toggle([1,3], 2); // -> [1,3,2]
+ * ```
+ */
+declare function toggle<T>(array: readonly T[], item: T): T[];
+/**
+ * Returns a cryptographically secure random index for an array.
+ * Used internally for secure pick/shuffle operations.
+ *
+ * @param {number} max Upper bound (exclusive).
+ * @returns {number} A secure random integer in range `[0, max)`.
+ * @throws {RangeError} If `max` is not a positive number.
+ *
+ * @example
+ * ```ts
+ * secureIndex(10); // -> 3 (unpredictable)
+ * ```
+ */
+declare function secureIndex(max: number): number;
+/**
+ * Returns a secure random element from an array using Node crypto.
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @returns {T | undefined}
+ */
+declare const secureRandom: <T>(array: readonly T[]) => T | undefined;
+/**
+ * Returns the last element in the array that satisfies the provided testing function.
+ *
+ * @template T
+ * @param {readonly T[]} array - The input array.
+ * @param {(item: T, index: number, array: readonly T[]) => boolean} predicate - Function to test each element.
+ * @returns {T | undefined} The found element, or undefined if not found.
+ */
+declare function findLast<T>(array: readonly T[], predicate: (item: T, index: number, array: readonly T[]) => boolean): T | undefined;
+/**
+ * Returns the index of the last element in the array that satisfies the provided testing function.
+ *
+ * @template T
+ * @param {readonly T[]} array - The input array.
+ * @param {(item: T, index: number, array: readonly T[]) => boolean} predicate - Function to test each element.
+ * @returns {number} The index, or -1 if not found.
+ */
+declare function findLastIndex<T>(array: readonly T[], predicate: (item: T, index: number, array: readonly T[]) => boolean): number;
+/**
+ * Splits an array into chunks based on a predicate function.
+ * Each chunk starts when predicate returns true.
+ *
+ * @template T
+ * @param {readonly T[]} array - The input array.
+ * @param {(item: T, index: number, array: readonly T[]) => boolean} predicate - Function to determine chunk boundaries.
+ * @returns {T[][]} Array of chunked arrays.
+ */
+declare function chunkBy<T>(array: readonly T[], predicate: (item: T, index: number, array: readonly T[]) => boolean): T[][];
+/**
+ * Removes all occurrences of a value from an array.
+ *
+ * @template T
+ * @param {readonly T[]} array - The input array.
+ * @param {T} value - Value to remove.
+ * @returns {T[]} New array with value removed.
+ */
+declare function remove<T>(array: readonly T[], value: T): T[];
+/**
+ * Checks if an array is sorted in ascending or descending order.
+ *
+ * @template T
+ * @param {readonly T[]} array - The input array.
+ * @param {'asc' | 'desc'} [direction='asc'] - Sort direction.
+ * @param {(a: T, b: T) => number} [compareFn] - Optional compare function.
+ * @returns {boolean} True if sorted, false otherwise.
+ */
+declare function isSorted<T>(array: readonly T[], direction?: 'asc' | 'desc', compareFn?: (a: T, b: T) => number): boolean;
+/**
+ * Returns the first element of an array, or undefined if empty.
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @returns {T | undefined}
+ */
+declare function headOfArr<T>(array: readonly T[]): T | undefined;
+/**
+ * Returns the last element of an array, or undefined if empty.
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @returns {T | undefined}
+ */
+declare function lastOfArr<T>(array: readonly T[]): T | undefined;
+/**
+ * Drops the first n elements from an array.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {number} n - Number of elements to drop.
+ * @returns {T[]} Array with first n elements removed.
+ *
+ * @example
+ * drop([1, 2, 3, 4, 5], 2); // [3, 4, 5]
+ */
+declare function drop<T>(array: readonly T[], n: number): T[];
+/**
+ * Drops elements from the start of an array while predicate returns true.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {(item: T, index: number) => boolean} predicate - Condition function.
+ * @returns {T[]} Array with elements dropped.
+ *
+ * @example
+ * dropWhile([1, 2, 3, 4, 1], x => x < 3); // [3, 4, 1]
+ */
+declare function dropWhile<T>(array: readonly T[], predicate: (item: T, index: number) => boolean): T[];
+/**
+ * Finds the element with the maximum value for a given key or function.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {keyof T | ((item: T) => number)} keyOrFn - Property key or function.
+ * @returns {T | undefined} Element with maximum value.
+ *
+ * @example
+ * maxBy([{a: 1}, {a: 5}, {a: 3}], 'a'); // {a: 5}
+ * maxBy([{a: 1}, {a: 5}, {a: 3}], x => x.a); // {a: 5}
+ */
+declare function maxBy<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => number)): T | undefined;
+/**
+ * Finds the element with the minimum value for a given key or function.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {keyof T | ((item: T) => number)} keyOrFn - Property key or function.
+ * @returns {T | undefined} Element with minimum value.
+ *
+ * @example
+ * minBy([{a: 1}, {a: 5}, {a: 3}], 'a'); // {a: 1}
+ * minBy([{a: 1}, {a: 5}, {a: 3}], x => x.a); // {a: 1}
+ */
+declare function minBy<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => number)): T | undefined;
+
+export { chunk, chunkBy, compact, countBy, difference, drop, dropWhile, findLast, findLastIndex, flattenDeep, groupBy, headOfArr, intersect, isSorted, lastOfArr, maxBy, mergeSort, minBy, partition, pluck, random, range, remove, secureIndex, secureRandom, shuffle, take, takeWhile, toggle, unique, zip };