houser-js-utils/dist/FunctionUtils.js

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.

"use strict";
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
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(...funcs) {
    return function(arg) {
      return funcs.reduceRight(
        (result, func) => func(result),
        arg
      );
    };
  },
  /**
   * 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(func, waitTime = 1e3, immediate = false) {
    let debounceTimeout = null;
    return function(...args) {
      const context = this;
      const later = function() {
        debounceTimeout = null;
        if (!immediate) {
          func.apply(context, args);
        }
      };
      const callNow = immediate && !debounceTimeout;
      if (debounceTimeout) {
        clearTimeout(debounceTimeout);
      }
      debounceTimeout = setTimeout(later, waitTime);
      if (callNow) {
        return func.apply(context, args);
      }
    };
  },
  /**
   * 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(func) {
    return function(...args) {
      setTimeout(() => func.apply(this, args), 0);
    };
  },
  /**
   * 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(func) {
    let called = false;
    let result;
    return function(...args) {
      if (!called) {
        called = true;
        result = func.apply(this, args);
      }
      return result;
    };
  },
  /**
   * 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(func, waitTime = 1e3) {
    let lastCall = 0;
    return function(...args) {
      const now = Date.now();
      if (now - lastCall >= waitTime) {
        lastCall = now;
        return func.apply(this, args);
      }
    };
  }
};
exports.FunctionUtils = FunctionUtils;
//# sourceMappingURL=FunctionUtils.js.map