@zenithui/utils/dist/lib/utils.d.ts

A collection of utility functions and hooks to simplify development in the ZenithUI ecosystem.

/**
 * Merges class names using clsx and twMerge.
 *
 * @param classes - Class names to merge.
 * @returns Merged class names.
 */
export declare function cn(...classes: (string | undefined | null | false | Record<string, boolean | null | undefined> | string[])[]): string;
type SortableKey<T> = keyof T;
/**
 * Sorts an array of objects by a specified key in ascending or descending order.
 *
 * @template T - The type of objects in the array.
 * @param array - The array of objects to be sorted.
 * @param key - The key of the object by which the array should be sorted. The key must exist in the objects.
 * @param order - The order of sorting, either "asc" for ascending or "desc" for descending. Defaults to "asc".
 * @returns A new array sorted by the specified key in the specified order.
 */
export declare function sortByKey<T>(array: T[], key: SortableKey<T>, order?: "asc" | "desc"): T[];
/**
 * Compares two values deeply to determine if they are equal.
 *
 * This utility function performs a deep comparison between two objects or values
 * to check if they are structurally identical. It handles nested objects, arrays,
 * and primitive types. If the values are not objects or one of them is `null`,
 * it performs a strict equality check.
 *
 * @param obj1 - The first value or object to compare.
 * @param obj2 - The second value or object to compare.
 * @returns `true` if the two values are deeply equal, otherwise `false`.
 */
export declare function deepEqual(obj1: unknown, obj2: unknown): boolean;
/**
 * Groups an array of objects by a specified key.
 *
 * @template T - The type of objects in the array.
 * @param array - The array of objects to be grouped.
 * @param key - The key by which to group the objects.
 * @returns An object where the keys are the values of the specified key and the values are arrays of grouped objects.
 */
export declare function groupBy<T, K extends keyof T>(array: T[], key: K): Record<string, T[]>;
/**
 * Removes duplicate objects from an array based on a specified key.
 *
 * @template T - The type of objects in the array.
 * @param array - The array to filter for unique objects.
 * @param key - The key to determine uniqueness.
 * @returns A new array containing only unique objects based on the specified key.
 */
export declare function uniqueByKey<T, K extends keyof T>(array: T[], key: K): T[];
/**
 * Creates a debounced function that delays execution until after a specified delay.
 *
 * @template T - The type of the function.
 * @param func - The function to debounce.
 * @param delay - The number of milliseconds to delay execution.
 * @returns A new debounced function.
 */
export declare function debounce<T extends (...args: unknown[]) => void>(func: T, delay: number): (...args: Parameters<T>) => void;
/**
 * Creates a throttled function that only invokes the provided function at most once per specified time interval.
 *
 * @template T - The type of the function.
 * @param func - The function to throttle.
 * @param limit - The time interval in milliseconds.
 * @returns A throttled function.
 */
export declare function throttle<T extends (...args: unknown[]) => void>(func: T, limit: number): (...args: Parameters<T>) => void;
/**
 * Creates a deep clone of an object.
 *
 * @template T - The type of the object.
 * @param obj - The object to clone.
 * @returns A deep copy of the object.
 */
export declare function cloneDeep<T>(obj: T): T;
/**
 * Picks specific keys from an object, returning a new object with only those keys.
 *
 * @template T - The type of the object.
 * @param obj - The source object.
 * @param keys - The keys to pick.
 * @returns A new object with only the picked keys.
 */
export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
/**
 * Omits specific keys from an object, returning a new object without those keys.
 *
 * @template T - The type of the object.
 * @param obj - The source object.
 * @param keys - The keys to omit.
 * @returns A new object without the omitted keys.
 */
export declare function omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
/**
 * Generates a random integer between min and max (inclusive).
 *
 * @param min - The minimum value.
 * @param max - The maximum value.
 * @returns A random integer between min and max.
 */
export declare function randomInt(min: number, max: number): number;
/**
 * Delays execution for a specified number of milliseconds.
 *
 * @param ms - The number of milliseconds to delay.
 * @returns A promise that resolves after the specified delay.
 */
export declare function sleep(ms: number): Promise<void>;
/**
 * Converts a byte size into a human-readable format (KB, MB, GB, etc.).
 *
 * @param bytes - The number of bytes.
 * @param decimals - The number of decimal places.
 * @returns A human-readable string.
 */
export declare function formatBytes(bytes: number, decimals?: number): string;
/**
 * Generates a UUID (v4).
 *
 * @returns A random UUID string.
 */
export declare function uuid(): string;
/**
 * Capitalizes the first letter of a string.
 *
 * @param str - The string to capitalize.
 * @returns The capitalized string.
 */
export declare function capitalize(str: string): string;
export {};