类：AsyncRateLimiter<TFn>

定义于：async-rate-limiter.ts:127

一个创建异步速率限制函数的类。

速率限制是一种简单的方法，它允许函数在时间窗口内执行达到限制的次数，然后阻止所有后续调用，直到窗口过去。这可能导致“突发”行为，即所有执行立即发生，然后是完全阻塞。

速率限制器支持两种类型的窗口：

'fixed'：一个严格的窗口，在窗口期过后重置。窗口内的所有执行都计入限制，并且窗口在期满后完全重置。
'sliding'：一个滚动窗口，允许随着旧执行的过期而执行。这提供了一个更随时间推移更一致的执行速率。

与非异步 RateLimiter 不同，此异步版本支持从速率限制函数返回值，使其非常适合 API 调用和其他异步操作，在这些操作中，您希望获得 maybeExecute 调用的结果而不是在速率限制函数内部设置状态变量的结果。

对于更平滑的执行模式，请考虑使用：

节流：确保执行之间具有一致的间距（例如，每 200 毫秒最多一次）
防抖：在执行前等待调用暂停（例如，在没有调用 500 毫秒后）

速率限制最适合用于硬 API 限制或资源约束。对于 UI 更新或平滑频繁事件，节流或防抖通常提供更好的用户体验。

错误处理：

如果提供了 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 调用失败：', error);
    },
    onReject: (limiter) => {
      console.log(`已超出速率限制。请在 ${limiter.getMsUntilNextWindow()} 毫秒后重试`);
    }
  }
);

// 将立即执行直到达到限制，然后阻塞
// 直接返回 API 响应
const data = await rateLimiter.maybeExecute('123');

const rateLimiter = new AsyncRateLimiter(
  async (id: string) => await api.getData(id),
  {
    limit: 5,
    window: 1000,
    windowType: 'sliding',
    onError: (error) => {
      console.error('API 调用失败：', error);
    },
    onReject: (limiter) => {
      console.log(`已超出速率限制。请在 ${limiter.getMsUntilNextWindow()} 毫秒后重试`);
    }
  }
);

// 将立即执行直到达到限制，然后阻塞
// 直接返回 API 响应
const data = await rateLimiter.maybeExecute('123');

类型参数

• TFn extends AnyAsyncFunction

构造函数

new AsyncRateLimiter()

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

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

定义于：async-rate-limiter.ts:137

参数

fn

TFn

initialOptions

AsyncRateLimiterOptions<TFn>

AsyncRateLimiter<TFn>

方法

getEnabled()

getEnabled(): boolean

getEnabled(): boolean

定义于：async-rate-limiter.ts:165

返回速率限制器的当前启用状态

boolean

getErrorCount()

getErrorCount(): number

getErrorCount(): number

定义于：async-rate-limiter.ts:324

返回函数出错的次数

number

getIsExecuting()

getIsExecuting(): boolean

getIsExecuting(): boolean

定义于：async-rate-limiter.ts:338

返回函数当前是否正在执行

boolean

getLimit()

getLimit(): number

getLimit(): number

定义于：async-rate-limiter.ts:172

返回时间窗口内允许的当前执行限制

number

getMsUntilNextWindow()

getMsUntilNextWindow(): number

getMsUntilNextWindow(): number

定义于：async-rate-limiter.ts:299

返回距离下一次可能执行的毫秒数对于固定窗口，这是当前窗口重置之前的时间对于滑动窗口，这是最旧的执行过期之前的时间

number

getOptions()

getOptions(): AsyncRateLimiterOptions<TFn>

getOptions(): AsyncRateLimiterOptions<TFn>

定义于：async-rate-limiter.ts:158

返回当前速率限制器选项

AsyncRateLimiterOptions<TFn>

getRejectionCount()

getRejectionCount(): number

getRejectionCount(): number

定义于：async-rate-limiter.ts:331

返回函数被拒绝的次数

number

getRemainingInWindow()

getRemainingInWindow(): number

getRemainingInWindow(): number

定义于：async-rate-limiter.ts:289

返回当前窗口中允许的剩余执行次数

number

getSettleCount()

getSettleCount(): number

getSettleCount(): number

定义于：async-rate-limiter.ts:317

返回函数已完成的次数

number

getSuccessCount()

getSuccessCount(): number

getSuccessCount(): number

定义于：async-rate-limiter.ts:310

返回函数已执行的次数

number

getWindow()

getWindow(): number

getWindow(): number

定义于：async-rate-limiter.ts:179

返��当前时间窗口（以毫秒为单位）

number

maybeExecute()

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

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

定义于：async-rate-limiter.ts:212

如果符合配置的限制，则尝试执行速率限制函数。如果当前窗口中的调用次数超出限制，则将拒绝执行。如果允许执行，则在继续之前等待任何先前的执行完成。

错误处理：

如果速率限制函数抛出错误并且未配置 onError 处理程序，则此方法将抛出错误。
如果配置了 onError 处理程序，错误将被捕获并传递给处理程序，并且此方法将返回 undefined。
如果超出速率限制，则将拒绝执行，并且如果已配置，则将调用 onReject 处理程序。
可以使用 getErrorCount() 和 getIsExecuting() 检查错误状态。
可以使用 getRejectionCount() 跟踪速率限制拒绝。

参数

args

...Parameters<TFn>

Promise<undefined | ReturnType<TFn>>

一个 Promise，它解析为函数的返回值，如果发生错误并由 onError 处理，则解析为 undefined

抛出

如果未配置 onError 处理程序，则抛出速率限制函数的错误

示例

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

// 前 5 次调用将执行
await rateLimiter.maybeExecute('arg1', 'arg2');

// 窗口内的其他调用将被拒绝
await rateLimiter.maybeExecute('arg1', 'arg2'); // 已拒绝

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

// 前 5 次调用将执行
await rateLimiter.maybeExecute('arg1', 'arg2');

// 窗口内的其他调用将被拒绝
await rateLimiter.maybeExecute('arg1', 'arg2'); // 已拒绝

reset()

reset(): void

reset(): void

定义于：async-rate-limiter.ts:345

重置速率限制器状态

void

setOptions()

setOptions(newOptions): void

setOptions(newOptions): void

定义于：async-rate-limiter.ts:151

更新速率限制器选项

参数

newOptions

Partial<AsyncRateLimiterOptions<TFn>>

void