Class: TokenBucketRateLimiterManager

Package: @litert/concurrentImport path: @litert/concurrentSource: packages/partials/concurrent/src/Classes/TokenBucketRateLimiterManager.tsImplements: ISyncRateLimiterManager

Manages a collection of per-key token-bucket rate limiters. Each unique key gets its own bucket with shared configuration. Idle buckets can be cleaned up automatically or on demand.

---

Constructor

new TokenBucketRateLimiterManager(opts: ITokenBucketRateLimiterManagerOptions)

See ITokenBucketRateLimiterManagerOptions.

Throws:

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

---

Methods

challenge(key)

challenge(key: string): void

Challenges the rate limiter for key. Throws if the bucket for that key has no tokens.

Throws: E_RATE_LIMITED (or custom error).

---

isBlocking(key)

isBlocking(key: string): boolean

Returns true if the bucket for key currently has no tokens.

---

call(key, fn)

call<T extends IFunction>(key: string, fn: T): ReturnType<T>

Calls fn after a successful challenge(key).

---

reset(key)

reset(key: string): void

Refills the bucket for key to capacity immediately.

---

clean()

clean(): void

Removes idle (full) bucket entries that have not been accessed for cleanDelayMs milliseconds. Has no effect if cleanDelayMs is 0.

---

Scoped Types

Interface ITokenBucketRateLimiterManagerOptions

Source: TokenBucketRateLimiterManager.ts

import type { ITokenBucketRateLimiterManagerOptions } from '@litert/concurrent';

interface ITokenBucketRateLimiterManagerOptions {
    capacity: number;
    initialTokens?: number;
    refillIntervalMs: number;
    cleanDelayMs?: number;
    errorCtorOnLimited?: IConstructor<Error>;
}

Property	Type	Default	Description
capacity	number	—	Bucket capacity per key
initialTokens	number?	capacity	Initial tokens per key
refillIntervalMs	number	—	Milliseconds per token refill
cleanDelayMs	number?	0	How long (ms) to keep a full, unused context before cleaning; 0 = disabled
errorCtorOnLimited	IConstructor<Error>?	E_RATE_LIMITED	Custom error class

---

Example

import { TokenBucketRateLimiterManager } from '@litert/concurrent';

const manager = new TokenBucketRateLimiterManager({
    capacity: 100,
    refillIntervalMs: 1000,  // one token per ms → 100 tokens per 100ms
    cleanDelayMs: 30_000,
});

function handleRequest(userId: string) {
    try {
        manager.challenge(userId);
        processRequest(userId);
    } catch {
        return tooManyRequests();
    }
}