본문으로 건너뛰기

클래스: AsyncRateLimiter<TFn>

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

비동기 요청률 제한 함수를 생성하는 클래스입니다.

비동기 버전과 동기 버전: 비동기 버전은 동기 RateLimiter보다 다음과 같은 고급 기능을 제공합니다.

  • 요청률이 제한된 함수의 결과를 기다릴 수 있도록 프로미스를 반환합니다
  • AsyncRetryer 통합을 통해 재시도를 기본으로 지원합니다
  • 진행 중인 실행을 취소할 수 있는 중단 기능을 지원합니다
  • onError 콜백과 throwOnError 제어 기능으로 포괄적인 오류 처리를 제공합니다
  • 실행을 상세히 추적합니다(성공/오류/완료 횟수, 거부 횟수)
  • 자동 정리 기능을 갖춘 더욱 정교한 윈도우 관리를 제공합니다

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

요청률 제한이란? 요청률 제한을 사용하면 시간 윈도우 안에서 한도까지 함수를 실행할 수 있으며, 이후에는 윈도우가 지날 때까지 모든 호출을 차단합니다. 이로 인해 모든 실행이 즉시 일어난 뒤 완전히 차단되는 "버스트성" 동작이 발생할 수 있습니다.

윈도우 유형:

  • 'fixed': 윈도우 기간이 지나면 재설정되는 엄격한 윈도우입니다. 윈도우 안의 모든 실행이 한도에 포함되며, 기간이 지나면 윈도우가 완전히 재설정됩니다.
  • 'sliding': 이전 실행이 만료됨에 따라 새 실행을 허용하는 이동식 윈도우입니다. 시간의 흐름에 따라 더 일정한 실행률을 제공합니다.

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

  • 스로틀: 실행 사이에 일정한 간격을 보장합니다(예: 200ms당 최대 한 번)
  • 디바운스: 호출이 잠시 멈출 때까지 기다린 후 실행합니다(예: 500ms 동안 호출이 없을 때)

상태 관리:

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

오류 처리:

  • onError 핸들러를 제공하면 오류 및 요청률 제한기 인스턴스와 함께 호출됩니다
  • throwOnError가 true이면(onError 핸들러를 제공하지 않았을 때의 기본값) 오류를 던집니다
  • throwOnError가 false이면(onError 핸들러를 제공했을 때의 기본값) 오류를 무시합니다
  • onError와 throwOnError를 함께 사용할 수 있으며, 오류를 던지기 전에 핸들러를 호출합니다
  • 기반 AsyncRateLimiter 인스턴스를 사용하여 오류 상태를 확인할 수 있습니다
  • 요청률 한도 초과에 따른 거부는 onReject 핸들러를 통해 실행 오류와 별도로 처리됩니다

예시​

const rateLimiter = new AsyncRateLimiter(
  async (id: string) => await api.getData(id),
  {
    limit: 5,
    window: 1000,
    windowType: 'sliding',
    onError: (error) => {
      console.error('API call failed:', error);
    },
    onReject: (limiter) => {
      console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);
    }
  }
);

// Will execute immediately until limit reached, then block
// Returns the API response directly
const data = await rateLimiter.maybeExecute('123');

타입 매개변수​

TFn​

TFn extends AnyAsyncFunction

생성자​

생성자​

new AsyncRateLimiter<TFn>(fn, initialOptions): AsyncRateLimiter<TFn>;

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

매개변수​

fn​

TFn

initialOptions​

AsyncRateLimiterOptions&lt;TFn>

반환값​

AsyncRateLimiter&lt;TFn>

속성​

asyncRetryers​

asyncRetryers: Map<number, AsyncRetryer<TFn>>;

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

fn​

fn: TFn;

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

key​

key: string | undefined;

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

options​

options: AsyncRateLimiterOptions<TFn>;

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

store​

readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>;

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

메서드​

abort()​

abort(): void;

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

내부 중단 컨트롤러로 진행 중인 모든 실행을 중단합니다. 실행 시각을 지우거나 요청률 제한기를 재설정하지는 않습니다.

반환값​

void

getAbortSignal()​

getAbortSignal(maybeExecuteCount?): AbortSignal | null;

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

특정 실행의 AbortSignal을 반환합니다. maybeExecuteCount를 제공하지 않으면 가장 최근 실행의 시그널을 반환합니다. 실행을 찾을 수 없거나 현재 실행 중이 아니면 null을 반환합니다.

매개변수​

maybeExecuteCount?​

number

시그널을 가져올 특정 실행을 선택적으로 지정합니다

반환값​

AbortSignal | null

예시​

const rateLimiter = new AsyncRateLimiter(
  async (userId: string) => {
    const signal = rateLimiter.getAbortSignal()
    if (signal) {
      const response = await fetch(`/api/users/${userId}`, { signal })
      return response.json()
    }
  },
  { limit: 5, window: 1000 }
)

getMsUntilNextWindow()​

getMsUntilNextWindow(): number;

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

다음 실행이 가능해질 때까지 남은 밀리초 수를 반환합니다 고정 윈도우에서는 현재 윈도우가 재설정될 때까지의 시간입니다 슬라이딩 윈도우에서는 가장 오래된 실행이 만료될 때까지의 시간입니다

반환값​

number

getRemainingInWindow()​

getRemainingInWindow(): number;

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

현재 윈도우에서 허용되는 남은 실행 횟수를 반환합니다

반환값​

number

maybeExecute()​

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

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

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

오류 처리:

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

매개변수​

args​

...Parameters&lt;TFn>

반환값​

Promise&lt;Awaited&lt;ReturnType&lt;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

reset()​

reset(): void;

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

요청률 제한기의 상태를 재설정합니다

반환값​

void

setOptions()​

setOptions(newOptions): void;

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

비동기 요청률 제한기 옵션을 업데이트합니다

매개변수​

newOptions​

Partial&lt;AsyncRateLimiterOptions&lt;TFn>>

반환값​

void