houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
210 lines (209 loc) • 7.4 kB
TypeScript
/**
* @module ArrayUtils
* @description A collection of utility functions for array manipulation and operations.
* @example
* ```typescript
* import { ArrayUtils } from 'houser-js-utils';
*
* // Get unique values from an array
* const unique = ArrayUtils.deduplicate([1, 2, 2, 3]);
*
* // Find maximum value
* const max = ArrayUtils.findMax([1, 5, 3, 2]);
* ```
*/
/**
* Options for array comparison operations
*/
type CompareOptions = {
/** If true, elements must be in the same order. Defaults to false */
ordered?: boolean;
/** If true, performs deep equality comparison. Defaults to false */
deep?: boolean;
};
/**
* Represents an entity with an ID field
*/
type EmbeddedEntity = {
/** Unique identifier for the entity */
id: string;
/** Additional properties of the entity */
[key: string]: any;
};
/**
* Types that can be compared using standard comparison operators
*/
type Comparable = string | number | boolean;
/**
* Collection of array utility functions
*/
export declare const ArrayUtils: {
/**
* Calculates the average of all numbers in an array
* @param arr - Array of numbers to calculate average from
* @returns The average of all numbers, or 0 if array is empty
* @example
* ```typescript
* const avg = ArrayUtils.average([1, 2, 3, 4, 5]); // Returns 3
* ```
*/
average(arr: number[]): number;
/**
* Compares two arrays for equality by sorting and comparing elements
* @param a1 - First array to compare
* @param a2 - Second array to compare
* @returns True if arrays contain the same elements in any order
* @example
* ```typescript
* const equal = ArrayUtils.arrayEquals([1, 2, 3], [3, 2, 1]); // Returns true
* ```
*/
arrayEquals<T extends Comparable>(a1: T[], a2: T[]): boolean;
/**
* Splits an array into chunks of specified size
* @param arr - Array to split into chunks
* @param size - Size of each chunk (must be positive)
* @returns Array of arrays, each of size 'size'
* @throws Error if size is not positive
*/
chunks<T>(arr: T[], size: number): T[][];
/**
* Compares two arrays for equality based on the given options
* @param arr1 - First array to compare
* @param arr2 - Second array to compare
* @param options - Comparison options
* @returns True if arrays are equal based on the options
*/
compareArrays<T>(arr1: T[], arr2: T[], options?: CompareOptions): boolean;
/**
* Returns a new array with unique values
* @param array - Array to make unique
* @returns Array with duplicate values removed
*/
deduplicate<T>(array: T[]): T[];
/**
* Deep equality comparison between two values
* @param a - First value
* @param b - Second value
* @returns True if values are deeply equal
*/
deepEqual(a: unknown, b: unknown): boolean;
/**
* Returns elements from array a that are not in array b based on id property
* @param a - First array
* @param b - Second array
* @param getId - Optional function to extract id from items
* @returns Array of elements from a that are not in b
*/
difference<T>(a: T[], b: T[], getId?: (item: T) => string | number): T[];
/**
* Returns the maximum value in an array
* @param arr - Array of comparable values
* @returns Maximum value or undefined if array is empty
*/
findMax<T extends Comparable>(arr: T[]): T | undefined;
/**
* Returns the minimum value in an array
* @param arr - Array of comparable values
* @returns Minimum value or undefined if array is empty
*/
findMin<T extends Comparable>(arr: T[]): T | undefined;
/**
* Finds and updates an item in a collection based on id
* @param collection - Collection to update
* @param item - Item to update
* @returns Updated collection
* @throws Error if item is not found
*/
findAndUpdate(collection: EmbeddedEntity[], item: EmbeddedEntity): EmbeddedEntity[];
/**
* Flattens a nested array to a specified depth
* @param arr - Array to flatten
* @param depth - Maximum depth to flatten (default: Infinity)
* @returns Flattened array
*/
flatten<T>(arr: T[], depth?: number): T[];
/**
* Groups array elements by a key or function
* @param arr - Array to group
* @param keyOrFn - Key to group by or function that returns the group key
* @returns Object with grouped arrays
*/
groupBy<T>(arr: T[], keyOrFn: keyof T | ((item: T) => string | number)): Record<string, T[]>;
/**
* Checks if two arrays have any common elements
* @param array1 - First array
* @param array2 - Second array
* @returns True if arrays share at least one common element
*/
hasCommonElement<T>(array1: T[], array2: T[]): boolean;
/**
* Returns the intersection of two arrays
* @param arr1 - First array
* @param arr2 - Second array
* @returns Array containing elements present in both arrays
*/
intersection<T>(arr1: T[], arr2: T[]): T[];
/**
* Moves an item from one position to another in an array
* @param arr - Array to modify
* @param from - Source index
* @param to - Destination index
* @returns New array with item moved
* @throws Error if indices are out of bounds
*/
moveItem<T>(arr: T[], from: number, to: number): T[];
/**
* Returns a random element from the array
* @param arr - Array to get element from
* @returns Random element or undefined if array is empty
*/
random<T>(arr: T[]): T | undefined;
/**
* Removes elements from an array that match a predicate
* @param arr - Array to remove elements from
* @param predicate - Function that returns true for elements to remove
* @returns New array with matching elements removed
*/
remove<T>(arr: T[], predicate: (item: T) => boolean): T[];
/**
* Returns a new array with elements in random order
* @param arr - Array to shuffle
* @returns New array with elements in random order
*/
shuffle<T>(arr: T[]): T[];
/**
* Compares two values for sorting
* @param x - First value to compare
* @param y - Second value to compare
* @returns -1 if x < y, 0 if equal, 1 if x > y
*/
sortCompare(x: Comparable, y: Comparable): number;
/**
* Returns the sum of all numbers in an array
* @param arr - Array of numbers
* @returns Sum of all numbers
*/
sumArray(arr: number[]): number;
/**
* Returns the first n elements of an array
* @param arr - Array to get elements from
* @param n - Number of elements to get (default: 1)
* @returns Array containing the first n elements
*/
takeFirst<T>(arr: T[], n?: number): T[];
/**
* Returns the last n elements of an array
* @param arr - Array to get elements from
* @param n - Number of elements to get (default: 1)
* @returns Array containing the last n elements
*/
takeLast<T>(arr: T[], n?: number): T[];
/**
* Returns the union of multiple arrays
* @param arrays - Arrays to union
* @returns Array containing unique elements from all arrays
*/
union<T>(...arrays: T[][]): T[];
};
export {};