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.
256 lines (255 loc) • 10.3 kB
TypeScript
/**
* @module ObjectUtils
* @description A comprehensive collection of utility functions for object manipulation, transformation, and analysis.
* @example
* ```typescript
* import { ObjectUtils } from 'houser-js-utils';
*
* // Deep clone an object
* const cloned = ObjectUtils.cloneObject(originalObject);
*
* // Merge multiple objects
* const merged = ObjectUtils.merge(obj1, obj2, obj3);
*
* // Get nested property safely
* const value = ObjectUtils.getNestedProp(obj, 'user', 'profile', 'name');
* ```
*/
export declare const ObjectUtils: {
/**
* Creates a deep clone of an object, including nested objects and arrays.
* @template T - The type of the object to clone
* @param obj - The object to clone
* @returns A deeply cloned copy of the object
* @example
* ```typescript
* const original = { user: { name: 'John', hobbies: ['reading'] } };
* const cloned = ObjectUtils.cloneObject(original);
* cloned.user.name = 'Jane'; // Original remains unchanged
* ```
*/
cloneObject<T>(obj: T): T;
/**
* Performs a deep equality check between two values, comparing all nested properties.
* @param obj1 - The first value to compare
* @param obj2 - The second value to compare
* @returns True if the values are deeply equal, false otherwise
* @example
* ```typescript
* ObjectUtils.deepEqual({ a: { b: 1 } }, { a: { b: 1 } }); // Returns true
* ObjectUtils.deepEqual({ a: 1 }, { a: 2 }); // Returns false
* ObjectUtils.deepEqual([1, 2, 3], [1, 2, 3]); // Returns true
* ```
*/
deepEqual(obj1: unknown, obj2: unknown): boolean;
/**
* Filters an array of objects to unique values based on a specified property.
* @template T - The type of objects in the array
* @param objects - The array of objects to filter
* @param prop - The property to use for uniqueness comparison
* @returns An array containing only unique objects based on the specified property
* @example
* ```typescript
* const users = [
* { id: 1, name: 'John' },
* { id: 2, name: 'Jane' },
* { id: 1, name: 'John Doe' }
* ];
* ObjectUtils.filterUniqueByProp(users, 'id'); // Returns first two objects
* ```
*/
filterUniqueByProp<T extends Record<string, unknown>>(objects: T[], prop: keyof T): T[];
/**
* Filters an object to only include the specified keys.
* @param obj - The object to filter
* @param keys - An array of keys to include in the filtered object
* @returns A new object containing only the specified keys
* @example
* ```typescript
* const user = { id: 1, name: 'John', email: 'john@example.com', password: 'secret' };
* ObjectUtils.filterByKeys(user, ['id', 'name']); // Returns { id: 1, name: 'John' }
* ```
*/
filterByKeys(obj: Record<string, unknown>, keys: string[]): Record<string, unknown>;
/**
* Finds the index of the first non-zero value in an object of numbers.
* @param data - An object containing numeric values
* @returns The index of the first non-zero value, or -1 if all values are zero
* @example
* ```typescript
* ObjectUtils.findFirstNonZeroIndex({ a: 0, b: 0, c: 5, d: 2 }); // Returns 2
* ObjectUtils.findFirstNonZeroIndex({ a: 0, b: 0 }); // Returns -1
* ```
*/
findFirstNonZeroIndex(data: Record<string, number>): number;
/**
* Flattens a nested object into a single-level object with dot-notation keys.
* @param obj - The object to flatten
* @param prefix - The prefix to use for nested keys (default: empty string)
* @returns A flattened object with dot-notation keys
* @example
* ```typescript
* const nested = { user: { profile: { name: 'John', age: 30 } } };
* ObjectUtils.flatten(nested);
* // Returns { 'user.profile.name': 'John', 'user.profile.age': 30 }
* ```
*/
flatten(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
/**
* Converts a Map to a plain object
* @param map - Map to convert
* @returns Plain object
*/
fromMap<T>(map: Map<string, T> | Record<string, T>): Record<string, T>;
/**
* Gets a nested property from an object
* @param obj - Object to get property from
* @param path - Path to property
* @returns Property value or null if not found
*/
getNestedProp<T>(obj: Record<string, unknown>, ...path: string[]): T | null;
/**
* Groups objects by a property value
* @param objects - Array of objects to group
* @param propPath - Path to property to group by
* @returns Object with grouped arrays
*/
groupByProp<T extends Record<string, unknown>>(objects: T[], ...propPath: string[]): Record<string, T[]>;
/**
* Checks if an object has a nested property
* @param obj - Object to check
* @param path - Path to property
* @returns True if property exists
*/
hasNestedProp(obj: Record<string, unknown>, ...path: string[]): boolean;
/**
* Checks if an object is empty
* @param obj - Object to check
* @returns True if object is empty
*/
isEmpty(obj: unknown): boolean;
/**
* Checks if a value is a function
* @param value - Value to check
* @returns True if value is a function
*/
isFunction(value: unknown): value is Function;
/**
* Checks if two objects are equal using JSON stringification
* @param obj1 - First object to compare
* @param obj2 - Second object to compare
* @returns True if objects are equal
*/
isEqual(obj1: unknown, obj2: unknown): boolean;
/**
* Compares objects based on specified keys
* @param obj1 - First object to compare
* @param obj2 - Second object to compare
* @param keys - Array of keys to compare
* @returns True if objects are equal on specified keys
*/
isEqualOnKeys(obj1: Record<string, unknown>, obj2: Record<string, unknown>, keys: string[]): boolean;
/**
* Checks if a value is an object
* @param value - Value to check
* @returns True if value is an object
*/
isObject(value: unknown): value is Record<string, unknown>;
/**
* Maps objects by a property value
* @param objects - Array of objects to map
* @param propPath - Path to property to map by
* @returns Object with mapped values
*/
mapByProp<T extends Record<string, unknown>>(objects: T[], ...propPath: string[]): Record<string, T>;
/**
* Checks if an object conforms to a set of rules
* @param obj - Object to check
* @param ruleSet - Object containing validation functions
* @returns True if object conforms to all rules
*/
matchesRules<T extends Record<string, unknown>>(obj: T, ruleSet: Record<keyof T, (value: unknown) => boolean>): boolean;
/**
* Deep merges two or more objects
* @param objects - Objects to merge
* @returns Merged object
*/
merge<T extends Record<string, unknown>>(...objects: T[]): T;
/**
* Creates a new object with specified keys omitted
* @param obj - Object to omit keys from
* @param keys - Keys to omit
* @returns New object without specified keys
*/
omit<T extends Record<string, unknown>>(obj: T, keys: string[]): Partial<T>;
/**
* Creates a new object with only the specified keys
* @param obj - Object to pick from
* @param keys - Keys to pick
* @returns New object with only specified keys
*/
pick<T extends Record<string, unknown>>(obj: T, keys: string[]): Partial<T>;
/**
* Removes null, undefined, and optionally empty string values from an object
* @param obj - Object to clean
* @param noEmptyStrings - Whether to remove empty strings
* @returns Cleaned object
*/
removeNullishValues<T extends Record<string, unknown>>(obj: T, noEmptyStrings?: boolean): Partial<T>;
/**
* Replaces empty strings with null in an object
* @param obj - Object to process
* @param deep - Whether to process nested objects
* @returns Processed object
*/
replaceEmptyStringsWithNull(obj: Record<string, unknown>, deep?: boolean): Record<string, unknown>;
/**
* Replaces a key in an object
* @param obj - Object to modify
* @param oldKey - Key to replace
* @param newKey - New key name
* @returns New object with replaced key
*/
replaceKey<T extends Record<string, unknown>>(obj: T, oldKey: keyof T, newKey: string): Record<string, unknown>;
/**
* Replaces null values with empty strings in an object
* @param obj - Object to process
* @param fields - Optional array of fields to process
* @returns Processed object
*/
replaceNullWithEmptyString(obj: Record<string, unknown>, fields?: string[]): Record<string, unknown>;
/**
* Sets a nested property in an object
* @param obj - Object to modify
* @param path - Path to property
* @param value - Value to set
* @returns New object with set property
*/
setNestedProp<T extends Record<string, unknown>>(obj: T, ...path: [...string[], unknown]): T | null;
/**
* Sorts an array of objects by a property
* @param objects - Array of objects to sort
* @param prop - Property to sort by
* @param direction - Sort direction
* @returns Sorted array
*/
sortByProp<T extends Record<string, unknown>>({ objects, prop, direction, }: {
objects: T[];
prop: keyof T;
direction?: "asc" | "desc";
}): T[];
/**
* Converts an object to a Map
* @param obj - Object to convert
* @returns Map
*/
toMap<T>(obj: Record<string, T>): Map<string, T>;
/**
* Transforms an object's keys and/or values
* @param obj - Object to transform
* @param keyTransform - Function to transform keys
* @param valueTransform - Function to transform values
* @returns Transformed object
*/
transform<T extends Record<string, unknown>>(obj: T, keyTransform?: (key: string) => string, valueTransform?: (value: unknown) => unknown): Record<string, unknown>;
};