@xyph3r/rate-limiter 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,21 @@
 # `@xyph3r/rate-limiter`
 
-Framework-agnostic rate limiting for Node.js and fetch-based runtimes with two clear goals:
+Framework-agnostic rate limiting for Node.js and fetch-based runtimes.
 
-- keep the core API small enough to use without ceremony
-- keep the internals structured enough to stay maintainable when requirements change
+This package is for the common cases people actually need:
 
-The package is organized around a few deliberate design choices:
+- protect a public API by IP or API key
+- slow down abusive login attempts
+- apply per-tenant or per-user quotas
+- add rate-limit headers to HTTP responses
+- use Redis when you run more than one app instance
+
+The package is intentionally small:
 
 - `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
+- `Builder`: setup stays readable as configuration grows
+- `Decorator`: framework adapters wrap the core without coupling it to Express, Fastify, Hono, or Next
+- `Proxy`: optional short-lived caching reduces repeated checks on hot paths
 
 ## Install
 
@@ -19,50 +23,69 @@ The package is organized around a few deliberate design choices:
 npm install @xyph3r/rate-limiter
 ```
 
-## Quick start
+or
 
-```ts
-import { createExpressRateLimit, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+```bash
+bun add @xyph3r/rate-limiter
+```
 
-const limiter = new RateLimiterBuilder()
-  .forSlidingWindow({ limit: 100, windowMs: 60_000 })
-  .withMemoryStore()
-  .withKeyPrefix("api")
-  .build();
+## When to use which algorithm
 
-app.use(createExpressRateLimit(limiter));
-```
+### Sliding window
+
+Use sliding window when you want a straightforward limit like:
 
-## Bun
+- `100 requests per minute`
+- `5 login attempts per 10 minutes`
+- `30 requests per second`
+
+This is usually the default choice for HTTP APIs.
+
+### Token bucket
 
-For Bun's native `fetch` handler, use the shared fetch adapter:
+Use token bucket when you want bursts to be allowed but still controlled over time.
+
+Examples:
+
+- allow a short burst of `20` requests, then refill at `5/second`
+- smooth traffic for jobs or background workers
+- tolerate small spikes without rejecting immediately
+
+## Production advice
+
+- `MemoryStore` is process-local. Use it for local dev, tests, or single-instance apps.
+- `RedisStore` is the right choice for multi-instance deployments.
+- Rate limiting only works as well as your key choice. Pick a stable identity: IP, API key, tenant ID, or user ID.
+
+## Quick start
 
 ```ts
-import { createFetchRateLimit, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+import express from "express";
+import {
+  createExpressRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
+
+const app = express();
 
 const limiter = new RateLimiterBuilder()
   .forSlidingWindow({ limit: 100, windowMs: 60_000 })
   .withMemoryStore()
+  .withKeyPrefix("api")
   .build();
 
-const withRateLimit = createFetchRateLimit(limiter);
-
-Bun.serve({
-  fetch: withRateLimit(async () => {
-    return Response.json({ ok: true });
-  }),
-});
+app.use(createExpressRateLimit(limiter));
 ```
 
 ## Core usage
 
-### Sliding window
+Use the core API when you want rate-limit decisions outside HTTP middleware.
 
 ```ts
-import { MemoryStore, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+import { RateLimiterBuilder } from "@xyph3r/rate-limiter";
 
 const limiter = new RateLimiterBuilder()
-  .useStore(new MemoryStore())
+  .withMemoryStore()
   .forSlidingWindow({
     limit: 10,
     windowMs: 1_000,
@@ -76,7 +99,7 @@ if (!decision.allowed) {
 }
 ```
 
-### Token bucket
+### Token bucket example
 
 ```ts
 import { createRateLimiter } from "@xyph3r/rate-limiter";
@@ -92,7 +115,7 @@ const limiter = createRateLimiter({
 
 ## Redis-backed usage
 
-The package does not force a Redis client. Instead, it ships lightweight executors for the two common interfaces.
+The package does not force a Redis client. It ships small executors for the common client shapes.
 
 ### `node-redis`
 
@@ -104,13 +127,11 @@ import {
   RateLimiterBuilder,
 } from "@xyph3r/rate-limiter";
 
-const client = createClient();
+const client = createClient({ url: process.env.REDIS_URL });
 await client.connect();
 
-const store = new RedisStore(createNodeRedisExecutor(client));
-
 const limiter = new RateLimiterBuilder()
-  .useStore(store)
+  .useStore(new RedisStore(createNodeRedisExecutor(client)))
   .forSlidingWindow({ limit: 200, windowMs: 60_000 })
   .build();
 ```
@@ -126,114 +147,186 @@ import {
 } from "@xyph3r/rate-limiter";
 
 const client = new Redis(process.env.REDIS_URL!);
-const store = new RedisStore(createIORedisExecutor(client));
+
+const limiter = new RateLimiterBuilder()
+  .useStore(new RedisStore(createIORedisExecutor(client)))
+  .forSlidingWindow({ limit: 200, windowMs: 60_000 })
+  .build();
 ```
 
-## Simple factory
+## Framework usage
+
+### Express
 
-If you prefer a plain config object over the builder:
+Use `createExpressRateLimit()` as middleware.
 
 ```ts
-import { createRateLimiter } from "@xyph3r/rate-limiter";
+import express from "express";
+import {
+  createExpressRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
 
-const limiter = createRateLimiter({
-  algorithm: "sliding-window",
-  limit: 50,
-  windowMs: 10_000,
-  keyPrefix: "public-api",
-  cacheMs: 25,
-});
+const app = express();
+
+const limiter = new RateLimiterBuilder()
+  .withMemoryStore()
+  .forSlidingWindow({ limit: 50, windowMs: 60_000 })
+  .build();
+
+app.use(
+  createExpressRateLimit(limiter, {
+    key: (request) =>
+      request.headers["x-api-key"] as string || request.ip || "anonymous",
+    skip: (request) => request.headers["x-internal-call"] === "1",
+  }),
+);
 ```
 
-## Express adapter
+Use this for:
+
+- public REST APIs
+- login and auth routes
+- per-customer API key limits
+
+### Fastify
+
+Use `createFastifyRateLimit()` in `preHandler`.
 
 ```ts
-import express from "express";
+import Fastify from "fastify";
 import {
-  createExpressRateLimit,
+  createFastifyRateLimit,
   RateLimiterBuilder,
 } from "@xyph3r/rate-limiter";
 
-const app = express();
+const app = Fastify();
 
 const limiter = new RateLimiterBuilder()
+  .withMemoryStore()
   .forTokenBucket({
     capacity: 30,
     refillRate: 10,
     refillIntervalMs: 1_000,
   })
-  .withMemoryStore()
   .build();
 
-app.use(
-  createExpressRateLimit(limiter, {
-    key: (req) => req.headers["x-api-key"] as string,
+app.addHook(
+  "preHandler",
+  createFastifyRateLimit(limiter, {
+    key: (request) =>
+      request.headers["x-api-key"] as string || request.ip || "anonymous",
   }),
 );
 ```
 
-## Hono adapter
+### Fetch / Bun / standard `Request` handlers
+
+Use `createFetchRateLimit()` when your runtime already uses the standard `Request -> Response` shape.
 
 ```ts
-import { Hono } from "hono";
 import {
-  createHonoRateLimit,
+  createFetchRateLimit,
   RateLimiterBuilder,
 } from "@xyph3r/rate-limiter";
 
-const app = new Hono();
+const limiter = new RateLimiterBuilder()
+  .withMemoryStore()
+  .forSlidingWindow({ limit: 100, windowMs: 60_000 })
+  .build();
+
+const withRateLimit = createFetchRateLimit(limiter, {
+  key: (request) => request.headers.get("x-api-key") ?? "anonymous",
+});
+
+const handler = withRateLimit(async () => {
+  return Response.json({ ok: true });
+});
+```
+
+#### Bun example
+
+```ts
+import {
+  createFetchRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
 
 const limiter = new RateLimiterBuilder()
-  .forSlidingWindow({ limit: 20, windowMs: 1_000 })
   .withMemoryStore()
+  .forSlidingWindow({ limit: 100, windowMs: 60_000 })
   .build();
 
-app.use("*", createHonoRateLimit(limiter));
+const withRateLimit = createFetchRateLimit(limiter, {
+  key: (request) => request.headers.get("x-forwarded-for") ?? "anonymous",
+});
+
+Bun.serve({
+  fetch: withRateLimit(async () => Response.json({ ok: true })),
+});
 ```
 
-## Fastify adapter
+### Hono
+
+Use `createHonoRateLimit()` as Hono middleware.
 
 ```ts
-import fastify from "fastify";
+import { Hono } from "hono";
 import {
-  createFastifyRateLimit,
+  createHonoRateLimit,
   RateLimiterBuilder,
 } from "@xyph3r/rate-limiter";
 
-const app = fastify();
+const app = new Hono();
 
 const limiter = new RateLimiterBuilder()
-  .forSlidingWindow({ limit: 5, windowMs: 1_000 })
   .withMemoryStore()
+  .forSlidingWindow({ limit: 20, windowMs: 1_000 })
   .build();
 
-app.addHook("preHandler", createFastifyRateLimit(limiter));
+app.use(
+  "*",
+  createHonoRateLimit(limiter, {
+    key: (c) => c.req.header("x-api-key") ?? "anonymous",
+  }),
+);
 ```
 
-## Next.js route handlers
+### Next.js App Router
 
-For App Router route handlers, wrap the exported handler:
+Use `createNextRateLimit()` to wrap the exported route handler.
 
 ```ts
-import { createNextRateLimit, RateLimiterBuilder } from "@xyph3r/rate-limiter";
+import {
+  createNextRateLimit,
+  RateLimiterBuilder,
+} from "@xyph3r/rate-limiter";
 
 const limiter = new RateLimiterBuilder()
-  .forSlidingWindow({ limit: 30, windowMs: 60_000 })
   .withMemoryStore()
+  .forSlidingWindow({ limit: 30, windowMs: 60_000 })
   .build();
 
-const withRateLimit = createNextRateLimit(limiter);
+const withRateLimit = createNextRateLimit(limiter, {
+  key: (request) => request.headers.get("x-api-key") ?? "anonymous",
+});
 
 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.
+You can also derive the key from route params or tenant context:
+
+```ts
+const withRateLimit = createNextRateLimit(limiter, {
+  key: (_request, context: { params: { tenantId: string } }) => context.params.tenantId,
+});
+```
 
-## NestJS guard
+### NestJS
 
-Nest is exposed as a guard-shaped decorator. Pass your own exception from `@nestjs/common` so the framework returns a proper `429`.
+Use `createNestRateLimitGuard()` where a Nest guard fits better than middleware.
 
 ```ts
 import { TooManyRequestsException } from "@nestjs/common";
@@ -243,11 +336,12 @@ import {
 } from "@xyph3r/rate-limiter";
 
 const limiter = new RateLimiterBuilder()
-  .forSlidingWindow({ limit: 10, windowMs: 1_000 })
   .withMemoryStore()
+  .forSlidingWindow({ limit: 10, windowMs: 1_000 })
   .build();
 
 export const RateLimitGuard = createNestRateLimitGuard(limiter, {
+  key: (request) => request.headers?.["x-api-key"] as string || request.ip || "anonymous",
   errorFactory: (decision) =>
     new TooManyRequestsException({
       error: "Too many requests",
@@ -256,6 +350,84 @@ export const RateLimitGuard = createNestRateLimitGuard(limiter, {
 });
 ```
 
+## Choosing the key
+
+A good rate-limit key represents the caller you want to control.
+
+Good keys:
+
+- client IP for anonymous traffic
+- API key
+- authenticated user ID
+- tenant ID
+- machine or worker ID for background endpoints
+
+Bad keys:
+
+- a random UUID per request
+- request timestamp
+- request path alone, if many callers share it
+
+## Cost-based limiting
+
+Every adapter and the core API support `cost`.
+
+Use this when one operation is more expensive than another.
+
+```ts
+const limiter = new RateLimiterBuilder()
+  .withMemoryStore()
+  .forSlidingWindow({ limit: 100, windowMs: 60_000 })
+  .build();
+
+await limiter.check("tenant:42", { cost: 5 });
+```
+
+Example uses:
+
+- expensive report generation counts as `5`
+- normal read counts as `1`
+- bulk export counts as `10`
+
+## Response headers
+
+By default the HTTP adapters set:
+
+- `ratelimit-limit`
+- `ratelimit-remaining`
+- `ratelimit-reset`
+- `ratelimit-policy`
+- `retry-after`
+
+Disable this with `setHeaders: false` if you need full manual control.
+
+## Factory vs Builder
+
+Use the Builder when you want readability and progressive configuration.
+
+```ts
+const limiter = new RateLimiterBuilder()
+  .withMemoryStore()
+  .forSlidingWindow({ limit: 50, windowMs: 10_000 })
+  .withKeyPrefix("public-api")
+  .withCache(25)
+  .build();
+```
+
+Use `createRateLimiter()` when a plain config object is enough.
+
+```ts
+import { createRateLimiter } from "@xyph3r/rate-limiter";
+
+const limiter = createRateLimiter({
+  algorithm: "sliding-window",
+  limit: 50,
+  windowMs: 10_000,
+  keyPrefix: "public-api",
+  cacheMs: 25,
+});
+```
+
 ## Public API
 
 ### `RateLimiterBuilder`
@@ -265,6 +437,7 @@ export const RateLimitGuard = createNestRateLimitGuard(limiter, {
 - `.useStore(store)` / `.withMemoryStore()`
 - `.withKeyPrefix(prefix)`
 - `.withCache(ttlMs)`
+- `.withClock(now)`
 - `.build()`
 
 ### `RateLimiterLike`
@@ -274,11 +447,12 @@ export const RateLimitGuard = createNestRateLimitGuard(limiter, {
 
 ### 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()`
+- `createExpressRateLimit()`
+- `createFastifyRateLimit()`
+- `createFetchRateLimit()`
+- `createHonoRateLimit()`
+- `createNextRateLimit()`
+- `createNestRateLimitGuard()`
 
 ### Decision fields
 
@@ -287,24 +461,26 @@ export const RateLimitGuard = createNestRateLimitGuard(limiter, {
 - `used`
 - `remaining`
 - `retryAfterMs`
+- `retryAfterSeconds`
 - `resetAt`
+- `resetAfterMs`
 - `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.
+- Sliding window uses a weighted previous-window approximation, not a timestamp log.
+- Redis checks are atomic because each strategy ships its own Lua program.
+- Bun and Next.js share the fetch adapter shape under the hood.
+- The optional cache proxy is only for very short-lived hot-path reuse. It is not a replacement for Redis.
 
 ## Publishing
 
-The package is set up so `npm publish` builds `dist/` during `prepack` and runs the test suite during `prepublishOnly`.
+The package is set up so `npm publish` builds `dist/` during `prepack` and runs tests 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`.
+1. Install dependencies with `bun install` or `npm install`.
+2. Verify with `bun run test` and `bun run build`.
+3. Inspect the tarball with `npm pack --dry-run`.
+4. Log in with `npm login` if needed.
+5. Publish with `npm publish --access public --provenance`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyph3r/rate-limiter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-agnostic rate limiting for Node.js with sliding window and token bucket strategies.",
   "author": "xyph3r",
   "license": "MIT",