debounce.ts

/**
 * Custom debounce based on lodash.debounce.
 *
 * 1. 불필요한 전역 객체 탐지 제거:
 *      freeGlobal과 freeSelf를 제거하고, globalThis를 기본으로 사용하되, 브라우저 호환성을 위해 간단한 폴백을 추가했습니다. 현대 환경에서는 globalThis가 대부분 지원되므로 코드가 간결해졌습니다.
 * 2. 타입 개선:
 *      any 사용을 최소화하고, unknown과 제네릭 타입을 활용해 타입 안전성을 높였습니다.
 *      Parameters<T>와 ReturnType<T>를 사용해 함수 인자와 반환값의 타입을 정확히 추론하도록 했습니다.
 * 3. 변수 선언 간소화:
 *      options 처리 로직을 구조 분해 할당으로 간소화해 가독성을 높였습니다.
 *      maxWait 계산을 초기화 시점에서 한 번만 수행하도록 변경해 중복 연산을 줄였습니다.
 * 4. 함수 인라인 최적화:
 *      중첩 함수를 상위 스코프로 끌어올려 클로저 환경을 단순화하고, 불필요한 함수 호출 오버헤드를 줄였습니다.
 *      timerExpired 로직을 간소화해 조건 검사를 줄였습니다.
 * 5. 성능 개선:
 *      Math.max와 Math.min을 구조 분해할당으로 직접 참조해 네이티브 메서드 호출을 최적화했습니다.
 *      toNumber 함수에서 불필요한 중간 변수와 조건문을 정리했습니다.
 * 6. 주석 간소화:
 *      불필요하거나 중복된 주석을 제거하고, 핵심 정보만 남겼습니다.
 */

/** Used as the `TypeError` message for "Functions" methods. */
const FUNC_ERROR_TEXT = 'Expected a function';

/** Used as a reference to the global object. */
const root = (typeof globalThis === 'object' && globalThis) || Function('return this')();

/** Built-in method references. */
const { max: nativeMax, min: nativeMin } = Math;
const now = () => root.Date.now();

interface DebounceOptions {
  leading?: boolean;
  maxWait?: number;
  trailing?: boolean;
}

// eslint-disable-next-line @typescript-eslint/no-explicit-any
interface DebouncedFunction<T extends (...args: any[]) => any> {
  (...args: Parameters<T>): ReturnType<T> | undefined;
  cancel(): void;
  flush(): ReturnType<T> | undefined;
}

// eslint-disable-next-line @typescript-eslint/no-explicit-any
function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait = 0,
  options: DebounceOptions = {},
): DebouncedFunction<T> {
  if (typeof func !== 'function') throw new TypeError(FUNC_ERROR_TEXT);

  const { leading = false, maxWait, trailing = true } = options;
  const maxing = maxWait !== undefined;
  const effectiveMaxWait = maxing ? nativeMax(toNumber(maxWait) || 0, wait) : undefined;

  let lastArgs: Parameters<T> | undefined;
  let lastThis: unknown;
  let result: ReturnType<T> | undefined;
  let timerId: ReturnType<typeof setTimeout> | undefined;
  let lastCallTime: number | undefined;
  let lastInvokeTime = 0;

  const invokeFunc = (time: number): ReturnType<T> | undefined => {
    const args = lastArgs!;
    const thisArg = lastThis;
    lastArgs = lastThis = undefined;
    lastInvokeTime = time;
    return (result = func.apply(thisArg, args) as ReturnType<T> | undefined);
  };

  const remainingWait = (time: number): number => {
    const timeSinceLastCall = time - (lastCallTime || 0);
    const timeSinceLastInvoke = time - lastInvokeTime;
    const timeWaiting = wait - timeSinceLastCall;
    return maxing ? nativeMin(timeWaiting, effectiveMaxWait! - timeSinceLastInvoke) : timeWaiting;
  };

  const shouldInvoke = (time: number): boolean => {
    const timeSinceLastCall = time - (lastCallTime || 0);
    const timeSinceLastInvoke = time - lastInvokeTime;
    return (
      lastCallTime === undefined ||
      timeSinceLastCall >= wait ||
      timeSinceLastCall < 0 ||
      (maxing && timeSinceLastInvoke >= effectiveMaxWait!)
    );
  };

  const trailingEdge = (time: number): ReturnType<T> | undefined => {
    timerId = undefined;
    if (trailing && lastArgs) return invokeFunc(time);
    lastArgs = lastThis = undefined;
    return result;
  };

  const timerExpired = (): void => {
    const time = now();
    if (shouldInvoke(time)) {
      trailingEdge(time); // timerId는 trailingEdge에서만 수정
    } else {
      timerId = setTimeout(timerExpired, remainingWait(time));
    }
  };

  const leadingEdge = (time: number): ReturnType<T> | undefined => {
    lastInvokeTime = time;
    timerId = setTimeout(timerExpired, wait);
    return leading ? invokeFunc(time) : result;
  };

  const cancel = (): void => {
    if (timerId !== undefined) clearTimeout(timerId);
    lastInvokeTime = 0;
    lastArgs = lastCallTime = lastThis = timerId = undefined;
  };

  const flush = (): ReturnType<T> | undefined =>
    timerId === undefined ? result : trailingEdge(now());

  function debounced(this: unknown, ...args: Parameters<T>): ReturnType<T> | undefined {
    const time = now();
    const isInvoking = shouldInvoke(time);

    lastArgs = args;
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    lastThis = this as any; // `this`를 별칭으로 저장하지만, 타입은 unknown 에서 any 로 변환
    lastCallTime = time;

    if (isInvoking) {
      if (timerId === undefined) return leadingEdge(time);
      if (maxing) {
        timerId = setTimeout(timerExpired, wait);
        return invokeFunc(time);
      }
    }
    if (timerId === undefined) timerId = setTimeout(timerExpired, wait);
    return result;
  }

  debounced.cancel = cancel;
  debounced.flush = flush;
  return debounced as DebouncedFunction<T>;
}

const isObject = (value: unknown): value is object =>
  Boolean(value) && (typeof value === 'object' || typeof value === 'function');

const toNumber = (value: unknown): number => {
  if (typeof value === 'number') return value;
  if (typeof value === 'symbol') return NaN;
  if (isObject(value)) {
    const other = typeof value.valueOf === 'function' ? value.valueOf() : value;
    value = isObject(other) ? String(other) : other;
  }
  if (typeof value !== 'string') return value === 0 ? 0 : Number(value);

  const trimmed = value.trim();
  if (/^0b[01]+$/i.test(trimmed)) return parseInt(trimmed.slice(2), 2);
  if (/^0o[0-7]+$/i.test(trimmed)) return parseInt(trimmed.slice(2), 8);
  if (/^0x[0-9a-f]+$/i.test(trimmed)) return parseInt(trimmed.slice(2), 16);
  return /^0x/i.test(trimmed) ? NaN : Number(trimmed);
};

export default debounce;