Limiter

^{ref / ratelimiter / Limiter}

A fluent API builder for constructing rate-limiter rules.

^Source

Type Parameters

C

C extends GrammyContext

Constructors

Limiter();

^Source

Methods

fixedWindow

fixedWindow(options: { limit: number | DynamicLimitGenerator<C>; timeFrame: number }): this;

Sets the limiting strategy to Fixed Window.

^Source

tokenBucket

tokenBucket(options: {
bucketSize: number; tokensPerInterval: number; interval: number
}): this;

Sets the limiting strategy to Token Bucket.

^Source

customStrategy

customStrategy(strategy: ILimiterStrategy<unknown>): this;

Sets a custom limiting strategy.

^Source

useStorage

useStorage(storage: IStorageEngine): this;

Sets the storage engine for the rule.

^Source

limitFor

limitFor(scope: "user" | "chat" | "global" | KeyGenerator<C>): this;

Defines what entity to rate-limit.

^Source

on

on<E extends keyof LimiterEvents<C>>(eventName: E, listener: (...args: LimiterEvents<C>[E]) => void): this;

Registers an event listener for this limiter instance. This allows for observing the limiter’s behavior for logging or analytics.

^Source

off

off<E extends keyof LimiterEvents<C>>(eventName: E, listener: (...args: LimiterEvents<C>[E]) => void): this;

Unregisters an event listener.

^Source

withKeyPrefix

withKeyPrefix(prefix: string): this;

Sets a prefix for all keys generated for this rule. Useful for preventing key collisions between different rules in the same storage.

^Source

onlyIf

onlyIf(predicate: (ctx: C) => boolean | Promise<boolean>): this;

Rate limiter will only run if this function returns true.

^Source

onThrottled

onThrottled(handler: OnLimitExceeded<C>): this;

Defines the callback to execute when a request is throttled (rate-limited).

^Source

withPenalty

withPenalty(options: { penaltyTime: number | PenaltyDurationGenerator<C>; penaltyKeyPrefix?: string }): this;

Enables and configures the “Penalty Box” feature.

^Source

build

build(): Rule<C>;

Finalizes the configuration and returns a validated Rule instance.

^Source