houser-js-utils/dist/FunctionUtils.d.ts

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.

/**
 * Utility functions for function manipulation and optimization.
 *
 * This module provides a collection of utility functions for working with functions,
 * including composition, debouncing, throttling, and more.
 *
 * @module FunctionUtils
 * @example
 * ```typescript
 * // Compose multiple functions
 * const addOne = (x: number) => x + 1;
 * const double = (x: number) => x * 2;
 * const addOneAndDouble = FunctionUtils.compose(double, addOne);
 *
 * // Debounce a function
 * const debouncedSearch = FunctionUtils.debounce(searchFunction, 300);
 *
 * // Throttle a function
 * const throttledScroll = FunctionUtils.throttle(handleScroll, 100);
 * ```
 */
export declare const FunctionUtils: {
    /**
     * Composes multiple functions into a single function, where the output
     * of each function is passed as input to the next function.
     *
     * @template T - The type of the input to the first function
     * @template R - The type of the output of the last function
     * @param funcs - The functions to compose
     * @returns A function that is the composition of all provided functions
     *
     * @example
     * ```typescript
     * const addOne = (x: number) => x + 1;
     * const double = (x: number) => x * 2;
     * const addOneAndDouble = FunctionUtils.compose(double, addOne);
     * addOneAndDouble(5); // Returns 12 (5 + 1 = 6, then 6 * 2 = 12)
     * ```
     */
    compose<T, R>(...funcs: Array<(arg: any) => any>): (arg: T) => R;
    /**
     * Creates a debounced function that delays invoking the provided function
     * until after the specified wait time has elapsed since the last time it was invoked.
     *
     * @template T - The type of the function's arguments
     * @template R - The return type of the function
     * @param func - The function to debounce
     * @param waitTime - The number of milliseconds to delay
     * @param immediate - If true, the function will be called on the leading edge instead of the trailing edge
     * @returns A debounced version of the provided function
     *
     * @example
     * ```typescript
     * const debouncedSearch = FunctionUtils.debounce((query: string) => {
     *   // Perform search
     * }, 300);
     *
     * // Will only execute after 300ms of no calls
     * debouncedSearch("test");
     * ```
     */
    debounce<T extends any[], R>(func: (...args: T) => R, waitTime?: number, immediate?: boolean): (...args: T) => R | undefined;
    /**
     * Creates a function that delays invoking the provided function
     * until the current call stack has cleared.
     *
     * @template T - The type of the function's arguments
     * @template R - The return type of the function
     * @param func - The function to defer
     * @returns A deferred version of the provided function
     *
     * @example
     * ```typescript
     * const deferredLog = FunctionUtils.defer((message: string) => {
     *   console.log(message);
     * });
     *
     * // Will execute after current execution context
     * deferredLog("Hello");
     * ```
     */
    defer<T extends any[], R>(func: (...args: T) => R): (...args: T) => void;
    /**
     * Creates a function that can only be called once. Subsequent calls
     * will return the result of the first call.
     *
     * @template T - The type of the function's arguments
     * @template R - The return type of the function
     * @param func - The function to make callable only once
     * @returns A function that can only be called once
     *
     * @example
     * ```typescript
     * const initialize = FunctionUtils.once(() => {
     *   // Expensive initialization
     *   return "initialized";
     * });
     *
     * initialize(); // Returns "initialized"
     * initialize(); // Returns "initialized" without executing the function again
     * ```
     */
    once<T extends any[], R>(func: (...args: T) => R): (...args: T) => R;
    /**
     * Creates a throttled function that only invokes the provided function
     * at most once per every wait milliseconds.
     *
     * @template T - The type of the function's arguments
     * @template R - The return type of the function
     * @param func - The function to throttle
     * @param waitTime - The number of milliseconds to throttle invocations to
     * @returns A throttled version of the provided function
     *
     * @example
     * ```typescript
     * const throttledScroll = FunctionUtils.throttle(() => {
     *   // Handle scroll event
     * }, 100);
     *
     * // Will execute at most once every 100ms
     * window.addEventListener('scroll', throttledScroll);
     * ```
     */
    throttle<T extends any[], R>(func: (...args: T) => R, waitTime?: number): (...args: T) => R | undefined;
};