함수: asyncRateLimit()

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

정의 위치: async-rate-limiter.ts:642

시간 윈도우 안에서 제공된 함수를 최대 횟수까지 실행하는 비동기 요청률 제한 함수를 생성합니다.

비동기 버전과 동기 버전: 비동기 버전은 동기 요청률 제한 함수보다 다음과 같은 고급 기능을 제공합니다.

• 요청률 제한 함수 결과를 기다릴 수 있는 프로미스를 반환합니다.
• AsyncRetryer 통합을 통한 내장 재시도 기능을 제공합니다.
• 진행 중인 실행을 취소하는 중단 기능을 제공합니다.
• onError 콜백과 throwOnError 제어를 통한 포괄적인 오류 처리를 제공합니다.
• 세부 실행 정보(성공/오류/완료 횟수, 거부 횟수)를 추적합니다.
• 자동 정리를 포함한 정교한 윈도우 관리를 제공합니다.

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

요청률 제한이란? 요청률 제한은 시간 윈도우 안에서 한도까지 함수 실행을 허용한 뒤 윈도우가 지날 때까지 이후 모든 호출을 차단합니다. 모든 실행이 즉시 몰린 후 완전히 차단되는 "버스트형" 동작이 발생할 수 있습니다.

윈도우 유형:

• 'fixed': 윈도우 기간이 지나면 초기화되는 엄격한 윈도우입니다. 윈도우 안의 모든 실행이 한도에 포함되며 기간이 지나면 윈도우가 완전히 초기화됩니다.
• 'sliding': 이전 실행이 만료됨에 따라 실행을 허용하는 롤링 윈도우입니다. 시간에 걸쳐 더 일정한 실행률을 제공합니다.

설정 옵션:

• limit: 윈도우 안에서 허용되는 최대 실행 횟수(필수)
• window: 시간 윈도우(밀리초, 필수)
• windowType: 'fixed' 또는 'sliding'(기본값: 'fixed')
• enabled: 요청률 제한기 활성화 여부(기본값: true)
• asyncRetryerOptions: 실행의 재시도 동작 설정

요청률 제한을 사용해야 하는 경우: 요청률 제한은 엄격한 API 한도나 리소스 제약에 가장 적합합니다. UI 업데이트나 빈번한 이벤트를 완화하는 경우에는 일반적으로 스로틀링이나 디바운싱이 더 나은 사용자 경험을 제공합니다.

• 요청률 제한기는 한도에 도달할 때까지 모든 실행을 허용한 뒤 윈도우가 초기화될 때까지 이후 모든 호출을 차단합니다.
• 스로틀러는 실행 간격을 일정하게 유지하므로 일관된 성능에 더 적합할 수 있습니다.
• 디바운서는 여러 호출을 하나로 합치므로 이벤트 버스트 처리에 더 적합합니다.

오류 처리:

• onError 핸들러를 제공하면 오류 및 요청률 제한기 인스턴스와 함께 호출됩니다.
• throwOnError가 true이면(onError 핸들러가 없을 때의 기본값) 오류가 발생합니다.
• throwOnError가 false이면(onError 핸들러가 있을 때의 기본값) 오류가 처리된 것으로 간주됩니다.
• onError와 throwOnError를 함께 사용할 수 있으며 오류가 발생하기 전에 핸들러가 호출됩니다.
• 내부 AsyncRateLimiter 인스턴스를 사용해 오류 상태를 확인할 수 있습니다.
• 요청률 제한 거부(한도 초과 시)는 onReject 핸들러를 통해 실행 오류와 별도로 처리됩니다.

상태 관리:

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

타입 매개변수

TFn

TFn extends AnyAsyncFunction

매개변수

fn

TFn

initialOptions

AsyncRateLimiterOptions<TFn>

반환값

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

설정된 한도 안이면 요청률 제한 함수 실행을 시도합니다. 현재 윈도우의 호출 수가 한도를 초과하면 실행을 거부합니다.

오류 처리:

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

매개변수

args

...Parameters<TFn>

반환값

Promise<Awaited<ReturnType<TFn>> | undefined>

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

발생 오류

onError 핸들러가 설정되지 않았을 때 발생한 요청률 제한 함수의 오류입니다.

예시

const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });

// First 5 calls will return a promise that resolves with the result
const result = await rateLimiter.maybeExecute('arg1', 'arg2');

// Additional calls within the window will return undefined
const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined

예시

// Rate limit to 5 calls per minute with a sliding window
const rateLimited = asyncRateLimit(makeApiCall, {
  limit: 5,
  window: 60000,
  windowType: 'sliding',
  onError: (error) => {
    console.error('API call failed:', error);
  },
  onReject: (rateLimiter) => {
    console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  }
});

// First 5 calls will execute immediately
// Additional calls will be rejected until the minute window resets
// Returns the API response directly
const result = await rateLimited();

// For more even execution, consider using throttle instead:
const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds