@modern-kit/utils/dist/common/debounce/index.d.ts

modern-kit/utils

interface DebounceOptions {
    signal?: AbortSignal;
    maxWait?: number;
    leading?: boolean;
    trailing?: boolean;
}
interface DebouncedFunction<F extends (...args: any[]) => void> {
    (...args: Parameters<F>): void;
    cancel: () => void;
    flush: () => void;
}
/**
 * @description 디바운스된 함수를 생성합니다.
 *
 * 디바운스된 함수는 마지막으로 호출된 시점으로부터 `wait` 밀리초가 경과할 때까지 제공된 함수의 실행을 지연시킵니다.
 * - 연속 호출 시 이전 호출은 취소되고 새로운 타이머가 시작됩니다.
 *
 * @template F - 함수의 타입입니다.
 * @param {F} func - 디바운스할 함수입니다.
 * @param {number} wait - 지연시킬 시간(밀리초)입니다.
 * @param {DebounceOptions} options - 옵션 객체입니다.
 * @param {number} options.maxWait - 최대 대기 시간(밀리초)입니다.
 * debounce는 기본적으로 호출되면 대기 시간이 초기화됩니다. maxWait 옵션은 연속적인 호출이 발생하더라도 첫 호출 기준으로 최대 대기 시간이 지나면 강제로 함수가 실행됩니다.
 * @param {boolean} options.leading - 첫 번째 호출을 실행할지 여부입니다.
 * @param {boolean} options.trailing - 마지막 호출을 실행할지 여부입니다.
 * @param {AbortSignal} options.signal - 디바운스된 함수를 취소하기 위한 선택적 AbortSignal입니다.
 *
 * @returns {DebouncedFunction<F>} `cancel` 메서드가 포함된 새로운 디바운스된 함수를 반환합니다.
 * - `cancel` 메서드는 디바운스된 함수의 대기 중인 실행을 취소합니다.
 * - `flush` 메서드는 대기 중인 실행이 있는 경우 디바운스된 함수를 즉시 실행합니다.
 *
 * @example
 * const debouncedFunction = debounce(func, 1000);
 * debouncedFunction(); // 1초 후에 함수가 실행됩니다
 *
 * @example
 * // AbortSignal 사용 예시
 * const controller = new AbortController();
 * const signal = controller.signal;
 * const debouncedWithSignal = debounce(func, 1000, { signal });
 *
 * debouncedWithSignal();
 *
 * // 디바운스된 함수 호출을 취소합니다
 * controller.abort();
 */
declare function debounce<F extends (...args: any[]) => void>(func: F, wait: number, options?: DebounceOptions): DebouncedFunction<F>;

export { debounce };