@clov-std/elysia-ratelimit 3.1.1 → 4.0.1

package/README.md

@@ -34,7 +34,7 @@ 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.
+- 🧯 **Complete RFC 9457 `429`** : Answers a real problem document on its own, `detail` included, with no exception class to import.
 
 ## 🔧 Installation
 
@@ -111,57 +111,24 @@ new Elysia()
 
 ## 🧯 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:
+When the allowance is exceeded, the plugin throws Elysia's `problem()`, so the `429` is a complete
+RFC 9457 document with no exception class and no error dependency involved:
 
 ```json
-{ "type": "elysia-ratelimit.exceeded", "title": "Too Many Requests" }
+{
+	"type": "rate-limit.quota.exceeded",
+	"title": "Too Many Requests",
+	"status": 429,
+	"detail": "Limit of 100 requests per 60s exceeded. Retry in 42s."
+}
 ```
 
-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' })
-)
-```
+`type` is always `RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED`. `title` is derived by Elysia from the
+status reason phrase. `detail` carries the live counter state, so it changes per occurrence.
+The content type is `application/problem+json`, and the `X-RateLimit-*` headers are set before
+the throw so they survive on the `429`.
 
-> **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.
+This is also the response the macro declares for OpenAPI, so a typed client sees it.
 
 ## 📚 API Reference
 

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,14 +1,13 @@
 // @bun
 // src/rate-limit.ts
-import { Exception } from "@clov-std/error";
 import { MemoryStore } from "@clov-std/kv-store";
-import { Elysia, t } from "elysia";
-var RATE_LIMIT_ERROR_KEYS = {
-  RATE_LIMIT_EXCEEDED: "elysia-ratelimit.exceeded"
+import { Elysia, problem, t } from "elysia";
+var RATE_LIMIT_ERROR_CODES = {
+  QUOTA_EXCEEDED: "rate-limit.quota.exceeded"
 };
 var rateLimitResponseSchema = t.Object({
   type: t.String({
-    description: `Error key. Defaults to \`${RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED}\`.`
+    description: `Error code. Always \`${RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED}\`.`
   }),
   title: t.String({
     description: "Short, human-readable summary of the error."
@@ -16,25 +15,10 @@ var rateLimitResponseSchema = t.Object({
   status: t.Literal(429, {
     description: "HTTP status code, repeated in the body per RFC 9457."
   }),
-  detail: t.Optional(t.String({
-    description: "Explanation specific to this occurrence."
-  }))
+  detail: t.String({
+    description: "Explanation specific to this occurrence, including when to retry."
+  })
 });
-
-class RateLimitException extends Exception {
-  status = 429;
-  response = {
-    type: RATE_LIMIT_ERROR_KEYS.RATE_LIMIT_EXCEEDED,
-    title: "Too Many Requests",
-    status: 429
-  };
-  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) {
@@ -44,7 +28,7 @@ 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().macro({
+var rateLimitPlugin = (store = new MemoryStore) => new Elysia({ name: "rateLimitPlugin" }).macro({
   rateLimit: ({
     limit,
     window,
@@ -64,16 +48,17 @@ var rateLimitPlugin = (store = new MemoryStore) => new Elysia().macro({
       set.headers["X-RateLimit-Limit"] = limit.toString();
       set.headers["X-RateLimit-Remaining"] = remaining.toString();
       set.headers["X-RateLimit-Reset"] = reset.toString();
-      if (count > limit) {
-        set.headers["content-type"] = "application/problem+json";
-        throw new RateLimitException({ limit, window, reset });
-      }
+      if (count > limit)
+        throw problem({
+          type: RATE_LIMIT_ERROR_CODES.QUOTA_EXCEEDED,
+          status: 429,
+          detail: `Limit of ${limit} requests per ${window}s exceeded. Retry in ${reset}s.`
+        });
     }
   })
 });
 export {
   rateLimitPlugin,
   extractClientIp,
-  RateLimitException,
-  RATE_LIMIT_ERROR_KEYS
+  RATE_LIMIT_ERROR_CODES
 };

package/dist/rate-limit.d.ts

@@ -1,50 +1,22 @@
-import { Exception } from '@clov-std/error';
 import { type KvStore } from '@clov-std/kv-store';
 import type { Server } from 'bun';
 import { Elysia, type HTTPHeaders } from 'elysia';
-import type { TLiteral, TObject, TOptional, TString } from 'typebox/type';
-export declare const RATE_LIMIT_ERROR_KEYS: {
-    readonly RATE_LIMIT_EXCEEDED: 'elysia-ratelimit.exceeded';
+import type { TLiteral, TObject, TString } from 'typebox/type';
+export declare const RATE_LIMIT_ERROR_CODES: {
+    readonly QUOTA_EXCEEDED: 'rate-limit.quota.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, following RFC 9457.
+ * Shape of the `429` body, an RFC 9457 problem document.
+ *
+ * `title` is filled by Elysia from the status reason phrase, so the plugin only supplies
+ * `type`, `status`, and `detail`.
  */
 declare const rateLimitResponseSchema: TObject<{
     type: TString;
     title: TString;
     status: TLiteral<429>;
-    detail: TOptional<TString>;
+    detail: TString;
 }>;
-/**
- * Thrown when a caller exceeds its allowance.
- *
- * @see {@link rateLimitResponseSchema}
- */
-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;
-        readonly status: 429;
-    };
-    /**
-     * 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;
@@ -69,7 +41,7 @@ type RateLimitMacro = (options: RateLimitMacroOptions) => {
     transform: (context: RateLimitTransformContext) => Promise<void>;
 };
 export declare const extractClientIp: (request: Request, server: Server<unknown> | null) => string;
-export declare const rateLimitPlugin: (store?: KvStore) => Elysia<'', 'local', {
+export declare const rateLimitPlugin: (store?: KvStore) => Elysia<'rateLimitPlugin', 'local', {
     decorator: {};
     derive: {};
     store: {};

package/package.json

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