@catbee/utils 0.0.8-rc.3 → 1.0.1

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

@@ -1,167 +0,0 @@
-/**
- * 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>;

package/build/cjs/utils/array.utils.js

@@ -1,363 +0,0 @@
-"use strict";
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.chunk = chunk;
-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;
-exports.zip = zip;
-exports.partition = partition;
-exports.range = range;
-exports.take = take;
-exports.takeWhile = takeWhile;
-exports.compact = compact;
-exports.countBy = countBy;
-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.
- */
-function 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));
-}
-/**
- * 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);
-}
-/**
- * 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.
- */
-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;
-}
-/**
- * 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].
- */
-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]];
-    }, [[], []]);
-}
-/**
- * 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.
- */
-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;
-}
-/**
- * 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.
- */
-function take(array, n = 1) {
-    if (!Array.isArray(array) || n <= 0)
-        return [];
-    return array.slice(0, n);
-}
-/**
- * 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.
- */
-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;
-}
-/**
- * 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.
- */
-function compact(array) {
-    if (!Array.isArray(array))
-        return [];
-    return array.filter(Boolean);
-}
-/**
- * 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.
- */
-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;
-    }, {});
-}