@clov-std/elysia-ratelimit 1.2.1 → 3.0.0

package/README.md

@@ -22,6 +22,7 @@ Storage is handled by `@clov-std/kv-store`, so you start with in-memory and move
 - [Features](#-features)
 - [Installation](#-installation)
 - [Usage](#-usage)
+- [Error handling](#-error-handling)
 - [API Reference](#-api-reference)
 - [License](#-license)
 - [Contact](#-contact)
@@ -33,14 +34,15 @@ Storage is handled by `@clov-std/kv-store`, so you start with in-memory and move
 - 🗃️ **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`.
+- 🧯 **Works with or without an error plugin** : Answers a real `429` on its own, and steps aside when your application handles the error itself.
 
 ## 🔧 Installation
 
 ```bash
-bun add @clov-std/elysia-ratelimit
+bun add @clov-std/elysia-ratelimit elysia typebox
 ```
 
-> **Peer dependencies:** `elysia` must be installed alongside.
+> **Peer dependencies:** `elysia` (v2) and `typebox` must be installed alongside.
 
 ## ⚙️ Usage
 
@@ -54,9 +56,11 @@ import { Elysia } from 'elysia';
 
 new Elysia()
 	.use(rateLimitPlugin())
-	.post('/auth/login', () => authenticate(), {
-		rateLimit: { limit: 10, window: 60 } // 10 requests per minute per IP
-	})
+	.post(
+		'/auth/login',
+		{ rateLimit: { limit: 10, window: 60 } }, // 10 requests per minute per IP
+		() => authenticate()
+	)
 	.listen(3000);
 ```
 
@@ -73,9 +77,7 @@ const store = new BunRedisStore('redis://localhost:6379');
 
 new Elysia()
 	.use(rateLimitPlugin(store))
-	.post('/auth/login', () => authenticate(), {
-		rateLimit: { limit: 10, window: 60 }
-	})
+	.post('/auth/login', { rateLimit: { limit: 10, window: 60 } }, () => authenticate())
 	.listen(3000);
 ```
 
@@ -90,18 +92,77 @@ 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}`
-		}
-	})
+	.get(
+		'/api/data',
+		{
+			rateLimit: {
+				limit: 100,
+				window: 60,
+				keyGenerator: ({ ip, request }) =>
+					`${ip}:${request.headers.get('authorization') ?? ip}`
+			}
+		},
+		() => getData()
+	)
 	.listen(3000);
 ```
 
 > **Tip:** `extractClientIp` is exported if you need it inside your own `keyGenerator`.
 
+## 🧯 Error handling
+
+When the allowance is exceeded, the plugin throws a `RateLimitException` carrying:
+
+- `key` — always `RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED`, i.e. `'elysia-ratelimit.exceeded'`
+- `cause` — `{ limit, window, reset }`, the counter state at that moment
+- `status` and `response` — the default answer, read by Elysia's error fallback
+
+### Without an error plugin
+
+The default applies and the route answers a real `429`, which is also the response the macro
+declares for OpenAPI:
+
+```json
+{ "type": "elysia-ratelimit.exceeded", "title": "Too Many Requests" }
+```
+
+The `X-RateLimit-*` headers are set before the throw, so they are present on the `429` as well.
+
+### With an error plugin
+
+That default is only a fallback. Any `.error()` handler your application registers runs first and
+wins, which is how an API answers with its own localized body.
+
+```ts
+import { RateLimitException, rateLimitPlugin } from '@clov-std/elysia-ratelimit';
+import { Elysia, status } from 'elysia';
+
+new Elysia()
+	.error(RateLimitException, ({ error }) =>
+		status(429, {
+			type: 'request.rateLimitExceeded',
+			title: 'Too many requests. Please try again later.',
+			detail: `Retry in ${error.cause?.reset ?? 0}s.`
+		})
+	)
+	.use(rateLimitPlugin())
+	.get('/api/data', { rateLimit: { limit: 100, window: 60 } }, () => getData())
+	.listen(3000);
+```
+
+Matching on the key works too, if you would rather not import the class:
+
+```ts
+.error(({ error }) =>
+	(error as { key?: string }).key === RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED
+		? status(429, { type: 'request.rateLimitExceeded', title: 'Too many requests.' })
+		: status(500, { type: 'internal', title: 'Internal Server Error' })
+)
+```
+
+> **Note:** Elysia runs the first matching `.error()` handler. If your error plugin registers a
+> catch-all, register it after the specific handlers, otherwise it swallows them.
+
 ## 📚 API Reference
 
 Full docs: [https://clovlabs.github.io/std/](https://clovlabs.github.io/std/)

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,23 +1,36 @@
 // @bun
 // src/rate-limit.ts
-import { HttpException } from "@clov-std/error";
+import { Exception } 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
+import { Elysia, t } from "elysia";
 var RATE_LIMIT_ERROR_KEYS = {
   RATE_LIMIT_EXCEEDED: "elysia-ratelimit.exceeded"
 };
+var rateLimitResponseSchema = t.Object({
+  type: t.String({
+    description: `Error key. Defaults to \`${RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED}\`.`
+  }),
+  title: t.String({
+    description: "Short, human-readable summary of the error."
+  }),
+  detail: t.Optional(t.String({
+    description: "Explanation specific to this occurrence."
+  }))
+});
+
+class RateLimitException extends Exception {
+  status = 429;
+  response = {
+    type: RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED,
+    title: "Too Many Requests"
+  };
+  constructor(cause) {
+    super("Too Many Requests", {
+      key: RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED,
+      cause
+    });
+  }
+}
 var extractClientIp = (request, server) => {
   const forwarded = request.headers.get("x-forwarded-for");
   if (forwarded) {
@@ -27,16 +40,9 @@ var extractClientIp = (request, server) => {
   }
   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({
+var rateLimitPlugin = (store = new MemoryStore) => new Elysia().macro({
   rateLimit: ({ limit, window, keyGenerator }) => ({
-    response: {
-      429: "RateLimitError"
-    },
+    response: { 429: rateLimitResponseSchema },
     transform: async ({ set, request, server }) => {
       const route = `${request.method}:${new URL(request.url).pathname}`;
       const ip = extractClientIp(request, server);
@@ -46,24 +52,18 @@ var rateLimitPlugin = (store = new MemoryStore) => new Elysia({
       if (count === 1)
         await store.expire(key, window);
       const remaining = Math.max(0, limit - count);
-      const resetTime = await store.ttl(key);
+      const reset = 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
-        });
-      }
+      set.headers["X-RateLimit-Reset"] = reset.toString();
+      if (count > limit)
+        throw new RateLimitException({ limit, window, reset });
     }
   })
 });
 export {
   rateLimitPlugin,
-  rateLimitContract,
   extractClientIp,
+  RateLimitException,
   RATE_LIMIT_ERROR_KEYS
 };

package/dist/rate-limit.d.ts

@@ -1,10 +1,55 @@
+import { Exception } from '@clov-std/error';
 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';
+import { Elysia, type HTTPHeaders } from 'elysia';
 export declare const RATE_LIMIT_ERROR_KEYS: {
-    readonly RATE_LIMIT_EXCEEDED: "elysia-ratelimit.exceeded";
+    readonly RATE_LIMIT_EXCEEDED: 'elysia-ratelimit.exceeded';
 };
+/** Counter state at the moment the limit was exceeded, attached as the exception `cause`. */
+export interface RateLimitExceeded {
+    /** Maximum requests allowed within the window. */
+    readonly limit: number;
+    /** Window length in seconds. */
+    readonly window: number;
+    /** Seconds until the counter resets. */
+    readonly reset: number;
+}
+/**
+ * Shape of the `429` body.
+ *
+ * `type` is a plain string, not a literal: an application error handler is free to answer
+ * with its own key (a localized catalog entry, for instance). `detail` is optional for the
+ * same reason, the plugin never sets it.
+ */
+declare const rateLimitResponseSchema: import("typebox").TObject<{
+    type: import("typebox").TString;
+    title: import("typebox").TString;
+    detail: import("typebox").TOptional<import("typebox").TString>;
+}>;
+/**
+ * Thrown when a caller exceeds its allowance.
+ *
+ * `status` and `response` are read by Elysia's error fallback, so an application that
+ * installs no error handler still answers a real `429` with the documented body. They are
+ * only a default: any `.error()` handler registered by the application runs first and wins,
+ * which is what lets an API localize this error from its own catalog. Match on
+ * {@link Exception.key}, not on the message.
+ */
+export declare class RateLimitException extends Exception<RateLimitExceeded> {
+    /** HTTP status used by Elysia's error fallback. */
+    readonly status = 429;
+    /** Default body used by Elysia's error fallback. */
+    readonly response: {
+        readonly type: string;
+        readonly title: string;
+    };
+    /**
+     * Creates a new rate limit exception.
+     *
+     * @param cause - Counter state at the moment the limit was exceeded.
+     */
+    constructor(cause: RateLimitExceeded);
+}
 export interface RateLimitKeyContext {
     request: Request;
     server: Server<unknown> | null;
@@ -15,38 +60,37 @@ export interface RateLimitMacroOptions {
     window: number;
     keyGenerator?: (context: RateLimitKeyContext) => string;
 }
+interface RateLimitTransformContext {
+    set: {
+        headers: HTTPHeaders;
+    };
+    request: Request;
+    server: Server<unknown> | null;
+}
+type RateLimitMacro = (options: RateLimitMacroOptions) => {
+    response: {
+        429: typeof rateLimitResponseSchema;
+    };
+    transform: (context: RateLimitTransformContext) => Promise<void>;
+};
 export declare const extractClientIp: (request: Request, server: Server<unknown> | null) => string;
-export declare const rateLimitPlugin: (store?: KvStore) => Elysia<"rateLimitPlugin", {
+export declare const rateLimitPlugin: (store?: KvStore) => Elysia<'', 'local', {
     decorator: {};
     derive: {};
-    resolve: {};
     store: {};
 }, {
-    typebox: {
-        RateLimitError: (typeof rateLimitContract)[429];
-    };
-    error: {};
+    typebox: {};
+    error: [];
 }, {
+    schema: {};
+    schemas: {};
     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>;
-        };
+        rateLimit: RateLimitMacro;
     };
     parser: {};
     response: {};
-    schema: {};
-    standaloneSchema: {};
 }>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clov-std/elysia-ratelimit",
-  "version": "1.2.1",
+  "version": "3.0.0",
   "description": "Rate limiting plugin for Elysia framework.",
   "keywords": [
     "bun",
@@ -40,20 +40,20 @@
     "test": "bun test --pass-with-no-tests --coverage"
   },
   "dependencies": {
-    "@clov-std/error": "workspace:^",
-    "@clov-std/kv-store": "workspace:^",
-    "elysia": "^1.4.29"
+    "@clov-std/error": "^4.0.0",
+    "@clov-std/kv-store": "^1.1.2"
   },
   "devDependencies": {
-    "@types/bun": "catalog:base",
-    "oxfmt": "catalog:base",
-    "oxlint": "catalog:base",
-    "oxlint-tsgolint": "catalog:base",
-    "typescript": "catalog:base"
+    "@types/bun": "^1.3.14",
+    "oxfmt": "0.61.0",
+    "oxlint": "1.76.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "@clov-std/error": "workspace:^",
-    "@clov-std/kv-store": "workspace:^",
-    "elysia": "^1.4.29"
+    "@clov-std/error": "^4.0.0",
+    "@clov-std/kv-store": "^1.1.2",
+    "elysia": "^2.0.0-beta.1",
+    "typebox": "^1.3.10"
   }
 }

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

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