본문으로 건너뛰기

함수: asyncDebounce()

function asyncDebounce<TFn>(fn, initialOptions): (...args) => Promise<Awaited<ReturnType<TFn>> | undefined>;

정의 위치: async-debouncer.ts:560

지정된 대기 시간이 지난 뒤로 실행을 미루는 비동기 디바운스 함수를 생성합니다. 디바운스 함수는 새 호출 없이 대기 시간이 경과해야 실행됩니다. 대기 시간 중 다시 호출하면 타이머가 초기화되고 새로운 대기 시간이 시작됩니다.

비동기 버전과 동기 버전: 비동기 버전은 동기 디바운스 함수보다 다음과 같은 고급 기능을 제공합니다.

  • 디바운스 함수 결과를 기다릴 수 있는 프로미스를 반환합니다.
  • AsyncRetryer 통합을 통한 내장 재시도 기능을 제공합니다.
  • 진행 중인 실행을 취소하는 중단 기능을 제공합니다.
  • 대기 중인 실행의 시작을 막는 취소 기능을 제공합니다.
  • onError 콜백과 throwOnError 제어를 통한 포괄적인 오류 처리를 제공합니다.
  • 세부 실행 정보(성공/오류/완료 횟수)를 추적합니다.

비동기 기능, 반환값 또는 실행 제어가 필요하지 않다면 동기 디바운스 함수가 더 가볍고 간단합니다.

디바운싱이란? 디바운싱은 마지막 호출 후 지정된 지연 시간이 지나야 함수가 실행되도록 합니다. 새 호출이 발생할 때마다 지연 타이머가 초기화됩니다. 창 크기 조정이나 입력 변경처럼 이벤트 발생이 멈춘 뒤에만 핸들러를 실행하려는 빈번한 이벤트를 처리할 때 유용합니다.

설정 옵션:

  • wait: 마지막 호출 후 기다릴 지연 시간(밀리초, 필수)
  • leading: 타임아웃의 선행 에지에서 실행할지 여부(기본값: false)
  • trailing: 타임아웃의 후행 에지에서 실행할지 여부(기본값: true)
  • enabled: 디바운서 활성화 여부(기본값: true)
  • asyncRetryerOptions: 실행의 재시도 동작 설정

오류 처리:

  • onError 핸들러를 제공하면 오류 및 디바운서 인스턴스와 함께 호출됩니다.
  • throwOnError가 true이면(onError 핸들러가 없을 때의 기본값) 오류가 발생합니다.
  • throwOnError가 false이면(onError 핸들러가 있을 때의 기본값) 오류가 처리된 것으로 간주됩니다.
  • 내부 AsyncDebouncer 인스턴스를 사용해 오류 상태를 확인할 수 있습니다.
  • onError와 throwOnError를 함께 사용할 수 있으며 오류가 발생하기 전에 핸들러가 호출됩니다.

상태 관리:

  • 반응형 상태 관리에 TanStack Store를 사용합니다.
  • 비동기 디바운서 생성 시 initialState로 초기 상태 값을 제공합니다.
  • onSuccess 콜백으로 성공한 함수 실행에 반응하고 사용자 지정 로직을 구현합니다.
  • onError 콜백으로 함수 실행 오류에 반응하고 사용자 지정 오류 처리를 구현합니다.
  • onSettled 콜백으로 함수 실행 완료(성공 또는 오류)에 반응하고 사용자 지정 로직을 구현합니다.
  • 상태에는 canLeadingExecute, 오류 횟수, 실행 상태, 성공/완료 횟수가 포함됩니다.
  • 클래스를 직접 사용할 때는 asyncDebouncer.store.state로 상태에 접근할 수 있습니다.
  • 프레임워크 어댑터(React/Solid)를 사용할 때는 asyncDebouncer.state에서 상태에 접근합니다.

타입 매개변수​

TFn​

TFn extends AnyAsyncFunction

매개변수​

fn​

TFn

initialOptions​

AsyncDebouncerOptions&lt;TFn>

반환값​

(...args): Promise<Awaited<ReturnType<TFn>> | undefined>;

디바운스 함수 실행을 시도합니다. 호출이 이미 진행 중이면 큐에 추가됩니다.

오류 처리:

  • 디바운스 함수에서 오류가 발생하고 onError 핸들러가 설정되지 않았다면 이 메서드에서 오류가 발생합니다.
  • onError 핸들러가 설정되어 있다면 오류를 포착해 핸들러에 전달하고 이 메서드는 undefined를 반환합니다.
  • getErrorCount()와 getIsExecuting()을 사용해 오류 상태를 확인할 수 있습니다.

매개변수​

args​

...Parameters&lt;TFn>

반환값​

Promise&lt;Awaited&lt;ReturnType&lt;TFn>> | undefined>

함수의 반환값으로 이행되는 프로미스입니다. 오류가 발생했으며 onError로 처리된 경우에는 undefined입니다.

발생 오류​

onError 핸들러가 설정되지 않았을 때 발생한 디바운스 함수의 오류입니다.

예시​

const debounced = asyncDebounce(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  },
  throwOnError: true // Will both log the error and throw it
});

// Will only execute once, 1 second after the last call
// Returns the API response directly
const result = await debounced("third");