@utilify/core/dist/index.d.ts

Modern, strongly typed, and safe utility function library for JavaScript and TypeScript. Includes type checking, manipulation of arrays, objects, strings, dates, colors, numbers, regular expressions, and more. Compatible with Browser, Node.js, Deno, and B

/**
 * @callback AdjustCallback
 * @template T
 * @param {T} value - The value to adjust.
 * @returns {T} The adjusted value.
 */
/**
 * Applies a function to the element at the specified index of an array and returns a new array.
 * If the index is negative or out of bounds, it wraps around using modulo.
 * @template T
 * @param {T[]} array - The array to adjust.
 * @param {number} index - The index of the element to adjust.
 * @param {AdjustCallback} fn - The function to apply to the element.
 * @returns {T[]} A new array with the adjusted element.
 * @throws {TypeError} If array is not an array, index is not a number, or fn is not a function.
 */
declare function adjust<T>(array: T[], index: number, fn: (value: T) => T): T[];

/**
 * Returns elements after a given index in a string.
 * @param {string} string - The string to slice.
 * @param {number} index - The index.
 * @returns {string} The substring after the index.
 * @throws {TypeError} If input is not array-like or index is invalid.
 */
declare function after(string: string, index: number): string;
/**
 * Returns elements after a given index in an array.
 * @template T
 * @param {T[]} array - The array to slice.
 * @param {number} index - The index.
 * @returns {T[]} The elements after the index.
 * @throws {TypeError} If input is not array-like or index is invalid.
 */
declare function after<T>(array: T[], index: number): T[];

/**
 * Returns all subarrays of a given size (window) from an array.
 * @template T
 * @param {T[]} array - The array to window.
 * @param {number} [size=1] - The window size.
 * @returns {T[][]} Array of windows.
 * @throws {TypeError} If array is not an array or size is invalid.
 */
declare function aperture<T>(array: T[], size?: number): T[][];

/**
 * Appends a value to the end of an array and returns a new array.
 * @template T
 * @param {T[]} array - The array to append to.
 * @param {T} value - The value to append.
 * @returns {T[]} The new array with the value appended.
 * @throws {TypeError} If array is not an array.
 */
declare function append<T>(array: T[], value: T): T[];

/**
 * @callback ArrayToObjectKeyFn
 * @template T,K
 * @param {T} item - The item in the array.
 * @param {number} index - The index of the item.
 * @param {T[]} array - The array.
 * @returns {K} The key for the object.
 */
/**
 * @callback ArrayToObjectValueFn
 * @template T
 * @param {T} item - The item in the array.
 * @param {number} index - The index of the item.
 * @param {T[]} array - The array.
 * @returns {T} The value for the object.
 */
/**
 * Converts an array to an object using key and value selector functions.
 * @template T,K
 * @param {T[]} array - The array to convert.
 * @param {ArrayToObjectKeyFn} [keyFn] - Function to select keys.
 * @param {ArrayToObjectValueFn} [valueFn] - Function to select values.
 * @returns {Record<K, any>} The resulting object.
 * @throws {TypeError} If array is not an array or selectors are not functions.
 */
declare function arrayToObject<T, K extends PropertyKey>(array: T[], keyFn?: (item: T, index: number, array: T[]) => K, valueFn?: (item: T, index: number, array: T[]) => T): Record<K, any>;

/**
 * Returns elements before a given index in a string.
 * @param {string} string - The string to slice.
 * @param {number} index - The index.
 * @returns {string} The substring before the index.
 * @throws {TypeError} If input is not array-like or index is invalid.
 */
declare function before(string: string, index: number): string;
/**
 * Returns elements before a given index in an array.
 * @template T
 * @param {T[]} array - The array to slice.
 * @param {number} index - The index.
 * @returns {T[]} The elements before the index.
 * @throws {TypeError} If input is not array-like or index is invalid.
 */
declare function before<T>(array: T[], index: number): T[];

/**
 * Splits a string into chunks of a given size.
 * @param {string} string - The string to chunk.
 * @param {number} size - The chunk size.
 * @returns {string[]} Array of string chunks.
 * @throws {TypeError} If input is not array-like or size is invalid.
 */
declare function chunk(string: string, size: number): string[];
/**
 * Splits an array into chunks of a given size.
 * @template T
 * @param {T[]} array - The array to chunk.
 * @param {number} size - The chunk size.
 * @returns {T[][]} Array of array chunks.
 * @throws {TypeError} If input is not array-like or size is invalid.
 */
declare function chunk<T>(array: T[], size: number): T[][];

/**
 * @callback CollectByKeySelector
 * @template T,K
 * @param {T} value - The item in the array.
 * @param {number} index - The index of the item.
 * @returns {K} The key for grouping.
 */
/**
 * Collects array elements into groups by a key selector function.
 * @template T,K
 * @param {T[]} array - The array to collect from.
 * @param {CollectByKeySelector} keySelector - Function to select group key.
 * @returns {T[][]} Array of grouped arrays.
 * @throws {TypeError} If array is not an array or keySelector is not a function.
 */
declare function collectBy<T, K extends PropertyKey>(array: T[], keySelector: (value: T, index: number) => K): T[][];

/**
 * Returns a new array with all falsy values removed.
 * @template T
 * @param {T[]} array - The array to compact.
 * @returns {T[]} Array with falsy values removed.
 * @throws {TypeError} If array is not an array.
 */
declare function compact<T>(array: T[]): T[];

/**
 * Counts the number of elements matching a predicate.
 * @template T
 * @param {T[]} array - The array to count from.
 * @param {(item: T) => boolean} predicate - The predicate function.
 * @returns {number} The count of matching elements.
 * @throws {TypeError} If array is not an array or predicate is not a function.
 */
declare function count<T>(array: T[], predicate: (item: T) => boolean): number;

/**
 * Returns a function that cycles through array elements.
 * @template T
 * @param {T[]} array - The array to cycle through.
 * @returns {() => T | undefined} Function that returns the next element.
 * @throws {TypeError} If array is not an array.
 */
declare function cycle<T>(array: T[]): () => T | undefined;

/**
 * Returns the difference between two arrays (elements in array1 not in array2).
 * @template T
 * @param {T[]} array1 - The first array.
 * @param {T[]} array2 - The second array.
 * @returns {T[]} Array of elements in array1 not in array2.
 * @throws {TypeError} If either argument is not an array.
 */
declare function difference<T>(array1: T[], array2: T[]): T[];

/**
 * Returns the first N elements of a string.
 * @param {string} string - The string to slice.
 * @param {number} [count] - Number of elements to return.
 * @returns {string} The first N characters.
 * @throws {TypeError} If input is not array-like or count is invalid.
 */
declare function first(string: string, count?: number): string;
/**
 * Returns the first N elements of an array.
 * @template T
 * @param {T[]} array - The array to slice.
 * @param {number} [count] - Number of elements to return.
 * @returns {T[]} The first N elements.
 * @throws {TypeError} If input is not array-like or count is invalid.
 */
declare function first<T>(array: T[], count?: number): T[];

/**
 * Maps each array element and flattens the result one level.
 * @template T,U
 * @param {T[]} array - The array to map.
 * @param {(value: T, index: number, array: T[]) => U | U[]} fn - The mapping function.
 * @returns {U[]} The mapped and flattened array.
 * @throws {TypeError} If array is not an array or fn is not a function.
 */
declare function flatMap<T, U>(array: T[], fn: (value: T, index: number, array: T[]) => U | U[]): U[];

/**
 * Flattens an array up to a specified depth.
 * @template T
 * @param {T[]} array - The array to flatten.
 * @param {number} [depth=Infinity] - The depth to flatten.
 * @returns {FlatArray<T[], number>[]} The flattened array.
 * @throws {TypeError} If array is not an array or depth is invalid.
 */
declare function flat<T>(array: T[], depth?: number): FlatArray<T[], number>[];

/**
 * @callback GroupByKeySelector
 * @template T,K
 * @param {T} value - The item in the array.
 * @param {number} index - The index of the item.
 * @returns {K} The key for grouping.
 */
/**
 * Groups array elements by a key selector function.
 * @template T,K
 * @param {T[]} array - The array to group.
 * @param {GroupByKeySelector} [keySelector] - Function to select group key.
 * @returns {Record<K, T[]>} Object with grouped arrays.
 * @throws {TypeError} If array is not an array or keySelector is not a function.
 */
declare function groupBy<T, K extends PropertyKey>(array: T[], keySelector?: (value: T, index: number) => K): Record<K, T[]>;

/**
 * Checks if an array includes a value using deep equality.
 * @template T
 * @param {T[]} array - The array to search.
 * @param {T} value - The value to find.
 * @returns {boolean} True if value is found, false otherwise.
 * @throws {TypeError} If array is not an array.
 */
declare function includes<T>(array: T[], value: T): boolean;

/**
 * Checks if a value is iterable.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is iterable, false otherwise.
 */
declare function isIterable(value: any): value is Iterable<any>;

/**
 * Returns the last N elements of a string.
 * @param {string} string - The string to slice.
 * @param {number} [count] - Number of elements to return.
 * @returns {string} The last N characters.
 * @throws {TypeError} If input is not array-like or count is invalid.
 */
declare function last(string: string, count?: number): string;
/**
 * Returns the last N elements of an array.
 * @template T
 * @param {T[]} array - The array to slice.
 * @param {number} [count] - Number of elements to return.
 * @returns {T[]} The last N elements.
 * @throws {TypeError} If input is not array-like or count is invalid.
 */
declare function last<T>(array: T[], count?: number): T[];

/**
 * Returns a new array with elements that do NOT match the predicate.
 * @template T
 * @param {T[]} array - The array to filter.
 * @param {(value: T, index?: number, array?: T[]) => boolean} fn - The predicate function.
 * @returns {T[]} Array of rejected values.
 * @throws {TypeError} If array is not an array or fn is not a function.
 */
declare function reject<T>(array: T[], fn: (value: T, index?: number, array?: T[]) => boolean): T[];

/**
 * Repeats a value a specified number of times.
 * @template T
 * @param {T} value - The value to repeat.
 * @param {number} count - The number of times to repeat.
 * @returns {T[]} Array of repeated values.
 * @throws {TypeError|RangeError} If count is invalid.
 */
declare function repeat<T>(value: T, count: number): T[];
/**
 * Repeats a string a specified number of times.
 * @param {string} value - The string to repeat.
 * @param {number} count - The number of times to repeat.
 * @returns {string} The repeated string.
 * @throws {TypeError|RangeError} If count is invalid.
 */
declare function repeat(value: string, count: number): string;

/**
 * Rotates the elements of an array by a given offset.
 * @template T
 * @param {T[]} array - The array to rotate.
 * @param {number} offset - The offset to rotate by.
 * @returns {T[]} The rotated array.
 * @throws {TypeError} If array is not an array or offset is not a number.
 */
declare function rotate<T>(array: T[], offset: number): T[];

/**
 * Returns a random element from an array.
 * @template T
 * @param {T[]} array - The array to sample from.
 * @returns {T|undefined} A random element or undefined if empty.
 * @throws {TypeError} If array is not an array.
 */
declare function sample<T>(array: T[]): T | undefined;

/**
 * Shuffles the elements of an array in place.
 * @template T
 * @param {T[]} array - The array to shuffle.
 * @returns {T[]} The shuffled array.
 * @throws {TypeError} If array is not an array.
 */
declare function shuffle<T>(array: T[]): T[];

/**
 * Swaps two elements in an array by index.
 * @template T
 * @param {T[]} array - The array to modify.
 * @param {number} fromIndex - The index of the first element.
 * @param {number} toIndex - The index of the second element.
 * @returns {T[]} The array with swapped elements.
 * @throws {TypeError|RangeError} If arguments are invalid.
 */
declare function swap<T>(array: T[], fromIndex: number, toIndex: number): T[];

/**
 * Returns the union of multiple arrays (unique values).
 * @template T
 * @param {...T[][]} arrays - Arrays to union.
 * @returns {T[]} Array of unique values from all arrays.
 * @throws {TypeError} If any argument is not an array.
 */
declare function union<T>(...arrays: T[][]): T[];

/**
 * Returns a new array with only unique values.
 * @template T
 * @param {T[]} array - The array to filter.
 * @returns {T[]} Array of unique values.
 * @throws {TypeError} If array is not an array.
 */
declare function unique<T>(array: T[]): T[];

/**
 * Unzips an array of grouped elements into separate arrays.
 * @template T
 * @param {T[][]} zip - The zipped array.
 * @returns {T[][]} Unzipped arrays.
 * @throws {TypeError} If zip or its elements are not arrays.
 */
declare function unzip<T>(zip: T[][]): T[][];

/**
 * Zips multiple arrays together, grouping elements by index.
 * @template T
 * @param {...T[][]} arrays - Arrays to zip.
 * @returns {T[][]} Zipped array of groups.
 * @throws {TypeError} If any argument is not an array.
 */
declare function zip<T>(...arrays: T[][]): T[][];

/**
 * Exits fullscreen mode in the browser.
 * @returns {Promise<void>} Resolves when fullscreen is exited.
 * @throws {Error} If fullscreen API is not supported.
 */
declare function exitFullscreen(): Promise<void>;

/**
 * Gets the user's preferred language (ISO 639-1 code).
 * @returns {string|undefined} The language code or undefined if server.
 */
declare function getLanguage(): string | undefined;

/**
 * Gets the user's preferred color scheme ('dark' or 'light').
 * @returns {'dark' | 'light' | undefined} The theme or undefined if server.
 */
declare function getTheme(): 'dark' | 'light';

/**
 * Checks if cookies are enabled in the browser.
 * @returns {boolean|undefined} True if enabled, false if not, undefined if server.
 */
declare function isCookieEnabled(): boolean | undefined;

/**
 * Checks if the fullscreen API is enabled in the browser.
 * @returns {boolean|undefined} True if enabled, false if not, undefined if server.
 */
declare function isFullscreenEnabled(): boolean;

/**
 * Checks if the browser is currently online.
 * @returns {boolean|undefined} True if online, false if not, undefined if server.
 */
declare function isOnline(): boolean | undefined;

/**
 * Checks if the Web Share API is available and the data is shareable.
 * @param {ShareData} [data] - The data to check.
 * @returns {boolean} True if shareable, false otherwise.
 */
declare function isShareable(data?: ShareData): boolean;

/**
 * Checks if the browser tab is currently active (visible).
 * @returns {boolean|undefined} True if tab is active, false if not, undefined if server.
 */
declare function isTabActive(): boolean;

/**
 * Checks if the current device supports touch events.
 * @returns {boolean|undefined} True if touch device, false if not, undefined if server.
 */
declare function isTouchDevice(): boolean | undefined;

/**
 * Registers an event listener and returns a function to remove it.
 * @template T
 * @param {T} target - The event target.
 * @param {string} event - The event name.
 * @param {(this: T, ev: Event) => any} listener - The event listener.
 * @param {boolean|AddEventListenerOptions} [options] - Listener options.
 * @returns {() => void} Function to remove the listener.
 */
declare function on<T extends Window | Document | HTMLElement | EventTarget>(target: T, event: keyof WindowEventMap | keyof DocumentEventMap | keyof HTMLElementEventMap, listener: (this: T, ev: Event) => any, options?: boolean | AddEventListenerOptions): () => void;

/**
 * Registers a listener for the offline event.
 * @param {() => void} listener - The callback.
 * @returns {() => void} Function to remove the listener.
 */
declare function onOffline(listener: () => void): () => void;

/**
 * Registers a listener for the online event.
 * @param {() => void} listener - The callback.
 * @returns {() => void} Function to remove the listener.
 */
declare function onOnline(listener: () => void): () => void;

/**
 * Registers a listener for document visibility changes.
 * @param {(visibilityState: Document['visibilityState']) => void} listener - The callback.
 * @returns {() => void} Function to remove the listener.
 */
declare function onVisibilityChange(listener: (visibilityState: Document['visibilityState']) => void): () => void;

/**
 * Requests fullscreen mode for a given element.
 * @param {Element} element - The element to make fullscreen.
 * @returns {Promise<void>} Resolves when fullscreen is entered.
 * @throws {Error} If fullscreen API is not supported.
 */
declare function requestFullscreen(element: Element): Promise<void>;

/**
 * Scrolls an element into view with boolean options.
 * @param {HTMLElement} element - The element to scroll to.
 * @param {boolean} [options] - Scroll options.
 * @returns {void}
 */
declare function scrollToElement(element: HTMLElement, options?: boolean): void;
/**
 * Scrolls an element into view with ScrollIntoViewOptions.
 * @param {HTMLElement} element - The element to scroll to.
 * @param {ScrollIntoViewOptions} [options] - Scroll options.
 * @returns {void}
 */
declare function scrollToElement(element: HTMLElement, options?: ScrollIntoViewOptions): void;

/**
 * Scrolls the window to the top of the page.
 * @param {ScrollBehavior} [behavior='smooth'] - The scroll behavior.
 * @returns {void}
 */
declare function scrollToTop(behavior?: ScrollBehavior): void;

/**
 * Shares data using the Web Share API.
 * @param {ShareData} data - The data to share.
 * @returns {Promise<void>} Resolves when sharing is complete.
 * @throws {Error} If Web Share API is not available or data is not shareable.
 */
declare function share(data: ShareData): Promise<void>;

type ParsedColor = {
    model: "rgb" | "hsl";
    values: [number, number, number];
    alpha?: number;
} | null;
/**
 * Parses a color string (hex, rgb, rgba, hsl, hsla) into its components.
 * @param {string} color - The color string to parse.
 * @returns {ParsedColor} The parsed color object or null if invalid.
 * @throws {TypeError} If color is not a string.
 */
declare function parseColor(color: string): ParsedColor;

/**
 * Converts a hex color string to an HSL color string.
 * @param {string} hex - The hex color string.
 * @returns {string} The HSL color string.
 * @throws {Error} If hex is not a valid hex color.
 */
declare function hexToHsl(hex: string): string;

/**
 * Converts a hex color string to an RGB(A) color string.
 * @param {string} hex - The hex color string.
 * @returns {string} The RGB(A) color string.
 * @throws {Error} If hex is not a valid hex color.
 */
declare function hexToRgb(hex: string): string;

/**
 * Converts an HSL color string to a hex color string.
 * @param {string} hsl - The HSL color string.
 * @returns {string} The hex color string.
 * @throws {Error} If hsl is not a valid HSL color.
 */
declare function hslToHex(hsl: string): string;

/**
 * Converts an HSL(A) color string to an RGB(A) color string.
 * @param {string} hsl - The HSL(A) color string.
 * @returns {string} The RGB(A) color string.
 * @throws {Error} If hsl is not a valid HSL color.
 */
declare function hslToRgb(hsl: string): string;

/**
 * Checks if a string is a valid hex color.
 * @param {string} hex - The string to check.
 * @returns {boolean} True if valid hex color, false otherwise.
 */
declare function isHexColor(hex: string): boolean;

/**
 * Checks if a string is a valid HSL or HSLA color.
 * @param {string} hsl - The string to check.
 * @returns {boolean} True if valid HSL(A), false otherwise.
 */
declare function isHslColor(hsl: string): boolean;

/**
 * Checks if a string is a valid RGB or RGBA color.
 * @param {string} rgb - The string to check.
 * @returns {boolean} True if valid RGB(A), false otherwise.
 */
declare function isRgbColor(rgb: string): boolean;

/**
 * Converts an RGB(A) color string to a hex color string.
 * @param {string} rgb - The RGB(A) color string.
 * @returns {string} The hex color string.
 * @throws {Error} If rgb is not a valid RGB color.
 */
declare function rgbToHex(rgb: string): string;

/**
 * Converts an RGB color string to an HSL color string.
 * @param {string} rgb - The RGB color string.
 * @returns {string} The HSL color string.
 * @throws {Error} If rgb is not a valid RGB color.
 */
declare function rgbToHsl(rgb: string): string;

type Format = "hex" | "rgb" | "hsl";
/**
 * Generates a random color string in the specified format.
 * @param {Format} [format="rgb"] - The color format ("hex", "rgb", "hsl").
 * @param {boolean} alpha - Whether to include alpha channel.
 * @returns {string} The random color string.
 * @throws {Error} If format is invalid.
 */
declare function randomColor(format: Format | undefined, alpha: boolean): string;

/**
 * Decodes a base64 or base64url string into a Uint8Array.
 * @param {string} input - The string to decode.
 * @param {boolean} [urlSafe=false] - Whether the input is base64url.
 * @returns {Uint8Array} The decoded bytes.
 * @throws {Error} If input is not valid base64/base64url or no decoder is available.
 */
declare function base64Decode(input: string, urlSafe?: boolean): Uint8Array;

/**
 * Encodes a Uint8Array or ArrayBuffer as a base64 or base64url string.
 * @param {Uint8Array|ArrayBuffer} input - The data to encode.
 * @param {boolean} [urlSafe=false] - Whether to use base64url encoding.
 * @returns {string} The encoded string.
 * @throws {Error} If no encoder is available.
 */
declare function base64Encode(input: Uint8Array | ArrayBuffer, urlSafe?: boolean): string;

/**
 * Computes the djb2 hash of a string.
 * @param {string} str - The string to hash.
 * @returns {number} The hash value.
 * @throws {TypeError} If str is not a string.
 */
declare function djb2(str: string): number;

/**
 * Generates a random nonce as a Uint8Array.
 * @param {number} [length=16] - The length of the nonce.
 * @returns {Uint8Array} The generated nonce.
 * @throws {Error} If length is not a positive multiple of 8.
 */
declare function generateNonce(length?: number): Uint8Array;

/**
 * Generates a random UUID (version 4).
 * @returns {string} The generated UUID.
 */
declare function generateUUID(): string;

/**
 * Decodes a hexadecimal string into a Uint8Array.
 * @param {string} hex - The hex string to decode.
 * @returns {Uint8Array} The decoded bytes.
 * @throws {Error} If hex is not valid or has odd length.
 */
declare function hexDecode(hex: string): Uint8Array;

/**
 * Encodes a Uint8Array or ArrayBuffer as a hexadecimal string.
 * @param {ArrayBuffer|Uint8Array} data - The data to encode.
 * @returns {string} The hex string.
 */
declare function hexEncode(data: ArrayBuffer | Uint8Array): string;

/**
 * Checks if a value is an ArrayBuffer.
 * @param {unknown} input - The value to check.
 * @returns {boolean} True if input is an ArrayBuffer, false otherwise.
 */
declare function isArrayBuffer(input: unknown): input is ArrayBuffer;

/**
 * Checks if a string is a valid base64 string.
 * @param {string} value - The string to check.
 * @returns {boolean} True if valid base64, false otherwise.
 * @throws {TypeError} If value is not a string.
 */
declare function isBase64(value: string): boolean;

/**
 * Checks if a string is a valid base64url string.
 * @param {string} value - The string to check.
 * @returns {boolean} True if valid base64url, false otherwise.
 * @throws {TypeError} If value is not a string.
 */
declare function isBase64URL(value: string): boolean;

type HashAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
/**
 * Checks if a string is a valid hash for the given algorithm.
 * @param {string} hash - The hash string to check.
 * @param {HashAlgorithm} [algorithm='SHA-256'] - The hash algorithm.
 * @returns {boolean} True if valid hash, false otherwise.
 * @throws {TypeError|Error} If hash is not a string or algorithm is invalid.
 */
declare function isHash(hash: string, algorithm?: HashAlgorithm): boolean;

/**
 * Checks if a string is a valid hexadecimal string.
 * @param {string} value - The string to check.
 * @returns {boolean} True if valid hex, false otherwise.
 * @throws {TypeError} If value is not a string.
 */
declare function isHex(value: string): boolean;

/**
 * Checks if a value is a Uint8Array.
 * @param {unknown} input - The value to check.
 * @returns {boolean} True if input is a Uint8Array, false otherwise.
 */
declare function isUint8Array(input: unknown): input is Uint8Array;

/**
 * Checks if a string is a valid UUID (version 4).
 * @param {string} value - The string to check.
 * @returns {boolean} True if valid UUID, false otherwise.
 * @throws {TypeError} If value is not a string.
 */
declare function isUUID(value: string): boolean;

/**
 * Decodes a Uint8Array or ArrayBuffer as a UTF-8 string.
 * @param {ArrayBuffer|Uint8Array} data - The data to decode.
 * @returns {string} The decoded string.
 * @throws {Error} If no decoder is available.
 */
declare function utf8Decode(data: ArrayBuffer | Uint8Array): string;

/**
 * Encodes a string as UTF-8 and returns a Uint8Array.
 * @param {string} input - The string to encode.
 * @returns {Uint8Array} The UTF-8 encoded bytes.
 * @throws {TypeError|Error} If input is not a string or no encoder is available.
 */
declare function utf8Encode(input: string): Uint8Array;

/**
 * Adjusts a date by adding or subtracting years, months, days, hours, minutes, seconds, or milliseconds.
 * @param {Date} date - The date to adjust.
 * @param {Partial<{years: number, months: number, days: number, hours: number, minutes: number, seconds: number, milliseconds: number}>} adjustment - The adjustment object.
 * @returns {Date} The adjusted date.
 * @throws {TypeError} If date is not valid.
 */
declare function adjustDate(date: Date, adjustment: Partial<{
    years: number;
    months: number;
    days: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
}>): Date;

/**
 * Adjusts a date to a target timezone offset.
 * @param {Date} date - The date to adjust.
 * @param {number} targetTimezone - The target timezone offset (in hours).
 * @returns {Date} The adjusted date.
 * @throws {TypeError} If date is not valid.
 */
declare function adjustTimezone(date: Date, targetTimezone: number): Date;

type DateFormat$1 = "timestamp" | "string" | "utc" | "iso";
/**
 * Converts a Date object to a string or number in the specified format.
 * @param {Date} date - The date to convert.
 * @param {DateFormat} [format="iso"] - The format ("timestamp", "string", "utc", "iso").
 * @returns {string|number} The converted value.
 * @throws {TypeError} If date is not valid.
 */
declare function convertDateTo(date: Date, format?: DateFormat$1): string | number;

type TimeUnit$1 = "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "years";
/**
 * Converts a time value from one unit to another.
 * @param {number} time - The time value.
 * @param {TimeUnit} from - The unit to convert from.
 * @param {TimeUnit} to - The unit to convert to.
 * @returns {number} The converted time value.
 * @throws {TypeError} If arguments are invalid.
 */
declare function convertTimeUnit(time: number, from: TimeUnit$1, to: TimeUnit$1): number;

type TimeUnit = "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "years";
/**
 * Calculates the elapsed time between two dates in the specified unit.
 * @param {Date} from - The start date.
 * @param {Date} [to=new Date()] - The end date.
 * @param {TimeUnit} [unit] - The unit to return.
 * @returns {number} The elapsed time in the specified unit.
 * @throws {TypeError} If dates or unit are invalid.
 */
declare function elapsedTime(from: Date, to?: Date, unit?: TimeUnit): number;

type DateFormat = "DMY" | "MDY" | "YMD";
/**
 * Formats a Date object as a date string in the specified format.
 * @param {Date} date - The date to format.
 * @param {DateFormat} format - The format ("DMY", "MDY", "YMD").
 * @param {string} [separator='/'] - The separator character.
 * @returns {string} The formatted date string.
 * @throws {TypeError} If date or format is invalid.
 */
declare function formatDate(date: Date, format: DateFormat, separator?: string): string;

/**
 * Formats a duration in milliseconds as a time string.
 * @param {number} ms - The duration in milliseconds.
 * @param {string} [format="hh:mm:ss"] - The format string.
 * @param {boolean} [autoHour=true] - Whether to omit hours if zero.
 * @returns {string} The formatted duration string.
 * @throws {TypeError} If ms or format is invalid.
 */
declare function formatDuration(ms: number, format?: string, autoHour?: boolean): string;

/**
 * Formats a Date object as a time string.
 * @param {Date} date - The date to format.
 * @param {string} [format="hh:mm"] - The format string.
 * @returns {string} The formatted time string.
 * @throws {TypeError} If date is not valid.
 */
declare function formatTime(date: Date, format?: string): string;

/**
 * Checks if a date is between two other dates.
 * @param {Date} date - The date to check.
 * @param {Date} start - The start date.
 * @param {Date} end - The end date.
 * @param {boolean} [inclusive=true] - Whether the range is inclusive.
 * @returns {boolean} True if date is between start and end, false otherwise.
 * @throws {TypeError} If any date is not valid.
 */
declare function isBetween(date: Date, start: Date, end: Date, inclusive?: boolean): boolean;

/**
 * Checks if a year is a leap year.
 * @param {string} year - The year as a string.
 * @returns {boolean} True if leap year, false otherwise.
 */
declare function isLeapYear(year: string): boolean;
/**
 * Checks if a year is a leap year.
 * @param {number} year - The year as a number.
 * @returns {boolean} True if leap year, false otherwise.
 */
declare function isLeapYear(year: number): boolean;

/**
 * Checks if two dates are on the same day.
 * @param {Date} date1 - The first date.
 * @param {Date} date2 - The second date.
 * @returns {boolean} True if both dates are on the same day, false otherwise.
 * @throws {TypeError} If either date is not valid.
 */
declare function isSameDay(date1: Date, date2: Date): boolean;

/**
 * Checks if a date is today.
 * @param {Date} date - The date to check.
 * @returns {boolean} True if the date is today, false otherwise.
 * @throws {TypeError} If date is not valid.
 */
declare function isToday(date: Date): boolean;

/**
 * Checks if a date is tomorrow.
 * @param {Date} date - The date to check.
 * @returns {boolean} True if the date is tomorrow, false otherwise.
 * @throws {TypeError} If date is not valid.
 */
declare function isTomorrow(date: Date): boolean;

/**
 * Checks if a value is a valid Date object.
 * @param {Date} value - The value to check.
 * @returns {boolean} True if valid Date, false otherwise.
 */
declare function isValidDate(value: Date): boolean;

/**
 * Checks if a string is a valid date string.
 * @param {string} date - The date string to check.
 * @returns {boolean} True if valid date string, false otherwise.
 * @throws {TypeError} If date is not a string.
 */
declare function isValidDateString(date: string): boolean;

/**
 * Checks if a date falls on a weekday (Monday to Friday).
 * @param {Date} date - The date to check.
 * @returns {boolean} True if weekday, false otherwise.
 * @throws {TypeError} If date is not valid.
 */
declare function isWeekday(date: Date): boolean;

/**
 * Checks if a date falls on a weekend (Saturday or Sunday).
 * @param {Date} date - The date to check.
 * @returns {boolean} True if weekend, false otherwise.
 * @throws {TypeError} If date is not valid.
 */
declare function isWeekend(date: Date): boolean;

/**
 * Checks if a date is yesterday.
 * @param {Date} date - The date to check.
 * @returns {boolean} True if the date is yesterday, false otherwise.
 * @throws {TypeError} If date is not valid.
 */
declare function isYesterday(date: Date): boolean;

/**
 * Parses a Date, string, or number into a valid Date object.
 * @param {Date} date - The date to parse.
 * @returns {Date} The parsed Date object.
 * @throws {TypeError} If date is not valid.
 */
declare function parseDate(date: Date): Date;
/**
 * Parses a string into a valid Date object.
 * @param {string} date - The date string to parse.
 * @returns {Date} The parsed Date object.
 * @throws {TypeError} If date is not valid.
 */
declare function parseDate(date: string): Date;
/**
 * Parses a number into a valid Date object.
 * @param {number} date - The date number to parse.
 * @returns {Date} The parsed Date object.
 * @throws {TypeError} If date is not valid.
 */
declare function parseDate(date: number): Date;

/**
 * Removes the time portion from a Date object (sets time to 00:00:00.000).
 * @param {Date} date - The date to strip time from.
 * @returns {Date} The date with time set to midnight.
 * @throws {TypeError} If date is not valid.
 */
declare function stripTime(date: Date): Date;

/**
 * Converts a Date, string, or number to a Date object.
 * @param {Date} value - The value to convert.
 * @returns {Date} The Date object.
 */
declare function toDate(value: Date): Date;
/**
 * Converts a string to a Date object.
 * @param {string} value - The value to convert.
 * @returns {Date} The Date object.
 */
declare function toDate(value: string): Date;
/**
 * Converts a number to a Date object.
 * @param {number} value - The value to convert.
 * @returns {Date} The Date object.
 */
declare function toDate(value: number): Date;

/**
 * Checks if an environment variable matches an expected value or any value in an array.
 * @param {string} key - The environment variable key.
 * @param {string|string[]} expected - The expected value(s).
 * @returns {boolean} True if the environment variable matches, false otherwise.
 */
declare function equalsEnv(key: string, expected: string | string[]): boolean;

/**
 * Gets an environment variable value, or returns a fallback if not set.
 * @param {string} key - The environment variable key.
 * @param {string} [fallback] - The fallback value if not set.
 * @returns {string|undefined} The environment variable value or fallback.
 */
declare function getEnv(key: string, fallback?: string): string | undefined;

/**
 * Gets the operating system name from the user agent.
 * @returns {string|undefined} The OS name or undefined if server.
 */
declare function getOS(): string | undefined;

/**
 * Gets the current runtime environment.
 * @returns {'Browser' | 'Node' | 'Deno' | 'Bun' | 'Unknown'} The runtime name.
 */
declare function getRuntime(): 'Browser' | 'Node' | 'Deno' | 'Bun' | 'Unknown';

/**
 * Checks if an environment variable is set.
 * @param {string} key - The environment variable key.
 * @returns {boolean} True if the variable is set, false otherwise.
 */
declare function hasEnv(key: string): boolean;

/**
 * Checks if the current environment is a browser.
 * @returns {boolean} True if running in a browser, false otherwise.
 */
declare function isBrowser(): boolean;

/**
 * Checks if the current environment is Bun.
 * @returns {boolean} True if running in Bun, false otherwise.
 */
declare function isBun(): boolean;

/**
 * Checks if the current environment is a Dedicated Worker.
 * @returns {boolean} True if running in a Dedicated Worker, false otherwise.
 */
declare function isDedicatedWorker(): boolean;

/**
 * Checks if the current environment is Deno.
 * @returns {boolean} True if running in Deno, false otherwise.
 */
declare function isDeno(): boolean;

/**
 * Checks if the environment is set to 'development'.
 * @returns {boolean} True if NODE_ENV is 'development', false otherwise.
 */
declare function isDev(): boolean;

/**
 * Checks if the current device is a mobile device.
 * @returns {boolean|undefined} True if mobile, false if not, undefined if server.
 */
declare function isMobile(): boolean | undefined;

/**
 * Checks if the current environment is Node.js.
 * @returns {boolean} True if running in Node.js, false otherwise.
 */
declare function isNode(): boolean;

/**
 * Checks if the environment is set to 'production'.
 * @returns {boolean} True if NODE_ENV is 'production', false otherwise.
 */
declare function isProd(): boolean;

/**
 * Checks if the current environment is a server (not browser).
 * @returns {boolean} True if running on server, false otherwise.
 */
declare function isServer(): boolean;

/**
 * Checks if the current environment is a Service Worker.
 * @returns {boolean} True if running in a Service Worker, false otherwise.
 */
declare function isServiceWorker(): boolean;

/**
 * Checks if the current environment is a Shared Worker.
 * @returns {boolean} True if running in a Shared Worker, false otherwise.
 */
declare function isSharedWorker(): boolean;

/**
 * Checks if the environment is set to 'test'.
 * @returns {boolean} True if NODE_ENV is 'test', false otherwise.
 */
declare function isTest(): boolean;

/**
 * Checks if the current environment is a Web Worker.
 * @returns {boolean} True if running in a Web Worker, false otherwise.
 */
declare function isWebWorker(): boolean;

/**
 * Gets an environment variable value or throws if not set.
 * @param {string} key - The environment variable key.
 * @returns {string} The environment variable value.
 * @throws {Error} If the variable is not set.
 */
declare function requireEnv(key: string): string;

/**
 * Creates a custom error class with a specified name.
 * @param {string} name - The name of the custom error.
 * @returns {new (message?: string, options?: ErrorOptions) => Error} The custom error class.
 */
declare function customError(name: string): new (message?: string, options?: ErrorOptions) => Error;

/**
 * Checks if a value is an AggregateError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is an AggregateError, false otherwise.
 */
declare function isAggregateError(value: any): value is AggregateError;

/**
 * Checks if a value is a DOMException.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is a DOMException, false otherwise.
 */
declare function isDOMException(value: any): value is DOMException;

/**
 * Checks if a value is an error-like object (has name and message).
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is error-like, false otherwise.
 */
declare function isError(value: any): value is {
    name: string;
    message: string;
    stack?: string;
};

/**
 * Checks if a value is an EvalError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is an EvalError, false otherwise.
 */
declare function isEvalError(value: any): value is EvalError;

/**
 * Checks if a value is a RangeError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is a RangeError, false otherwise.
 */
declare function isRangeError(value: any): value is RangeError;

/**
 * Checks if a value is a ReferenceError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is a ReferenceError, false otherwise.
 */
declare function isReferenceError(value: any): value is ReferenceError;

/**
 * Checks if a value is a SyntaxError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is a SyntaxError, false otherwise.
 */
declare function isSyntaxError(value: any): value is SyntaxError;

/**
 * Checks if a value is a TypeError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is a TypeError, false otherwise.
 */
declare function isTypeError(value: any): value is TypeError;

/**
 * Checks if a value is a URIError.
 * @param {any} value - The value to check.
 * @returns {boolean} True if value is a URIError, false otherwise.
 */
declare function isURIError(value: any): value is URIError;

/**
 * @callback ComposeCallback
 * @param {T} value
 * @returns {T}
 */
/**
 * Composes multiple functions from right to left.
 * @template T
 * @param {...ComposeCallback} callbacks - Functions to compose.
 * @returns {(value: T) => T} The composed function.
 * @throws {TypeError} If any argument is not a function.
 */
declare function compose<T>(...callbacks: ((value: T) => T)[]): (value: T) => T;

/**
 * Returns the input value unchanged.
 * @template T
 * @param {T} value - The value to return.
 * @returns {T} The same value.
 */
declare function identity<T>(value: T): T;

/**
 * @callback MemoCallback
 * @param {...any} args
 * @returns {any}
 */
/**
 * @callback MemoSerializer
 * @param {any[]} args
 * @returns {string}
 */
/**
 * Memoizes a function, caching results by arguments.
 * @template T
 * @param {MemoCallback} callback - The function to memoize.
 * @param {{cacheTimeout?: number, serializer?: MemoSerializer}} [options={serializer: JSON.stringify}] - Memoization options.
 * @returns {(...args: Parameters<T>) => ReturnType<T>} The memoized function.
 * @throws {TypeError} If callback or serializer is not a function, or cacheTimeout is not a number.
 */
declare function memo<T extends (...args: any[]) => any>(callback: T, { cacheTimeout, serializer }?: {
    cacheTimeout?: number;
    serializer?: (args: Parameters<T>) => string;
}): (...args: Parameters<T>) => ReturnType<T>;

/**
 * A function that does nothing.
 * @returns {void}
 */
declare function noop(): void;

/**
 * @callback PredicateCallback
 * @param {...any} args
 * @returns {boolean}
 */
/**
 * Negates the result of a predicate function.
 * @template T
 * @param {PredicateCallback} fn - The predicate function.
 * @returns {(...args: Parameters<T>) => boolean} The negated function.
 * @throws {TypeError} If fn is not a function.
 */
declare function not<T extends (...args: any[]) => any>(fn: T): (...args: Parameters<T>) => boolean;

/**
 * @callback OnceCallback
 * @param {...any} args
 * @returns {any}
 */
/**
 * Ensures a function is only called once, caching its result.
 * @template T
 * @param {OnceCallback} callback - The function to call once.
 * @returns {(...args: Parameters<T>) => ReturnType<T>} The wrapped function.
 * @throws {TypeError} If callback is not a function.
 */
declare function once<T extends (...args: any[]) => any>(callback: T): (...args: Parameters<T>) => ReturnType<T>;

type DropFirst<T extends any[]> = T extends [any, ...infer R] ? R : never;
/**
 * @callback PartialLeftCallback
 * @param {...any} args
 * @returns {any}
 */
/**
 * Partially applies arguments from the left.
 * @template Args,R,P
 * @param {PartialLeftCallback} callback - The function to partially apply.
 * @param {...P} partial - Arguments to apply from the left.
 * @returns {(...args: DropFirst<Args> extends P ? [] : DropFirst<Args>) => R} The partially applied function.
 * @throws {TypeError} If callback is not a function.
 */
declare function partialLeft<Args extends any[], R, P extends Partial<Args>>(callback: (...args: Args) => R, ...partial: P): (...args: DropFirst<Args> extends P ? [] : DropFirst<Args>) => R;

type DropLast<T extends any[], N extends any[]> = T extends [...infer R, ...N] ? R : never;
/**
 * @callback PartialRightCallback
 * @param {...any} args
 * @returns {any|Promise<any>}
 */
/**
 * Partially applies arguments from the right.
 * @template Args,R,P
 * @param {PartialRightCallback} callback - The function to partially apply.
 * @param {...P} partial - Arguments to apply from the right.
 * @returns {(...args: DropLast<Args, P>) => R | Promise<R>} The partially applied function.
 * @throws {TypeError} If callback is not a function.
 */
declare function partialRight<Args extends any[], R, P extends Partial<Args>>(callback: (...args: Args) => R | Promise<R>, ...partial: P): (...args: DropLast<Args, P>) => R | Promise<R>;

/**
 * @callback PipeCallback
 * @param {T} value
 * @returns {T}
 */
/**
 * Pipes multiple functions from left to right.
 * @template T
 * @param {...PipeCallback} callbacks - Functions to pipe.
 * @returns {(value: T) => T} The piped function.
 * @throws {TypeError} If any argument is not a function.
 */
declare function pipe<T>(...callbacks: ((value: T) => T)[]): (value: T) => T;

/**
 * @callback TimesCallback
 * @param {number} index
 * @returns {*}
 */
/**
 * Calls a callback a specified number of times, passing the index.
 * @template T
 * @param {TimesCallback} callback - The callback to call.
 * @param {number} count - The number of times to call the callback.
 * @returns {T[]} Array of callback results.
 * @throws {TypeError} If callback is not a function or count is not a non-negative integer.
 */
declare function times<T>(callback: (index: number) => T, count: number): T[];

/**
 * @callback ActionCallback
 * @param {...any} args
 * @returns {any}
 */
/**
 * Executes an action if the predicate returns true.
 * @template T
 * @param {(...args: any) => boolean} predicate - The predicate function.
 * @param {ActionCallback} action - The action to execute.
 * @returns {(...args: Parameters<T>) => ReturnType<T> | undefined} The conditional function.
 * @throws {TypeError} If predicate or action is not a function.
 */
declare function when<T extends (...args: any) => any>(predicate: (...args: any) => boolean, action: T): (...args: Parameters<T>) => ReturnType<T> | undefined;

/**
 * Returns the sum of all provided numbers.
 * @param {...number} values - The numbers to add.
 * @returns {number} The sum of the numbers.
 * @throws {TypeError} If any value is not a number.
 */
declare function add(...values: number[]): number;

/**
 * Clamps a number between min and max.
 * @param {number} value - The number to clamp.
 * @param {number} min - The minimum value.
 * @param {number} max - The maximum value.
 * @returns {number} The clamped value.
 * @throws {TypeError|RangeError} If arguments are invalid.
 */
declare function clamp(value: number, min: number, max: number): number;

/**
 * Divides dividend by divisor.
 * @param {number} dividend - The dividend.
 * @param {number} divisor - The divisor.
 * @returns {number} The result of division.
 * @throws {TypeError|Error} If dividend or divisor is not a number, or divisor is zero.
 */
declare function divide(dividend: number, divisor: number): number;

/**
 * Returns the factorial of a non-negative integer.
 * @param {number} value - The non-negative integer.
 * @returns {number} The factorial value.
 * @throws {TypeError} If value is not a non-negative integer.
 */
declare function factorial(value: number): number;

/**
 * Returns the nth Fibonacci number.
 * @param {number} num - The index (non-negative integer).
 * @returns {number} The nth Fibonacci number.
 * @throws {TypeError} If num is not a non-negative integer.
 */
declare function fibonacci(num: number): number;

/**
 * Returns a frequency map of items in an array.
 * @param {any[]} arr - The array to analyze.
 * @returns {Record<PropertyKey, number>} The frequency map.
 * @throws {TypeError} If arr is not an array.
 */
declare function frequency(arr: any[]): Record<PropertyKey, number>;

/**
 * Performs linear interpolation between two numbers.
 * @param {number} start - The start value.
 * @param {number} end - The end value.
 * @param {number} amount - The interpolation factor (0 to 1).
 * @returns {number} The interpolated value.
 * @throws {TypeError} If any argument is not a number.
 */
declare function lerp(start: number, end: number, amount: number): number;

/**
 * Returns the mean (average) of an array of numbers.
 * @param {number[]} values - The array of numbers.
 * @returns {number} The mean value.
 * @throws {TypeError} If values is not an array of numbers.
 */
declare function mean(values: number[]): number;

/**
 * Returns the median of an array of numbers.
 * @param {number[]} arr - The array of numbers.
 * @returns {number} The median value.
 * @throws {TypeError|Error} If arr is not a valid array or is empty.
 */
declare function median(arr: number[]): number;

/**
 * Returns the positive modulo of dividend and divisor.
 * @param {number} dividend - The dividend.
 * @param {number} divisor - The divisor.
 * @returns {number} The positive modulo result.
 * @throws {TypeError|Error} If dividend or divisor is not a number, or divisor is zero.
 */
declare function mod(dividend: number, divisor: number): number;

/**
 * Returns the mode(s) of an array of numbers.
 * @param {number[]} arr - The array of numbers.
 * @returns {number[]} The mode(s) of the array.
 * @throws {TypeError} If arr is not an array of numbers.
 */
declare function mode(arr: number[]): number[];

/**
 * Returns the product of all provided numbers.
 * @param {...number} values - The numbers to multiply.
 * @returns {number} The product of the numbers.
 * @throws {TypeError} If any value is not a number.
 */
declare function multiply(...values: number[]): number;

/**
 * Raises a base to the exponent power.
 * @param {number} base - The base number.
 * @param {number} exponent - The exponent.
 * @returns {number} The result of base raised to exponent.
 * @throws {TypeError} If base or exponent is not a number.
 */
declare function pow(base: number, exponent: number): number;

/**
 * Returns a random integer between min and max (inclusive).
 * @param {number} [min=0] - The minimum value.
 * @param {number} [max=10] - The maximum value.
 * @returns {number} The random integer.
 * @throws {TypeError|RangeError} If min or max is not a number, or min > max.
 */
declare function random(min?: number, max?: number): number;

/**
 * Rounds a number to a specified precision.
 * @param {number} value - The number to round.
 * @param {number} [precision=0] - The number of decimal places.
 * @returns {number} The rounded number.
 * @throws {TypeError} If value or precision is not