본문으로 건너뛰기

함수: asyncThrottle()

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

정의 위치: async-throttler.ts:628

함수의 실행 빈도를 제한하는 비동기 스로틀 함수를 생성합니다. 스로틀 함수는 여러 번 호출되어도 대기 시간마다 최대 한 번 실행됩니다. 실행 중에 호출하면 실행이 완료될 때까지 기다린 뒤 다음 호출을 예약합니다.

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

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

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

스로틀링이란? 스로틀링은 지정된 시간 윈도우 안에서 한 번의 실행만 허용해 함수 실행 빈도를 제한합니다. 호출할 때마다 지연 타이머를 초기화하는 디바운싱과 달리 스로틀링은 호출 빈도와 관계없이 함수가 일정한 간격으로 실행되도록 합니다.

설정 옵션:

  • wait: 함수를 한 번만 실행할 수 있는 시간 윈도우(밀리초, 필수)
  • leading: 호출 시 즉시 실행할지 여부(기본값: true)
  • trailing: 대기 시간의 후행 에지에서 실행할지 여부(기본값: true)
  • enabled: 스로틀러 활성화 여부(기본값: true)
  • asyncRetryerOptions: 실행의 재시도 동작 설정

오류 처리:

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

상태 관리:

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

타입 매개변수​

TFn​

TFn extends AnyAsyncFunction

매개변수​

fn​

TFn

initialOptions​

AsyncThrottlerOptions&lt;TFn>

반환값​

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

스로틀 함수 실행을 시도합니다. 실행 동작은 스로틀러 옵션에 따라 달라집니다.

  • 마지막 실행 후 충분한 시간이 지난 경우(>= 대기 시간):

    • leading=true: 즉시 실행합니다.
    • leading=false: 다음 후행 실행을 기다립니다.

  • 대기 시간 안인 경우:

    • trailing=true: 대기 시간이 끝날 때 실행하도록 예약합니다.
    • trailing=false: 실행을 버립니다.

매개변수​

args​

...Parameters&lt;TFn>

반환값​

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

예시​

const throttled = new AsyncThrottler(fn, { wait: 1000 });

// First call executes immediately
await throttled.maybeExecute('a', 'b');

// Call during wait period - gets throttled
await throttled.maybeExecute('c', 'd');

예시​

const throttled = asyncThrottle(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  }
});

// This will execute at most once per second
// Returns the API response directly
const result = await throttled(inputElement.value);