Module @dws-std/elysia-ratelimit - v1.0.0

🚦 DWS Elysia Rate Limit

Rate limiting for Elysia routes, guards, and groups, as a macro.
Drop rateLimit on any endpoint and abusive traffic gets cut before it ever hits your logic.

Why this package?

This plugin uses Elysia's macro system to add rate limiting to any route, guard, or group.
You add rateLimit: { limit: 10, window: 60 } and you're done.

By default it limits by client IP, which works great for auth endpoints.
For cases where many users share the same public IP (offices, corporate proxies), you can pass a keyGenerator to rate limit by IP + access token, session ID, API key, or any combination that makes sense.

Storage is handled by @dws-std/kv-store, so you start with in-memory and move to Redis when you need to, without changing your routes.

✨ Features

🎯 Per-route macros : Attach rateLimit to any route independently, with its own limit and window.
🔑 Custom key generation : Rate limit by IP (default), IP + token, session, or any key you compute.
🗃️ KvStore-agnostic : Works with MemoryStore out of the box; swap in BunRedisStore or your own adapter.
⚡ Early rejection : Runs in transform, the first per-route hook, before auth guards and handlers.
📡 Standard headers : Automatically sets X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

🔧 Installation

bun add @dws-std/elysia-ratelimit

Peer dependencies: elysia must be installed alongside.

⚙️ Usage

Basic - rate limit by IP

The simplest form: pass limit (max requests) and window (time in seconds). Each client IP gets its own counter.

import { rateLimitPlugin } from '@dws-std/elysia-ratelimit';
import { Elysia } from 'elysia';

new Elysia()
	.use(rateLimitPlugin())
	.post('/auth/login', () => authenticate(), {
		rateLimit: { limit: 10, window: 60 } // 10 requests per minute per IP
	})
	.listen(3000);

Custom store - Redis

By default, counters are kept in memory. Pass a BunRedisStore (or any KvStore adapter) for persistence across restarts and multi-instance deployments.

import { BunRedisStore } from '@dws-std/kv-store';
import { rateLimitPlugin } from '@dws-std/elysia-ratelimit';
import { Elysia } from 'elysia';

const store = new BunRedisStore('redis://localhost:6379');

new Elysia()
	.use(rateLimitPlugin(store))
	.post('/auth/login', () => authenticate(), {
		rateLimit: { limit: 10, window: 60 }
	})
	.listen(3000);

Custom key generation - IP + access token

Useful for authenticated routes where many users share the same public IP (office, corporate proxy).
Each user has their own counter, independent of their network.

import { rateLimitPlugin } from '@dws-std/elysia-ratelimit';
import { Elysia } from 'elysia';

new Elysia()
	.use(rateLimitPlugin())
	.get('/api/data', () => getData(), {
		rateLimit: {
			limit: 100,
			window: 60,
			keyGenerator: ({ ip, request }) => `${ip}:${request.headers.get('authorization') ?? ip}`
		}
	})
	.listen(3000);