@xyph3r/rate-limiter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xyph3r
+
+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,310 @@
+# `@xyph3r/rate-limiter`
+
+Framework-agnostic rate limiting for Node.js and fetch-based runtimes with two clear goals:
+
+- keep the core API small enough to use without ceremony
+- keep the internals structured enough to stay maintainable when requirements change
+
+The package is organized around a few deliberate design choices:
+
+- `Strategy`: sliding window and token bucket are swappable algorithms
+- `Builder`: fluent construction for readable setup
+- `Decorator`: optional Express and Fastify adapters wrap the core
+- `Decorator`: fetch/Hono/Next/Nest integrations stay outside the core
+- `Proxy`: short-lived decision caching for hot paths
+
+## Install
+
+```bash
+npm install @xyph3r/rate-limiter
+```
+
+## Quick start
+
+```ts
+import { createExpressRateLimit, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+
+const limiter = new RateLimiterBuilder()
+  .forSlidingWindow({ limit: 100, windowMs: 60_000 })
+  .withMemoryStore()
+  .withKeyPrefix("api")
+  .build();
+
+app.use(createExpressRateLimit(limiter));
+```
+
+## Bun
+
+For Bun's native `fetch` handler, use the shared fetch adapter:
+
+```ts
+import { createFetchRateLimit, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+
+const limiter = new RateLimiterBuilder()
+  .forSlidingWindow({ limit: 100, windowMs: 60_000 })
+  .withMemoryStore()
+  .build();
+
+const withRateLimit = createFetchRateLimit(limiter);
+
+Bun.serve({
+  fetch: withRateLimit(async () => {
+    return Response.json({ ok: true });
+  }),
+});
+```
+
+## Core usage
+
+### Sliding window
+
+```ts
+import { MemoryStore, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+
+const limiter = new RateLimiterBuilder()
+  .useStore(new MemoryStore())
+  .forSlidingWindow({
+    limit: 10,
+    windowMs: 1_000,
+  })
+  .build();
+
+const decision = await limiter.check("user:42");
+
+if (!decision.allowed) {
+  console.log(`Retry in ${decision.retryAfterMs}ms`);
+}
+```
+
+### Token bucket
+
+```ts
+import { createRateLimiter } from "@xyph3r/rate-limiter";
+
+const limiter = createRateLimiter({
+  algorithm: "token-bucket",
+  capacity: 20,
+  refillRate: 5,
+  refillIntervalMs: 1_000,
+  keyPrefix: "jobs",
+});
+```
+
+## Redis-backed usage
+
+The package does not force a Redis client. Instead, it ships lightweight executors for the two common interfaces.
+
+### `node-redis`
+
+```ts
+import { createClient } from "redis";
+import {
+  createNodeRedisExecutor,
+  RedisStore,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const client = createClient();
+await client.connect();
+
+const store = new RedisStore(createNodeRedisExecutor(client));
+
+const limiter = new RateLimiterBuilder()
+  .useStore(store)
+  .forSlidingWindow({ limit: 200, windowMs: 60_000 })
+  .build();
+```
+
+### `ioredis`
+
+```ts
+import Redis from "ioredis";
+import {
+  createIORedisExecutor,
+  RedisStore,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const client = new Redis(process.env.REDIS_URL!);
+const store = new RedisStore(createIORedisExecutor(client));
+```
+
+## Simple factory
+
+If you prefer a plain config object over the builder:
+
+```ts
+import { createRateLimiter } from "@xyph3r/rate-limiter";
+
+const limiter = createRateLimiter({
+  algorithm: "sliding-window",
+  limit: 50,
+  windowMs: 10_000,
+  keyPrefix: "public-api",
+  cacheMs: 25,
+});
+```
+
+## Express adapter
+
+```ts
+import express from "express";
+import {
+  createExpressRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const app = express();
+
+const limiter = new RateLimiterBuilder()
+  .forTokenBucket({
+    capacity: 30,
+    refillRate: 10,
+    refillIntervalMs: 1_000,
+  })
+  .withMemoryStore()
+  .build();
+
+app.use(
+  createExpressRateLimit(limiter, {
+    key: (req) => req.headers["x-api-key"] as string,
+  }),
+);
+```
+
+## Hono adapter
+
+```ts
+import { Hono } from "hono";
+import {
+  createHonoRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const app = new Hono();
+
+const limiter = new RateLimiterBuilder()
+  .forSlidingWindow({ limit: 20, windowMs: 1_000 })
+  .withMemoryStore()
+  .build();
+
+app.use("*", createHonoRateLimit(limiter));
+```
+
+## Fastify adapter
+
+```ts
+import fastify from "fastify";
+import {
+  createFastifyRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const app = fastify();
+
+const limiter = new RateLimiterBuilder()
+  .forSlidingWindow({ limit: 5, windowMs: 1_000 })
+  .withMemoryStore()
+  .build();
+
+app.addHook("preHandler", createFastifyRateLimit(limiter));
+```
+
+## Next.js route handlers
+
+For App Router route handlers, wrap the exported handler:
+
+```ts
+import { createNextRateLimit, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+
+const limiter = new RateLimiterBuilder()
+  .forSlidingWindow({ limit: 30, windowMs: 60_000 })
+  .withMemoryStore()
+  .build();
+
+const withRateLimit = createNextRateLimit(limiter);
+
+export const GET = withRateLimit(async () => {
+  return Response.json({ ok: true });
+});
+```
+
+You can also use `key(request, context)` to derive limits from route params, session data, or tenant IDs.
+
+## NestJS guard
+
+Nest is exposed as a guard-shaped decorator. Pass your own exception from `@nestjs/common` so the framework returns a proper `429`.
+
+```ts
+import { TooManyRequestsException } from "@nestjs/common";
+import {
+  createNestRateLimitGuard,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const limiter = new RateLimiterBuilder()
+  .forSlidingWindow({ limit: 10, windowMs: 1_000 })
+  .withMemoryStore()
+  .build();
+
+export const RateLimitGuard = createNestRateLimitGuard(limiter, {
+  errorFactory: (decision) =>
+    new TooManyRequestsException({
+      error: "Too many requests",
+      retryAfterMs: decision.retryAfterMs,
+    }),
+});
+```
+
+## Public API
+
+### `RateLimiterBuilder`
+
+- `.forSlidingWindow({ limit, windowMs })`
+- `.forTokenBucket({ capacity, refillRate, refillIntervalMs })`
+- `.useStore(store)` / `.withMemoryStore()`
+- `.withKeyPrefix(prefix)`
+- `.withCache(ttlMs)`
+- `.build()`
+
+### `RateLimiterLike`
+
+- `check(key, { cost? })`
+- `reset(key)`
+
+### Adapters
+
+- `createFetchRateLimit()` for Bun or any fetch-native runtime
+- `createHonoRateLimit()` for Hono middleware
+- `createNextRateLimit()` for Next.js App Router handlers
+- `createNestRateLimitGuard()` for NestJS HTTP guards
+- `createExpressRateLimit()` and `createFastifyRateLimit()`
+
+### Decision fields
+
+- `allowed`
+- `limit`
+- `used`
+- `remaining`
+- `retryAfterMs`
+- `resetAt`
+- `policy`
+
+## Notes
+
+- The memory store is process-local. Use Redis for multi-instance deployments.
+- Redis execution is atomic because each strategy ships its own Lua program.
+- The sliding window implementation uses a weighted previous-window approximation rather than a timestamp log. That keeps storage compact and predictable.
+- Bun, Hono, and Next.js all use the fetch-compatible adapter surface under the hood.
+
+## Publishing
+
+The package is set up so `npm publish` builds `dist/` during `prepack` and runs the test suite during `prepublishOnly`.
+
+Release flow:
+
+1. Install dev dependencies with `npm install`.
+2. Verify the package locally with `npm test`.
+3. Inspect the publish tarball with `npm pack --dry-run`.
+4. Log in with `npm login` if needed, then confirm the target account with `npm whoami`.
+5. Publish the public scoped package with `npm publish --access public --provenance`.

package/dist/adapters/express.d.ts

@@ -0,0 +1,26 @@
+import { type HeaderCarrier } from "../utils/http.js";
+import type { RateLimitDecision, RateLimiterLike } from "../types.js";
+export interface ExpressLikeRequest extends HeaderCarrier {
+}
+export interface ExpressLikeResponse {
+    end(body?: string): unknown;
+    json?(body: unknown): unknown;
+    setHeader(name: string, value: string): void;
+    status(code: number): this;
+}
+export type ExpressLikeNext = (error?: unknown) => void;
+export interface ExpressRateLimitOptions<TRequest extends ExpressLikeRequest = ExpressLikeRequest, TResponse extends ExpressLikeResponse = ExpressLikeResponse> {
+    cost?: (request: TRequest) => number | Promise<number>;
+    key?: (request: TRequest) => string | Promise<string>;
+    onRejected?: (request: TRequest, response: TResponse, decision: RateLimitDecision) => void | Promise<void>;
+    setHeaders?: boolean;
+    skip?: (request: TRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Pattern: Decorator
+ * Problem: HTTP concerns should not leak into the core limiter.
+ * Solution: The adapter decorates the core limiter with request parsing and response shaping.
+ * Trade-off: One wrapper per framework; justified because the core stays framework-agnostic.
+ */
+export declare function createExpressRateLimit<TRequest extends ExpressLikeRequest = ExpressLikeRequest, TResponse extends ExpressLikeResponse = ExpressLikeResponse>(limiter: RateLimiterLike, options?: ExpressRateLimitOptions<TRequest, TResponse>): (request: TRequest, response: TResponse, next: ExpressLikeNext) => Promise<void>;
+//# sourceMappingURL=express.d.ts.map

package/dist/adapters/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":"AACA,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,WAAW,kBAAmB,SAAQ,aAAa;CAAG;AAE5D,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC9B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,uBAAuB,CACtC,QAAQ,SAAS,kBAAkB,GAAG,kBAAkB,EACxD,SAAS,SAAS,mBAAmB,GAAG,mBAAmB;IAE3D,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,SAAS,EACnB,QAAQ,EAAE,iBAAiB,KACxB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,SAAS,kBAAkB,GAAG,kBAAkB,EACxD,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,EAE3D,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAM,GACzD,CACD,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,SAAS,EACnB,IAAI,EAAE,eAAe,KAClB,OAAO,CAAC,IAAI,CAAC,CAuCjB"}

package/dist/adapters/express.js

@@ -0,0 +1,51 @@
+import { applyHeaders } from "../utils/headers.js";
+import { getDefaultKeyFromRequest } from "../utils/http.js";
+/**
+ * Pattern: Decorator
+ * Problem: HTTP concerns should not leak into the core limiter.
+ * Solution: The adapter decorates the core limiter with request parsing and response shaping.
+ * Trade-off: One wrapper per framework; justified because the core stays framework-agnostic.
+ */
+export function createExpressRateLimit(limiter, options = {}) {
+    return async (request, response, next) => {
+        try {
+            if ((await options.skip?.(request)) === true) {
+                next();
+                return;
+            }
+            const key = (await options.key?.(request)) ?? getDefaultKeyFromRequest(request);
+            const cost = (await options.cost?.(request)) ?? 1;
+            const decision = await limiter.check(key, { cost });
+            if (options.setHeaders !== false) {
+                applyHeaders((name, value) => response.setHeader(name, value), decision);
+            }
+            if (decision.allowed) {
+                next();
+                return;
+            }
+            if (options.onRejected) {
+                await options.onRejected(request, response, decision);
+                return;
+            }
+            response.status(429);
+            response.setHeader("content-type", "application/json; charset=utf-8");
+            if (typeof response.json === "function") {
+                response.json(defaultRateLimitBody(decision));
+                return;
+            }
+            response.end(JSON.stringify(defaultRateLimitBody(decision)));
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+function defaultRateLimitBody(decision) {
+    return {
+        error: "Too many requests",
+        limit: decision.limit,
+        remaining: decision.remaining,
+        retryAfterMs: decision.retryAfterMs,
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAsB,MAAM,kBAAkB,CAAC;AA6BhF;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAIpC,OAAwB,EACxB,UAAwD,EAAE;IAM1D,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;QACvC,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC7C,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YAED,MAAM,GAAG,GACP,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;YACtE,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAEpD,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;gBACjC,YAAY,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC3E,CAAC;YAED,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACrB,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACvB,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBACtD,OAAO;YACT,CAAC;YAED,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACrB,QAAQ,CAAC,SAAS,CAAC,cAAc,EAAE,iCAAiC,CAAC,CAAC;YACtE,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACxC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAC9C,OAAO;YACT,CAAC;YAED,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,QAA2B;IACvD,OAAO;QACL,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,YAAY,EAAE,QAAQ,CAAC,YAAY;KACpC,CAAC;AACJ,CAAC"}

package/dist/adapters/fastify.d.ts

@@ -0,0 +1,24 @@
+import { type HeaderCarrier } from "../utils/http.js";
+import type { RateLimitDecision, RateLimiterLike } from "../types.js";
+export interface FastifyLikeRequest extends HeaderCarrier {
+}
+export interface FastifyLikeReply {
+    code(statusCode: number): this;
+    header(name: string, value: string): this;
+    send(payload: unknown): unknown;
+}
+export interface FastifyRateLimitOptions<TRequest extends FastifyLikeRequest = FastifyLikeRequest, TReply extends FastifyLikeReply = FastifyLikeReply> {
+    cost?: (request: TRequest) => number | Promise<number>;
+    key?: (request: TRequest) => string | Promise<string>;
+    onRejected?: (request: TRequest, reply: TReply, decision: RateLimitDecision) => void | Promise<void>;
+    setHeaders?: boolean;
+    skip?: (request: TRequest) => boolean | Promise<boolean>;
+}
+/**
+ * Pattern: Decorator
+ * Problem: Fastify request handling is framework-specific, but rate-limit decisions are not.
+ * Solution: The adapter layers Fastify semantics over the shared limiter contract.
+ * Trade-off: Separate adapter module; justified because it keeps the core reusable elsewhere.
+ */
+export declare function createFastifyRateLimit<TRequest extends FastifyLikeRequest = FastifyLikeRequest, TReply extends FastifyLikeReply = FastifyLikeReply>(limiter: RateLimiterLike, options?: FastifyRateLimitOptions<TRequest, TReply>): (request: TRequest, reply: TReply) => Promise<void>;
+//# sourceMappingURL=fastify.d.ts.map

package/dist/adapters/fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../../src/adapters/fastify.ts"],"names":[],"mappings":"AACA,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,WAAW,kBAAmB,SAAQ,aAAa;CAAG;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB,CACtC,QAAQ,SAAS,kBAAkB,GAAG,kBAAkB,EACxD,MAAM,SAAS,gBAAgB,GAAG,gBAAgB;IAElD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,iBAAiB,KACxB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,SAAS,kBAAkB,GAAG,kBAAkB,EACxD,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAElD,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,uBAAuB,CAAC,QAAQ,EAAE,MAAM,CAAM,GACtD,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CA2BrD"}

package/dist/adapters/fastify.js

@@ -0,0 +1,40 @@
+import { applyHeaders } from "../utils/headers.js";
+import { getDefaultKeyFromRequest } from "../utils/http.js";
+/**
+ * Pattern: Decorator
+ * Problem: Fastify request handling is framework-specific, but rate-limit decisions are not.
+ * Solution: The adapter layers Fastify semantics over the shared limiter contract.
+ * Trade-off: Separate adapter module; justified because it keeps the core reusable elsewhere.
+ */
+export function createFastifyRateLimit(limiter, options = {}) {
+    return async (request, reply) => {
+        if ((await options.skip?.(request)) === true) {
+            return;
+        }
+        const key = (await options.key?.(request)) ?? getDefaultKeyFromRequest(request);
+        const cost = (await options.cost?.(request)) ?? 1;
+        const decision = await limiter.check(key, { cost });
+        if (options.setHeaders !== false) {
+            applyHeaders((name, value) => {
+                reply.header(name, value);
+            }, decision);
+        }
+        if (decision.allowed) {
+            return;
+        }
+        if (options.onRejected) {
+            await options.onRejected(request, reply, decision);
+            return;
+        }
+        reply.code(429).send(defaultRateLimitBody(decision));
+    };
+}
+function defaultRateLimitBody(decision) {
+    return {
+        error: "Too many requests",
+        limit: decision.limit,
+        remaining: decision.remaining,
+        retryAfterMs: decision.retryAfterMs,
+    };
+}
+//# sourceMappingURL=fastify.js.map

package/dist/adapters/fastify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../../src/adapters/fastify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAsB,MAAM,kBAAkB,CAAC;AA0BhF;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAIpC,OAAwB,EACxB,UAAqD,EAAE;IAEvD,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;QAC9B,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7C,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAChF,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAEpD,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;YACjC,YAAY,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAC3B,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC5B,CAAC,EAAE,QAAQ,CAAC,CAAC;QACf,CAAC;QAED,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,QAA2B;IACvD,OAAO;QACL,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,YAAY,EAAE,QAAQ,CAAC,YAAY;KACpC,CAAC;AACJ,CAAC"}

package/dist/adapters/fetch.d.ts

@@ -0,0 +1,17 @@
+import type { RateLimitDecision, RateLimiterLike } from "../types.js";
+export type FetchLikeHandler<TContext = unknown> = (request: Request, context: TContext) => Response | Promise<Response>;
+export interface FetchRateLimitOptions<TContext = unknown> {
+    cost?: (request: Request, context: TContext) => number | Promise<number>;
+    key?: (request: Request, context: TContext) => string | Promise<string>;
+    onRejected?: (request: Request, context: TContext, decision: RateLimitDecision) => Response | Promise<Response>;
+    setHeaders?: boolean;
+    skip?: (request: Request, context: TContext) => boolean | Promise<boolean>;
+}
+/**
+ * Pattern: Decorator
+ * Problem: Fetch-style runtimes need rate limiting without coupling the core to Bun or Next.js.
+ * Solution: The adapter decorates standard Request/Response handlers behind a shared contract.
+ * Trade-off: One more wrapper around the handler; justified because Bun and Next.js both speak fetch natively.
+ */
+export declare function createFetchRateLimit<TContext = unknown>(limiter: RateLimiterLike, options?: FetchRateLimitOptions<TContext>): (handler: FetchLikeHandler<TContext>) => FetchLikeHandler<TContext>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/adapters/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/adapters/fetch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,MAAM,gBAAgB,CAAC,QAAQ,GAAG,OAAO,IAAI,CACjD,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,QAAQ,KACd,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,MAAM,WAAW,qBAAqB,CAAC,QAAQ,GAAG,OAAO;IACvD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxE,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,iBAAiB,KACxB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAG,OAAO,EACrD,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,qBAAqB,CAAC,QAAQ,CAAM,GAC5C,CAAC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,gBAAgB,CAAC,QAAQ,CAAC,CA8BrE"}

package/dist/adapters/fetch.js

@@ -0,0 +1,53 @@
+import { applyHeaders } from "../utils/headers.js";
+import { getDefaultKeyFromFetchRequest } from "../utils/http.js";
+/**
+ * Pattern: Decorator
+ * Problem: Fetch-style runtimes need rate limiting without coupling the core to Bun or Next.js.
+ * Solution: The adapter decorates standard Request/Response handlers behind a shared contract.
+ * Trade-off: One more wrapper around the handler; justified because Bun and Next.js both speak fetch natively.
+ */
+export function createFetchRateLimit(limiter, options = {}) {
+    return (handler) => {
+        return async (request, context) => {
+            if ((await options.skip?.(request, context)) === true) {
+                return handler(request, context);
+            }
+            const key = (await options.key?.(request, context)) ??
+                getDefaultKeyFromFetchRequest(request);
+            const cost = (await options.cost?.(request, context)) ?? 1;
+            const decision = await limiter.check(key, { cost });
+            if (!decision.allowed) {
+                const rejected = (await options.onRejected?.(request, context, decision)) ??
+                    defaultRateLimitResponse(decision);
+                return options.setHeaders === false
+                    ? rejected
+                    : withRateLimitHeaders(rejected, decision);
+            }
+            const response = await handler(request, context);
+            if (options.setHeaders === false) {
+                return response;
+            }
+            return withRateLimitHeaders(response, decision);
+        };
+    };
+}
+function defaultRateLimitResponse(decision) {
+    return Response.json({
+        error: "Too many requests",
+        limit: decision.limit,
+        remaining: decision.remaining,
+        retryAfterMs: decision.retryAfterMs,
+    }, { status: 429 });
+}
+function withRateLimitHeaders(response, decision) {
+    const headers = new Headers(response.headers);
+    applyHeaders((name, value) => {
+        headers.set(name, value);
+    }, decision);
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+//# sourceMappingURL=fetch.js.map

package/dist/adapters/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/adapters/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAoBjE;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAwB,EACxB,UAA2C,EAAE;IAE7C,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;YAChC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;gBACtD,OAAO,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACnC,CAAC;YAED,MAAM,GAAG,GACP,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACvC,6BAA6B,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;YAC3D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAEpD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACtB,MAAM,QAAQ,GACZ,CAAC,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;oBACxD,wBAAwB,CAAC,QAAQ,CAAC,CAAC;gBACrC,OAAO,OAAO,CAAC,UAAU,KAAK,KAAK;oBACjC,CAAC,CAAC,QAAQ;oBACV,CAAC,CAAC,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACjD,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;gBACjC,OAAO,QAAQ,CAAC;YAClB,CAAC;YAED,OAAO,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAClD,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,wBAAwB,CAAC,QAA2B;IAC3D,OAAO,QAAQ,CAAC,IAAI,CAClB;QACE,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,YAAY,EAAE,QAAQ,CAAC,YAAY;KACpC,EACD,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,QAAkB,EAClB,QAA2B;IAE3B,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9C,YAAY,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC3B,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC,EAAE,QAAQ,CAAC,CAAC;IAEb,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,OAAO;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/adapters/hono.d.ts

@@ -0,0 +1,25 @@
+import type { RateLimitDecision, RateLimiterLike } from "../types.js";
+export interface HonoLikeRequest {
+    raw: Request;
+    header(name: string): string | undefined;
+}
+export interface HonoLikeContext {
+    header(name: string, value: string): void;
+    json(body: unknown, status?: number): Response;
+    req: HonoLikeRequest;
+}
+export interface HonoRateLimitOptions<TContext extends HonoLikeContext = HonoLikeContext> {
+    cost?: (context: TContext) => number | Promise<number>;
+    key?: (context: TContext) => string | Promise<string>;
+    onRejected?: (context: TContext, decision: RateLimitDecision) => Response | Promise<Response>;
+    setHeaders?: boolean;
+    skip?: (context: TContext) => boolean | Promise<boolean>;
+}
+/**
+ * Pattern: Decorator
+ * Problem: Hono middleware needs framework-specific request and response hooks while the limiter stays framework-agnostic.
+ * Solution: The adapter decorates the core limiter with Hono's context API.
+ * Trade-off: Separate Hono wrapper; justified because Bun/Hono is a first-class target for this package.
+ */
+export declare function createHonoRateLimit<TContext extends HonoLikeContext = HonoLikeContext>(limiter: RateLimiterLike, options?: HonoRateLimitOptions<TContext>): (context: TContext, next: () => Promise<void>) => Promise<void | Response>;
+//# sourceMappingURL=hono.d.ts.map

package/dist/adapters/hono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/adapters/hono.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/C,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe;IACtF,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,iBAAiB,KACxB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe,EACpF,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,oBAAoB,CAAC,QAAQ,CAAM,GAC3C,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CA4B5E"}

package/dist/adapters/hono.js

@@ -0,0 +1,40 @@
+import { applyHeaders } from "../utils/headers.js";
+import { getDefaultKeyFromFetchRequest } from "../utils/http.js";
+/**
+ * Pattern: Decorator
+ * Problem: Hono middleware needs framework-specific request and response hooks while the limiter stays framework-agnostic.
+ * Solution: The adapter decorates the core limiter with Hono's context API.
+ * Trade-off: Separate Hono wrapper; justified because Bun/Hono is a first-class target for this package.
+ */
+export function createHonoRateLimit(limiter, options = {}) {
+    return async (context, next) => {
+        if ((await options.skip?.(context)) === true) {
+            await next();
+            return;
+        }
+        const key = (await options.key?.(context)) ??
+            getDefaultKeyFromFetchRequest(context.req.raw);
+        const cost = (await options.cost?.(context)) ?? 1;
+        const decision = await limiter.check(key, { cost });
+        if (options.setHeaders !== false) {
+            applyHeaders((name, value) => context.header(name, value), decision);
+        }
+        if (decision.allowed) {
+            await next();
+            return;
+        }
+        if (options.onRejected) {
+            return options.onRejected(context, decision);
+        }
+        return context.json(defaultRateLimitBody(decision), 429);
+    };
+}
+function defaultRateLimitBody(decision) {
+    return {
+        error: "Too many requests",
+        limit: decision.limit,
+        remaining: decision.remaining,
+        retryAfterMs: decision.retryAfterMs,
+    };
+}
+//# sourceMappingURL=hono.js.map

package/dist/adapters/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","sourceRoot":"","sources":["../../src/adapters/hono.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAyBjE;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAwB,EACxB,UAA0C,EAAE;IAE5C,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7C,MAAM,IAAI,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GACP,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;YAC9B,6BAA6B,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAEpD,IAAI,OAAO,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;YACjC,YAAY,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;QACvE,CAAC;QAED,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QAED,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,QAA2B;IACvD,OAAO;QACL,KAAK,EAAE,mBAAmB;QAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,YAAY,EAAE,QAAQ,CAAC,YAAY;KACpC,CAAC;AACJ,CAAC"}