@lesjoursfr/browser-tools/src/throttle.ts

Some browser tools for events & DOM manipulation.

/* eslint-disable @typescript-eslint/no-explicit-any */
/**
 * Based on lodash version of throttle : https://github.com/lodash/lodash/blob/master/throttle.js
 */
/**
 * Creates a debounced function that delays invoking `func` until after `wait`
 * milliseconds have elapsed since the last time the debounced function was
 * invoked, or until the next browser frame is drawn. Provide `options` to indicate
 * whether `func` should be invoked on the leading and/or trailing edge of the
 * `wait` timeout. The `func` is invoked with the last arguments provided to the
 * debounced function. Subsequent calls to the debounced function return the
 * result of the last `func` invocation.
 * **Note:** If `leading` and `trailing` options are `true`, `func` is
 * invoked on the trailing edge of the timeout only if the debounced function
 * is invoked more than once during the `wait` timeout.
 * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
 * until the next tick, similar to `setTimeout` with a timeout of `0`.
 * @param {Function} func The function to debounce
 * @param {number} wait The number of milliseconds to delay
 * @param {Object} [options={}] The options object
 * @param {boolean} [options.leading=false] Specify invoking on the leading edge of the timeout
 * @param {boolean} [options.trailing=true] Specify invoking on the trailing edge of the timeout
 * @param {number} [options.maxWait] The maximum time `func` is allowed to be delayed before it's invoked
 * @returns {Function} Returns the new debounced function
 */
function debounce<F extends (...args: any) => any>(
  func: F,
  wait: number,
  options: { leading?: boolean; trailing?: boolean; maxWait?: number } = {}
): (...args: Parameters<F>) => ReturnType<F> {
  let lastArgs: Parameters<F> | undefined,
    lastThis: any | undefined,
    result: ReturnType<F> | undefined,
    timerId: ReturnType<typeof setTimeout> | undefined,
    lastCallTime: number | undefined;

  let lastInvokeTime: number = 0;
  const leading = !!options.leading;
  const maxing = "maxWait" in options;
  const maxWait = maxing ? Math.max(options.maxWait || 0, wait) : undefined;
  const trailing = "trailing" in options ? !!options.trailing : true;

  function invokeFunc(time: number): ReturnType<F> {
    const args = lastArgs;
    const thisArg = lastThis;

    lastArgs = lastThis = undefined;
    lastInvokeTime = time;
    result = func.apply(thisArg!, args!);
    return result!;
  }

  function startTimer(pendingFunc: () => void, wait: number): ReturnType<typeof setTimeout> {
    return setTimeout(pendingFunc, wait);
  }

  function leadingEdge(time: number): ReturnType<F> {
    // Reset any `maxWait` timer.
    lastInvokeTime = time;
    // Start the timer for the trailing edge.
    timerId = startTimer(timerExpired, wait);
    // Invoke the leading edge.
    return leading ? invokeFunc(time) : result!;
  }

  function remainingWait(time: number): number {
    const timeSinceLastCall = time - lastCallTime!;
    const timeSinceLastInvoke = time - lastInvokeTime;
    const timeWaiting = wait - timeSinceLastCall;

    return maxing ? Math.min(timeWaiting, maxWait! - timeSinceLastInvoke) : timeWaiting;
  }

  function shouldInvoke(time: number): boolean {
    const timeSinceLastCall = time - lastCallTime!;
    const timeSinceLastInvoke = time - lastInvokeTime;

    // Either this is the first call, activity has stopped and we're at the
    // trailing edge, the system time has gone backwards and we're treating
    // it as the trailing edge, or we've hit the `maxWait` limit.
    return (
      lastCallTime === undefined ||
      timeSinceLastCall >= wait ||
      timeSinceLastCall < 0 ||
      (maxing && timeSinceLastInvoke >= maxWait!)
    );
  }

  function timerExpired(): ReturnType<F> | undefined {
    const time = Date.now();
    if (shouldInvoke(time)) {
      return trailingEdge(time);
    }
    // Restart the timer.
    timerId = startTimer(timerExpired, remainingWait(time));
  }

  function trailingEdge(time: number): ReturnType<F> {
    timerId = undefined;

    // Only invoke if we have `lastArgs` which means `func` has been
    // debounced at least once.
    if (trailing && lastArgs) {
      return invokeFunc(time);
    }
    lastArgs = lastThis = undefined;
    return result!;
  }

  function debounced(this: any, ...args: Parameters<F>): ReturnType<F> {
    const time = Date.now();
    const isInvoking = shouldInvoke(time);

    lastArgs = args;
    // eslint-disable-next-line @typescript-eslint/no-this-alias
    lastThis = this;
    lastCallTime = time;

    if (isInvoking) {
      if (timerId === undefined) {
        return leadingEdge(lastCallTime);
      }
      if (maxing) {
        // Handle invocations in a tight loop.
        timerId = startTimer(timerExpired, wait);
        return invokeFunc(lastCallTime);
      }
    }
    if (timerId === undefined) {
      timerId = startTimer(timerExpired, wait);
    }
    return result!;
  }

  return debounced;
}

/**
 * Creates a throttled function that only invokes `func` at most once per
 * every `wait` milliseconds (or once per browser frame). Provide `options` to indicate
 * whether `func` should be invoked on the leading and/or trailing edge of the
 * `wait` timeout. The `func` is invoked with the last arguments provided to the
 * throttled function. Subsequent calls to the throttled function return the
 * result of the last `func` invocation.
 * **Note:** If `leading` and `trailing` options are `true`, `func` is
 * invoked on the trailing edge of the timeout only if the throttled function
 * is invoked more than once during the `wait` timeout.
 * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
 * until the next tick, similar to `setTimeout` with a timeout of `0`.
 * @param {Function} func The function to throttle
 * @param {number} wait The number of milliseconds to throttle invocations to
 * @param {Object} [options={}] The options object
 * @param {boolean} [options.leading=true] Specify invoking on the leading edge of the timeout
 * @param {boolean} [options.trailing=true] Specify invoking on the trailing edge of the timeout
 * @returns {Function} Returns the new throttled function
 */
function throttle<F extends (...args: any) => any>(
  func: F,
  wait: number,
  options: { leading?: boolean; trailing?: boolean } = {}
): (...args: Parameters<F>) => ReturnType<F> {
  const leading = "leading" in options ? !!options.leading : true;
  const trailing = "trailing" in options ? !!options.trailing : true;

  return debounce(func, wait, {
    leading,
    trailing,
    maxWait: wait,
  });
}

export { debounce, throttle };