grammY Throttler

@grammyjs/transformer-throttler is an API transformer plugin for the grammY Telegram bot framework that limits and queues outgoing Telegram API calls so your bot conforms to the official Telegram rate limits. It is written in TypeScript and built on the Bottleneck rate limiter.

Installing the throttler is a one-liner, bot.api.config.use(apiThrottler()), after which global, per-group, and per-private-chat queues automatically pace your requests. Sensible defaults suit most bots, while every queue is fully configurable through Bottleneck constructor options.

What You Get

• An apiThrottler() transformer you register with bot.api.config.use
• Separate global, group, and out (private) throttle queues
• Sensible default reservoirs and intervals aligned with Telegram limits
• Full configurability via Bottleneck ConstructorOptions per queue
• An experimental bypassThrottler middleware for first responses

Common Use Cases

• Preventing a Telegram bot from exceeding official API rate limits
• Queuing bursts of outgoing messages so they send at a safe pace
• Tuning per-group and per-chat send rates for a high-traffic bot
• Adding rate limiting to a grammY bot with a single config line

Under The Hood

Architecture The entire plugin lives in src/mod.ts. It exports apiThrottler(), which returns a grammY Transformer that intercepts every outgoing API call and routes it through one of three Bottleneck instances: a global limiter, a group limiter keyed by chat id for group/supergroup sends, and an out limiter for private chats. Each call is wrapped so it must pass the global queue plus the relevant per-scope queue before reaching Telegram. A companion bypassThrottler middleware temporarily registers a config transformer that lets the first update-initiated response skip the queue, tracked via a shared skip set. Platform dependency shims (deps.node.ts and deps.deno.ts) let the same source target both Node and Deno.

Tech Stack TypeScript compiled for dual Node and Deno distribution, with bottleneck as the sole runtime dependency and grammy (>=1.0.0) as a peer dependency. Bottleneck provides the reservoir-based rate limiting and job scheduling that powers each queue.

Code Quality The implementation is small and focused, with clearly named configuration objects and typed options mirroring Bottleneck’s constructor. There is no dedicated automated test suite in the repository, which is common for a thin transformer of this size; correctness rests on Bottleneck’s well-tested scheduling and grammY’s transformer contract. Documentation in the README is thorough, covering defaults and configuration.

API Design The API is deliberately minimal: apiThrottler(opts?) takes an optional object with global, group, and out Bottleneck configs, and integration is a single bot.api.config.use(...) call. Defaults work out of the box, so most users need no configuration at all, while advanced users get the full surface of Bottleneck options. The optional bypassThrottler is clearly marked experimental.