@litert/utils

Appearance

Class: TokenBucketRateLimiter ​

Package: @litert/concurrentImport path: @litert/concurrentSource: packages/partials/concurrent/src/Classes/TokenBucketRateLimiter.tsImplements: ISyncRateLimiter

A synchronous rate limiter using the token bucket algorithm. The bucket holds up to capacity tokens. One token is consumed per call; one token is restored every refillIntervalMs milliseconds (up to capacity). If no tokens are available, the call is rejected immediately.

Constructor ​

ts
new TokenBucketRateLimiter(opts: ITokenBucketRateLimiterOptions)

See ITokenBucketRateLimiterOptions.

Throws:

  • TypeError — if capacity or refillIntervalMs is not a positive safe integer.
  • TypeError — if initialTokens is outside [0, capacity].

Methods ​

challenge() ​

ts
challenge(): void

Consumes one token. Throws if no tokens remain.

Throws: E_RATE_LIMITED (or custom error).

isBlocking() ​

ts
isBlocking(): boolean

Returns true when the bucket currently has zero tokens (after a lazy refill).

isIdle() ​

ts
isIdle(): boolean

Returns true when the bucket is full (no tokens have been consumed since the last full refill).

call(fn) ​

ts
call<TFn extends IFunction>(fn: TFn): ReturnType<TFn>

Calls fn after a successful challenge().

reset() ​

ts
reset(): void

Refills the bucket to capacity immediately.

wrap(fn) ​

ts
wrap<T extends IFunction>(fn: T): T

Returns a wrapper function that challenges the bucket before every call.

Example ​

ts
import { TokenBucketRateLimiter } from '@litert/concurrent';

const limiter = new TokenBucketRateLimiter({
    capacity: 10,
    refillIntervalMs: 100, // one token every 100ms
});

try {
    limiter.challenge();
    processRequest();
} catch {
    console.log('Too many requests');
}