useDebouncedCallback

import { useDebouncedCallback } from '@frontend-toolkit-js/hooks';
 
function SearchInput() {
  const debouncedSearch = useDebouncedCallback((query: string) => {
    fetch(`/api/search?q=${query}`);
  }, 300);
 
  return (
    <input
      onChange={e => debouncedSearch(e.target.value)}
      placeholder="검색..."
    />
  );
}

function AutocompleteSearch() {
  const [results, setResults] = useState([]);
 
  const debouncedSearch = useDebouncedCallback(async (query: string) => {
    const data = await fetch(`/api/search?q=${query}`);
    setResults(data);
  }, 300);
 
  return <input onChange={e => debouncedSearch(e.target.value)} />;
}

function PaymentForm() {
  const handleSubmit = useDebouncedCallback(
    async formData => {
      await submitPayment(formData);
    },
    2000,
    { leading: true, trailing: false }
  );
 
  return <button onClick={handleSubmit}>결제하기</button>;
}

클릭1 (0ms)    → 즉시 실행 ✅
클릭2 (500ms)  → 무시 ❌
클릭3 (1000ms) → 무시 ❌
클릭4 (2100ms) → 다시 즉시 실행 ✅

function Editor() {
  const [content, setContent] = useState('');
 
  const autoSave = useDebouncedCallback(
    (text: string) => {
      saveToServer(text);
    },
    1000,
    { maxWait: 5000 }
  );
 
  return (
    <textarea
      value={content}
      onChange={e => {
        setContent(e.target.value);
        autoSave(e.target.value);
      }}
    />
  );
}

계속 타이핑 → 1초 타이머 계속 리셋
5초 경과     → 강제 저장! ⚡
타이핑 멈춤  → 1초 후 저장 ✅

function ScrollTracker() {
  const trackScroll = useDebouncedCallback(
    () => {
      analytics.track('scroll', { position: window.scrollY });
    },
    200,
    { leading: true, trailing: true }
  );
 
  useEffect(() => {
    window.addEventListener('scroll', trackScroll);
    return () => window.removeEventListener('scroll', trackScroll);
  }, [trackScroll]);
 
  return <div>...</div>;
}

스크롤 시작 → 즉시 추적 ✅ (leading)
계속 스크롤 → 대기...
스크롤 멈춤 → 200ms 후 추적 ✅ (trailing)

function useDebouncedCallback<T extends (...args: any[]) => any>(
  callback: T,
  delay: number,
  options?: DebouncedCallbackOptions
): T;

interface DebouncedCallbackOptions {
  leading?: boolean; // 첫 호출 즉시 실행
  trailing?: boolean; // 마지막 호출 후 실행
  maxWait?: number; // 최대 대기 시간
}

// leading: true → 첫 호출 즉시 실행
const debounced = useDebouncedCallback(fn, 1000, {
  leading: true,
  trailing: false,
});
 
// 사용 사례: 버튼 연타 방지, 폼 제출

// trailing: true (기본) → 마지막 호출 후 실행
const debounced = useDebouncedCallback(fn, 300);
 
// 사용 사례: 검색 자동완성, 입력 검증

// maxWait: 5000 → 최대 5초마다 강제 실행
const debounced = useDebouncedCallback(save, 1000, { maxWait: 5000 });
 
// 사용 사례: 자동 저장, 주기적 동기화

useDebouncedCallback(fn, 300);
// = { leading: false, trailing: true }
 
// 입력 멈춘 후 300ms 후 실행

useDebouncedCallback(fn, 1000, {
  leading: true,
  trailing: false,
});
 
// 첫 호출만 즉시 실행, 이후 1초간 무시

useDebouncedCallback(fn, 200, {
  leading: true,
  trailing: true,
});
 
// 시작 시 즉시 실행 + 끝날 때도 실행

useDebouncedCallback(fn, 1000, {
  trailing: true,
  maxWait: 5000,
});
 
// 일반: 1초 대기, 강제: 5초마다 실행

// useDebounce: 값 디바운스
const debouncedValue = useDebounce(value, 300);
 
// useDebouncedCallback: 함수 디바운스
const debouncedFn = useDebouncedCallback(fn, 300);

// ✅ 타입 추론
const debouncedSearch = useDebouncedCallback((query: string, limit: number) => {
  fetch(`/api?q=${query}&limit=${limit}`);
}, 300);
 
debouncedSearch('hello', 10); // ✅
debouncedSearch('hello'); // ❌ 에러: limit 필요
debouncedSearch(123, 10); // ❌ 에러: query는 string

// 자동 cleanup됨 - 별도 처리 불필요
const debounced = useDebouncedCallback(fn, 300);