@clov-std/elysia-ratelimit 1.2.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/ClovLabs/std@main/packages/elysia-ratelimit/logo-elysia-ratelimit.png" alt="Clov Elysia Rate Limit logo" width="200" />
+</p>
+
+# 🚦 Clov 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 `@clov-std/kv-store`, so you start with in-memory and move to Redis when you need to, without changing your routes.
+
+## 📌 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [API Reference](#-api-reference)
+- [License](#-license)
+- [Contact](#-contact)
+
+## ✨ 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
+
+```bash
+bun add @clov-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.
+
+```ts
+import { rateLimitPlugin } from '@clov-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.
+
+```ts
+import { BunRedisStore } from '@clov-std/kv-store';
+import { rateLimitPlugin } from '@clov-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.
+
+```ts
+import { rateLimitPlugin } from '@clov-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);
+```
+
+> **Tip:** `extractClientIp` is exported if you need it inside your own `keyGenerator`.
+
+## 📚 API Reference
+
+Full docs: [https://clovlabs.github.io/std/](https://clovlabs.github.io/std/)
+
+## ⚖️ License
+
+MIT — see [LICENSE.md](LICENSE.md).
+
+## 📧 Contact
+
+Maintained by [Clov](https://github.com/ClovLabs).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { extractClientIp, RATE_LIMIT_ERROR_KEYS, rateLimitPlugin, type RateLimitKeyContext, type RateLimitMacroOptions } from './rate-limit';
+export { rateLimitContract } from './rate-limit.contract';

package/dist/index.js

@@ -0,0 +1,69 @@
+// @bun
+// src/rate-limit.ts
+import { HttpException } from "@clov-std/error";
+import { MemoryStore } from "@clov-std/kv-store";
+import { Elysia } from "elysia";
+
+// src/rate-limit.contract.ts
+import { t } from "elysia";
+var rateLimitContract = {
+  429: t.Object({
+    message: t.String({
+      description: "Error message indicating that the rate limit has been exceeded."
+    })
+  })
+};
+
+// src/rate-limit.ts
+var RATE_LIMIT_ERROR_KEYS = {
+  RATE_LIMIT_EXCEEDED: "elysia-ratelimit.exceeded"
+};
+var extractClientIp = (request, server) => {
+  const forwarded = request.headers.get("x-forwarded-for");
+  if (forwarded) {
+    const [first] = forwarded.split(",");
+    if (first)
+      return first.trim();
+  }
+  return request.headers.get("x-real-ip") ?? server?.requestIP(request)?.address ?? "127.0.0.1";
+};
+var rateLimitPlugin = (store = new MemoryStore) => new Elysia({
+  name: "rateLimitPlugin",
+  seed: store
+}).model({
+  RateLimitError: rateLimitContract[429]
+}).macro({
+  rateLimit: ({ limit, window, keyGenerator }) => ({
+    response: {
+      429: "RateLimitError"
+    },
+    transform: async ({ set, request, server }) => {
+      const route = `${request.method}:${new URL(request.url).pathname}`;
+      const ip = extractClientIp(request, server);
+      const discriminator = keyGenerator ? keyGenerator({ request, server, ip }) : ip;
+      const key = `ratelimit:${route}:${discriminator}`;
+      const count = await store.increment(key);
+      if (count === 1)
+        await store.expire(key, window);
+      const remaining = Math.max(0, limit - count);
+      const resetTime = await store.ttl(key);
+      set.headers["X-RateLimit-Limit"] = limit.toString();
+      set.headers["X-RateLimit-Remaining"] = remaining.toString();
+      set.headers["X-RateLimit-Reset"] = resetTime.toString();
+      if (count > limit) {
+        set.status = 429;
+        throw new HttpException("Too Many Requests", {
+          key: RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED,
+          cause: { limit, window, remaining: 0, reset: resetTime },
+          status: 429
+        });
+      }
+    }
+  })
+});
+export {
+  rateLimitPlugin,
+  rateLimitContract,
+  extractClientIp,
+  RATE_LIMIT_ERROR_KEYS
+};

package/dist/rate-limit.contract.d.ts

@@ -0,0 +1,5 @@
+export declare const rateLimitContract: {
+    429: import("@sinclair/typebox").TObject<{
+        message: import("@sinclair/typebox").TString;
+    }>;
+};

package/dist/rate-limit.d.ts

@@ -0,0 +1,52 @@
+import { type KvStore } from '@clov-std/kv-store';
+import type { Server } from 'bun';
+import { Elysia, type HTTPHeaders, type StatusMap } from 'elysia';
+import { rateLimitContract } from './rate-limit.contract';
+export declare const RATE_LIMIT_ERROR_KEYS: {
+    readonly RATE_LIMIT_EXCEEDED: "elysia-ratelimit.exceeded";
+};
+export interface RateLimitKeyContext {
+    request: Request;
+    server: Server<unknown> | null;
+    ip: string;
+}
+export interface RateLimitMacroOptions {
+    limit: number;
+    window: number;
+    keyGenerator?: (context: RateLimitKeyContext) => string;
+}
+export declare const extractClientIp: (request: Request, server: Server<unknown> | null) => string;
+export declare const rateLimitPlugin: (store?: KvStore) => Elysia<"rateLimitPlugin", {
+    decorator: {};
+    derive: {};
+    resolve: {};
+    store: {};
+}, {
+    typebox: {
+        RateLimitError: (typeof rateLimitContract)[429];
+    };
+    error: {};
+}, {
+    macro: Partial<{
+        readonly rateLimit: RateLimitMacroOptions;
+    }>;
+    macroFn: {
+        rateLimit: (options: RateLimitMacroOptions) => {
+            response: {
+                429: "RateLimitError";
+            };
+            transform: ({ set, request, server }: {
+                set: {
+                    headers: HTTPHeaders;
+                    status?: number | keyof StatusMap;
+                };
+                request: Request;
+                server: Server<unknown> | null;
+            }) => Promise<void>;
+        };
+    };
+    parser: {};
+    response: {};
+    schema: {};
+    standaloneSchema: {};
+}>;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@clov-std/elysia-ratelimit",
+  "version": "1.2.1",
+  "description": "Rate limiting plugin for Elysia framework.",
+  "keywords": [
+    "bun",
+    "clov",
+    "elysia",
+    "macro",
+    "open-source",
+    "plugin",
+    "ratelimit",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Clov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ClovLabs/std",
+    "directory": "packages/elysia-ratelimit"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun builder.ts",
+    "docs": "bunx typedoc --tsconfig tsconfig.build.json",
+    "fmt:check": "oxfmt --check",
+    "fmt": "oxfmt",
+    "lint:fix": "oxlint --type-aware --type-check --fix ./src",
+    "lint:github": "oxlint --type-aware --type-check --format=github ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "bun test --pass-with-no-tests --coverage"
+  },
+  "dependencies": {
+    "@clov-std/error": "workspace:^",
+    "@clov-std/kv-store": "workspace:^",
+    "elysia": "^1.4.29"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:base",
+    "oxfmt": "catalog:base",
+    "oxlint": "catalog:base",
+    "oxlint-tsgolint": "catalog:base",
+    "typescript": "catalog:base"
+  },
+  "peerDependencies": {
+    "@clov-std/error": "workspace:^",
+    "@clov-std/kv-store": "workspace:^",
+    "elysia": "^1.4.29"
+  }
+}