ratelimit-flex 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [1.0.0] - 2026-03-27
+
+### Added
+- Initial public release of `ratelimit-flex`.
+- Rate limiting strategies: sliding window, fixed window, and token bucket.
+- Express middleware and Fastify plugin integrations.
+- `MemoryStore` and Redis-backed `RedisStore`.
+- TypeScript-first API with documented defaults and strategy options.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ratelimit-flex contributors
+
+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,274 @@
+# ratelimit-flex
+
+[![npm version](https://img.shields.io/npm/v/ratelimit-flex.svg)](https://www.npmjs.com/package/ratelimit-flex)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+![Tests](https://img.shields.io/badge/tests-vitest%20passing-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-First-3178C6?logo=typescript&logoColor=white)
+
+Flexible, TypeScript-first rate limiting for Node.js APIs with first-class Express and Fastify support.
+
+**Key features**
+- Multiple strategies: sliding window, token bucket, fixed window
+- Works with Express and Fastify
+- Pluggable stores: in-memory and Redis
+- Strong TypeScript types and clean public API
+- Supports custom keys, skip logic, callbacks, and custom responses
+
+## Installation
+
+```bash
+npm install ratelimit-flex
+```
+
+```bash
+yarn add ratelimit-flex
+```
+
+```bash
+pnpm add ratelimit-flex
+```
+
+**Note:** The published package targets **Node.js 18+**. Continuous integration and local development use **Node.js 20.12+** because Vitest 4 depends on APIs that are not available on Node 18.
+
+## Quick Start (Express)
+
+```ts
+import express from 'express';
+import rateLimit from 'ratelimit-flex';
+const app = express();
+app.use(rateLimit({ maxRequests: 100, windowMs: 60_000 }));
+app.get('/health', (_req, res) => res.json({ ok: true }));
+```
+
+## Strategies
+
+### Sliding Window
+Most accurate for per-window fairness because each request is counted against a moving window, not a fixed boundary. Use this as your default for user-facing APIs where consistency matters more than minimal memory usage.
+
+### Token Bucket
+Great when you want to allow short bursts while still enforcing a long-term average rate. Useful for APIs where occasional spikes are expected (mobile reconnects, batchy clients, webhook retries).
+
+### Fixed Window
+Simplest and most memory-efficient approach. Best for straightforward rate limiting where slight boundary effects are acceptable (for example, internal tools or low-risk endpoints).
+
+## API Reference
+
+### Exports
+
+```ts
+import rateLimit, {
+  expressRateLimiter,
+  fastifyRateLimiter,
+  createRateLimiter,
+  createRateLimitEngine,
+  MemoryStore,
+  RedisStore,
+  RateLimitEngine,
+  RateLimitStrategy,
+  slidingWindowDefaults,
+  fixedWindowDefaults,
+  tokenBucketDefaults,
+} from 'ratelimit-flex';
+```
+
+- Default export: `expressRateLimiter`
+- Named exports include all of the above plus all types from `types/index.ts`
+- `createRateLimitEngine(options)`: factory that returns a `RateLimitEngine` instance (for advanced use cases)
+
+### `RateLimitOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `strategy` | `RateLimitStrategy` | `SLIDING_WINDOW` | Strategy to use: `SLIDING_WINDOW`, `TOKEN_BUCKET`, or `FIXED_WINDOW` |
+| `store` | `RateLimitStore` | `MemoryStore` (when omitted in middleware helpers) | Backing store for counters/token state |
+| `keyGenerator` | `(req: unknown) => string` | framework IP-based fallback | Builds the rate-limit key (user, API key, tenant, etc.) |
+| `onLimitReached` | `(req, result) => void \| Promise<void>` | `undefined` | Called when a request is blocked |
+| `skip` | `(req: unknown) => boolean` | `undefined` | Skip rate limiting entirely for matching requests |
+| `headers` | `boolean` | `true` | Adds `X-RateLimit-*` and `Retry-After` headers |
+| `statusCode` | `number` | `429` | HTTP status code used when blocked |
+| `message` | `string \| object` | `"Too many requests"` | Error payload wrapped as `{ error: message }` |
+| `skipFailedRequests` | `boolean` | `false` | Decrement usage for failed responses (`>= 400`) |
+| `skipSuccessfulRequests` | `boolean` | `false` | Decrement usage for successful responses (`< 400`) |
+| `windowMs` | `number` | `60000` | Window length for sliding/fixed window strategies |
+| `maxRequests` | `number` | `100` | Max requests per window for sliding/fixed window |
+| `tokensPerInterval` | `number` | `10` | Tokens refilled per interval (token bucket) |
+| `interval` | `number` | `60000` | Refill interval in ms (token bucket) |
+| `bucketSize` | `number` | `100` | Max bucket capacity (token bucket burst size) |
+
+### Defaults
+
+- `slidingWindowDefaults`: `{ strategy: SLIDING_WINDOW, windowMs: 60000, maxRequests: 100 }`
+- `fixedWindowDefaults`: `{ strategy: FIXED_WINDOW, windowMs: 60000, maxRequests: 100 }`
+- `tokenBucketDefaults`: `{ strategy: TOKEN_BUCKET, tokensPerInterval: 10, interval: 60000, bucketSize: 100 }`
+
+### Convenience Factory: `createRateLimiter(options)`
+
+`createRateLimiter` returns an object with both `.express` and `.fastify` properties:
+
+```ts
+const limiter = createRateLimiter({ maxRequests: 100 });
+app.use(limiter.express);           // Express
+await app.register(limiter.fastify); // Fastify
+```
+
+**Note**: This function requires `fastify-plugin` as a peer dependency (already listed). For best type-safety and clarity, prefer direct imports (`expressRateLimiter` or `fastifyRateLimiter`) when you already know your framework.
+
+## Examples
+
+### Basic Express usage
+
+```ts
+import express from 'express';
+import { expressRateLimiter } from 'ratelimit-flex';
+
+const app = express();
+app.use(
+  expressRateLimiter({
+    strategy: 'SLIDING_WINDOW',
+    windowMs: 60_000,
+    maxRequests: 100,
+  }),
+);
+```
+
+### Basic Fastify usage
+
+```ts
+import Fastify from 'fastify';
+import { fastifyRateLimiter, RateLimitStrategy } from 'ratelimit-flex';
+
+const app = Fastify();
+await app.register(fastifyRateLimiter, {
+  strategy: RateLimitStrategy.SLIDING_WINDOW,
+  windowMs: 60_000,
+  maxRequests: 100,
+});
+```
+
+### Per-user rate limiting by API key
+
+```ts
+import { expressRateLimiter } from 'ratelimit-flex';
+
+app.use(
+  expressRateLimiter({
+    maxRequests: 60,
+    windowMs: 60_000,
+    keyGenerator: (req) =>
+      String((req as import('express').Request).header('x-api-key') ?? 'anonymous'),
+  }),
+);
+```
+
+### Token bucket for API endpoints
+
+```ts
+import { expressRateLimiter, RateLimitStrategy } from 'ratelimit-flex';
+
+app.use(
+  '/api',
+  expressRateLimiter({
+    strategy: RateLimitStrategy.TOKEN_BUCKET,
+    tokensPerInterval: 20,
+    interval: 60_000,
+    bucketSize: 60,
+  }),
+);
+```
+
+### Using RedisStore for distributed systems
+
+```ts
+import { expressRateLimiter, RedisStore, RateLimitStrategy } from 'ratelimit-flex';
+
+const store = new RedisStore({
+  strategy: RateLimitStrategy.SLIDING_WINDOW,
+  windowMs: 60_000,
+  maxRequests: 100,
+  url: process.env.REDIS_URL!,
+});
+
+app.use(expressRateLimiter({ strategy: RateLimitStrategy.SLIDING_WINDOW, store }));
+```
+
+### Custom error responses
+
+```ts
+app.use(
+  expressRateLimiter({
+    maxRequests: 20,
+    windowMs: 60_000,
+    statusCode: 429,
+    message: { code: 'RATE_LIMITED', detail: 'Please retry shortly.' },
+  }),
+);
+```
+
+### Skipping certain routes
+
+```ts
+app.use(
+  expressRateLimiter({
+    maxRequests: 100,
+    windowMs: 60_000,
+    skip: (req) => String((req as { path?: string }).path ?? '').startsWith('/health'),
+  }),
+);
+```
+
+### Multiple rate limiters (global + per-endpoint)
+
+```ts
+import { expressRateLimiter } from 'ratelimit-flex';
+
+app.use(expressRateLimiter({ maxRequests: 100, windowMs: 60_000 })); // global
+app.use('/login', expressRateLimiter({ maxRequests: 10, windowMs: 60_000 })); // strict endpoint
+```
+
+## Stores
+
+| Store | Best for | Pros | Trade-offs |
+|---|---|---|---|
+| `MemoryStore` | Single-instance apps, local development | Zero setup, fastest, no external dependencies | Not shared across multiple app instances/processes |
+| `RedisStore` | Multi-instance/distributed deployments | Shared counters across nodes, atomic operations via Lua scripts | Requires Redis and network round-trips |
+
+## Writing Custom Stores
+
+Implement the `RateLimitStore` interface:
+
+```ts
+export interface RateLimitStore {
+  increment(key: string): Promise<{
+    totalHits: number;
+    remaining: number;
+    resetTime: Date;
+    isBlocked: boolean;
+  }>;
+  decrement(key: string): Promise<void>;
+  reset(key: string): Promise<void>;
+  shutdown(): Promise<void>;
+}
+```
+
+Use your custom store by passing `store` in options:
+
+```ts
+app.use(expressRateLimiter({ store: myCustomStore, maxRequests: 100, windowMs: 60_000 }));
+```
+
+## Contributing
+
+Contributions are welcome.
+
+1. Fork the repository
+2. Create a feature branch
+3. Add or update tests
+4. Run checks locally:
+   - `npm test`
+   - `npm run build`
+   - `npm run lint`
+5. Open a pull request with context and rationale
+
+## License
+
+MIT

package/dist/cjs/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ratelimit-flex — flexible rate limiting for Node.js
+ */
+import { expressRateLimiter } from './middleware/express.js';
+import { fastifyRateLimiter } from './middleware/fastify.js';
+import type { RateLimitOptions } from './types/index.js';
+export declare const VERSION = "0.1.0";
+export { expressRateLimiter, fastifyRateLimiter };
+export { RateLimitEngine, createRateLimiter as createRateLimitEngine, defaultKeyGenerator, type RateLimitConsumeResult, type RateLimiterConfigInput, } from './strategies/rate-limit-engine.js';
+export { MemoryStore } from './stores/memory-store.js';
+export { RedisStore } from './stores/redis-store.js';
+export { fixedWindowDefaults, slidingWindowDefaults, tokenBucketDefaults } from './strategies/defaults.js';
+export * from './types/index.js';
+export { RateLimitStrategy } from './types/index.js';
+/**
+ * Convenience factory that returns both Express middleware and Fastify plugin.
+ *
+ * Usage:
+ * ```ts
+ * const limiter = createRateLimiter({ maxRequests: 100 });
+ * app.use(limiter.express);           // Express
+ * await app.register(limiter.fastify); // Fastify
+ * ```
+ *
+ * Prefer importing `expressRateLimiter` or `fastifyRateLimiter` directly when framework is known.
+ */
+export declare function createRateLimiter(options: Partial<RateLimitOptions>): {
+    express: import("express").RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+    fastify: typeof fastifyRateLimiter;
+};
+export default expressRateLimiter;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;AAGlD,OAAO,EACL,eAAe,EACf,iBAAiB,IAAI,qBAAqB,EAC1C,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG3G,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC;;aActC,OAAO,kBAAkB;EAEtD;AAGD,eAAe,kBAAkB,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * ratelimit-flex — flexible rate limiting for Node.js
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitStrategy = exports.tokenBucketDefaults = exports.slidingWindowDefaults = exports.fixedWindowDefaults = exports.RedisStore = exports.MemoryStore = exports.defaultKeyGenerator = exports.createRateLimitEngine = exports.RateLimitEngine = exports.fastifyRateLimiter = exports.expressRateLimiter = exports.VERSION = void 0;
+exports.createRateLimiter = createRateLimiter;
+const express_js_1 = require("./middleware/express.js");
+Object.defineProperty(exports, "expressRateLimiter", { enumerable: true, get: function () { return express_js_1.expressRateLimiter; } });
+const fastify_js_1 = require("./middleware/fastify.js");
+Object.defineProperty(exports, "fastifyRateLimiter", { enumerable: true, get: function () { return fastify_js_1.fastifyRateLimiter; } });
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+exports.VERSION = '0.1.0';
+// Core engine and stores
+var rate_limit_engine_js_1 = require("./strategies/rate-limit-engine.js");
+Object.defineProperty(exports, "RateLimitEngine", { enumerable: true, get: function () { return rate_limit_engine_js_1.RateLimitEngine; } });
+Object.defineProperty(exports, "createRateLimitEngine", { enumerable: true, get: function () { return rate_limit_engine_js_1.createRateLimiter; } });
+Object.defineProperty(exports, "defaultKeyGenerator", { enumerable: true, get: function () { return rate_limit_engine_js_1.defaultKeyGenerator; } });
+var memory_store_js_1 = require("./stores/memory-store.js");
+Object.defineProperty(exports, "MemoryStore", { enumerable: true, get: function () { return memory_store_js_1.MemoryStore; } });
+var redis_store_js_1 = require("./stores/redis-store.js");
+Object.defineProperty(exports, "RedisStore", { enumerable: true, get: function () { return redis_store_js_1.RedisStore; } });
+// Built-in defaults
+var defaults_js_1 = require("./strategies/defaults.js");
+Object.defineProperty(exports, "fixedWindowDefaults", { enumerable: true, get: function () { return defaults_js_1.fixedWindowDefaults; } });
+Object.defineProperty(exports, "slidingWindowDefaults", { enumerable: true, get: function () { return defaults_js_1.slidingWindowDefaults; } });
+Object.defineProperty(exports, "tokenBucketDefaults", { enumerable: true, get: function () { return defaults_js_1.tokenBucketDefaults; } });
+// Shared types and enums
+__exportStar(require("./types/index.js"), exports);
+var index_js_1 = require("./types/index.js");
+Object.defineProperty(exports, "RateLimitStrategy", { enumerable: true, get: function () { return index_js_1.RateLimitStrategy; } });
+/**
+ * Convenience factory that returns both Express middleware and Fastify plugin.
+ *
+ * Usage:
+ * ```ts
+ * const limiter = createRateLimiter({ maxRequests: 100 });
+ * app.use(limiter.express);           // Express
+ * await app.register(limiter.fastify); // Fastify
+ * ```
+ *
+ * Prefer importing `expressRateLimiter` or `fastifyRateLimiter` directly when framework is known.
+ */
+function createRateLimiter(options) {
+    const wrappedPlugin = (0, fastify_plugin_1.default)(async (fastify, pluginOpts = {}) => {
+        const merged = { ...options, ...pluginOpts };
+        return fastify_js_1.fastifyRateLimiter(fastify, merged);
+    }, { name: 'ratelimit-flex-wrapper' });
+    return {
+        express: (0, express_js_1.expressRateLimiter)(options),
+        fastify: wrappedPlugin,
+    };
+}
+// Express is the most common default integration path.
+exports.default = express_js_1.expressRateLimiter;
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;AA0CH,8CAgBC;AAxDD,wDAA6D;AAQpD,mGARA,+BAAkB,OAQA;AAP3B,wDAA6D;AAOhC,mGAPpB,+BAAkB,OAOoB;AAL/C,oEAAgC;AAEnB,QAAA,OAAO,GAAG,OAAO,CAAC;AAK/B,yBAAyB;AACzB,0EAM2C;AALzC,uHAAA,eAAe,OAAA;AACf,6HAAA,iBAAiB,OAAyB;AAC1C,2HAAA,mBAAmB,OAAA;AAIrB,4DAAuD;AAA9C,8GAAA,WAAW,OAAA;AACpB,0DAAqD;AAA5C,4GAAA,UAAU,OAAA;AAEnB,oBAAoB;AACpB,wDAA2G;AAAlG,kHAAA,mBAAmB,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AAAE,kHAAA,mBAAmB,OAAA;AAExE,yBAAyB;AACzB,mDAAiC;AACjC,6CAAqD;AAA5C,6GAAA,iBAAiB,OAAA;AAE1B;;;;;;;;;;;GAWG;AACH,SAAgB,iBAAiB,CAAC,OAAkC;IAClE,MAAM,aAAa,GAAG,IAAA,wBAAE,EACtB,KAAK,EAAE,OAAgB,EAAE,aAAwC,EAAE,EAAE,EAAE;QACrE,MAAM,MAAM,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;QAC7C,OAAQ,+BAA6F,CACnG,OAAO,EACP,MAAM,CACP,CAAC;IACJ,CAAC,EACD,EAAE,IAAI,EAAE,wBAAwB,EAAE,CACnC,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,IAAA,+BAAkB,EAAC,OAAO,CAAC;QACpC,OAAO,EAAE,aAA0C;KACpD,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,kBAAe,+BAAkB,CAAC"}

package/dist/cjs/middleware/express.d.ts

@@ -0,0 +1,18 @@
+import type { RequestHandler } from 'express';
+import type { RateLimitInfo, RateLimitOptions } from '../types/index.js';
+declare module 'express-serve-static-core' {
+    interface Request {
+        /** Populated by {@link expressRateLimiter} after a successful consume (not blocked). */
+        rateLimit?: RateLimitInfo;
+    }
+}
+/**
+ * Express middleware factory. One {@link RateLimitEngine} and store are created per call (singleton for that middleware instance).
+ *
+ * @example
+ * ```ts
+ * app.use(expressRateLimiter({ maxRequests: 50 }));
+ * ```
+ */
+export declare function expressRateLimiter(options: Partial<RateLimitOptions>): RequestHandler;
+//# sourceMappingURL=express.d.ts.map

package/dist/cjs/middleware/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../../src/middleware/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,QAAQ,2BAA2B,CAAC;IACzC,UAAU,OAAO;QACf,wFAAwF;QACxF,SAAS,CAAC,EAAE,aAAa,CAAC;KAC3B;CACF;AAQD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,cAAc,CAkDrF"}

package/dist/cjs/middleware/express.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressRateLimiter = expressRateLimiter;
+const rate_limit_engine_js_1 = require("../strategies/rate-limit-engine.js");
+const merge_options_js_1 = require("./merge-options.js");
+function applyHeaders(res, headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        res.setHeader(name, value);
+    }
+}
+/**
+ * Express middleware factory. One {@link RateLimitEngine} and store are created per call (singleton for that middleware instance).
+ *
+ * @example
+ * ```ts
+ * app.use(expressRateLimiter({ maxRequests: 50 }));
+ * ```
+ */
+function expressRateLimiter(options) {
+    const resolved = (0, merge_options_js_1.mergeRateLimiterOptions)(options);
+    const { onLimitReached, ...engineOptions } = resolved;
+    const engine = new rate_limit_engine_js_1.RateLimitEngine(engineOptions);
+    const keyGen = resolved.keyGenerator ?? rate_limit_engine_js_1.defaultKeyGenerator;
+    return async function rateLimitMiddleware(req, res, next) {
+        if (resolved.skip?.(req) === true) {
+            next();
+            return;
+        }
+        const key = keyGen(req);
+        const result = await engine.consumeWithKey(key, req);
+        if (resolved.headers !== false) {
+            applyHeaders(res, result.headers);
+        }
+        if (result.isBlocked) {
+            if (onLimitReached) {
+                await Promise.resolve(onLimitReached(req, result));
+            }
+            res
+                .status(resolved.statusCode ?? 429)
+                .json((0, merge_options_js_1.jsonErrorBody)(resolved.message ?? 'Too many requests'));
+            return;
+        }
+        req.rateLimit = (0, merge_options_js_1.toRateLimitInfo)(resolved, result);
+        const shouldDecrementFailed = resolved.skipFailedRequests === true;
+        const shouldDecrementSuccess = resolved.skipSuccessfulRequests === true;
+        if (shouldDecrementFailed || shouldDecrementSuccess) {
+            res.once('finish', () => {
+                const status = res.statusCode;
+                const failed = status >= 400;
+                const success = status < 400;
+                if ((shouldDecrementFailed && failed) || (shouldDecrementSuccess && success)) {
+                    void resolved.store.decrement(key).catch(() => {
+                        /* ignore */
+                    });
+                }
+            });
+        }
+        next();
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/cjs/middleware/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../../src/middleware/express.ts"],"names":[],"mappings":";;AA0BA,gDAkDC;AA3ED,6EAA0F;AAE1F,yDAA6F;AAS7F,SAAS,YAAY,CAAC,GAAa,EAAE,OAA+B;IAClE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,OAAkC;IACnE,MAAM,QAAQ,GAAG,IAAA,0CAAuB,EAAC,OAAO,CAAC,CAAC;IAClD,MAAM,EAAE,cAAc,EAAE,GAAG,aAAa,EAAE,GAAG,QAAQ,CAAC;IACtD,MAAM,MAAM,GAAG,IAAI,sCAAe,CAAC,aAAa,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,YAAY,IAAI,0CAAmB,CAAC;IAE5D,OAAO,KAAK,UAAU,mBAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QACvF,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAClC,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAExB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAErD,IAAI,QAAQ,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;YAC/B,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;YACrD,CAAC;YACD,GAAG;iBACA,MAAM,CAAC,QAAQ,CAAC,UAAU,IAAI,GAAG,CAAC;iBAClC,IAAI,CAAC,IAAA,gCAAa,EAAC,QAAQ,CAAC,OAAO,IAAI,mBAAmB,CAAC,CAAC,CAAC;YAChE,OAAO;QACT,CAAC;QAED,GAAG,CAAC,SAAS,GAAG,IAAA,kCAAe,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAElD,MAAM,qBAAqB,GAAG,QAAQ,CAAC,kBAAkB,KAAK,IAAI,CAAC;QACnE,MAAM,sBAAsB,GAAG,QAAQ,CAAC,sBAAsB,KAAK,IAAI,CAAC;QAExE,IAAI,qBAAqB,IAAI,sBAAsB,EAAE,CAAC;YACpD,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE;gBACtB,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC;gBAC9B,MAAM,MAAM,GAAG,MAAM,IAAI,GAAG,CAAC;gBAC7B,MAAM,OAAO,GAAG,MAAM,GAAG,GAAG,CAAC;gBAC7B,IAAI,CAAC,qBAAqB,IAAI,MAAM,CAAC,IAAI,CAAC,sBAAsB,IAAI,OAAO,CAAC,EAAE,CAAC;oBAC7E,KAAK,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;wBAC5C,YAAY;oBACd,CAAC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/cjs/middleware/fastify.d.ts

@@ -0,0 +1,21 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { RateLimitInfo, RateLimitOptions } from '../types/index.js';
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** Populated by {@link fastifyRateLimiter} after a successful consume (not blocked). */
+        rateLimit?: RateLimitInfo;
+        /** Internal: storage key for optional response-based decrement. */
+        rateLimitKey?: string;
+        /** Internal: when to consider decrement on `onResponse`. */
+        rateLimitDecrementFlags?: {
+            onFailed: boolean;
+            onSuccess: boolean;
+        };
+    }
+}
+/**
+ * Fastify plugin (wrapped with `fastify-plugin` for correct encapsulation).
+ * Registers `onRequest` / `onResponse` hooks; one {@link RateLimitEngine} and store per registration.
+ */
+export declare const fastifyRateLimiter: FastifyPluginAsync<Partial<RateLimitOptions>>;
+//# sourceMappingURL=fastify.d.ts.map

package/dist/cjs/middleware/fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../../../src/middleware/fastify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,wFAAwF;QACxF,SAAS,CAAC,EAAE,aAAa,CAAC;QAC1B,mEAAmE;QACnE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,4DAA4D;QAC5D,uBAAuB,CAAC,EAAE;YACxB,QAAQ,EAAE,OAAO,CAAC;YAClB,SAAS,EAAE,OAAO,CAAC;SACpB,CAAC;KACH;CACF;AA6DD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,+CAE7B,CAAC"}

package/dist/cjs/middleware/fastify.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyRateLimiter = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const rate_limit_engine_js_1 = require("../strategies/rate-limit-engine.js");
+const merge_options_js_1 = require("./merge-options.js");
+const plugin = async (fastify, options) => {
+    const resolved = (0, merge_options_js_1.mergeRateLimiterOptions)(options);
+    const { onLimitReached, ...engineOptions } = resolved;
+    const engine = new rate_limit_engine_js_1.RateLimitEngine(engineOptions);
+    const keyGen = resolved.keyGenerator ?? rate_limit_engine_js_1.defaultKeyGenerator;
+    fastify.addHook('onRequest', async (request, reply) => {
+        if (resolved.skip?.(request) === true) {
+            return;
+        }
+        const key = keyGen(request);
+        const result = await engine.consumeWithKey(key, request);
+        if (resolved.headers !== false) {
+            for (const [name, value] of Object.entries(result.headers)) {
+                reply.header(name, value);
+            }
+        }
+        if (result.isBlocked) {
+            if (onLimitReached) {
+                await Promise.resolve(onLimitReached(request, result));
+            }
+            await reply
+                .status(resolved.statusCode ?? 429)
+                .send((0, merge_options_js_1.jsonErrorBody)(resolved.message ?? 'Too many requests'));
+            return;
+        }
+        request.rateLimit = (0, merge_options_js_1.toRateLimitInfo)(resolved, result);
+        const onFailed = resolved.skipFailedRequests === true;
+        const onSuccess = resolved.skipSuccessfulRequests === true;
+        if (onFailed || onSuccess) {
+            request.rateLimitKey = key;
+            request.rateLimitDecrementFlags = { onFailed, onSuccess };
+        }
+    });
+    fastify.addHook('onResponse', async (request, reply) => {
+        const key = request.rateLimitKey;
+        const flags = request.rateLimitDecrementFlags;
+        if (!key || !flags) {
+            return;
+        }
+        const status = reply.statusCode;
+        const failed = status >= 400;
+        const success = status < 400;
+        if ((flags.onFailed && failed) || (flags.onSuccess && success)) {
+            void resolved.store.decrement(key).catch(() => {
+                /* ignore */
+            });
+        }
+    });
+};
+/**
+ * Fastify plugin (wrapped with `fastify-plugin` for correct encapsulation).
+ * Registers `onRequest` / `onResponse` hooks; one {@link RateLimitEngine} and store per registration.
+ */
+exports.fastifyRateLimiter = (0, fastify_plugin_1.default)(plugin, {
+    name: 'ratelimit-flex',
+});
+//# sourceMappingURL=fastify.js.map

package/dist/cjs/middleware/fastify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../../../src/middleware/fastify.ts"],"names":[],"mappings":"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"}

package/dist/cjs/middleware/index.d.ts

@@ -0,0 +1,4 @@
+/** Framework middleware adapters (Express, Fastify, etc.) */
+export { expressRateLimiter } from './express.js';
+export { fastifyRateLimiter } from './fastify.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/cjs/middleware/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/** Framework middleware adapters (Express, Fastify, etc.) */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyRateLimiter = exports.expressRateLimiter = void 0;
+var express_js_1 = require("./express.js");
+Object.defineProperty(exports, "expressRateLimiter", { enumerable: true, get: function () { return express_js_1.expressRateLimiter; } });
+var fastify_js_1 = require("./fastify.js");
+Object.defineProperty(exports, "fastifyRateLimiter", { enumerable: true, get: function () { return fastify_js_1.fastifyRateLimiter; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/middleware/index.ts"],"names":[],"mappings":";AAAA,6DAA6D;;;AAE7D,2CAAkD;AAAzC,gHAAA,kBAAkB,OAAA;AAC3B,2CAAkD;AAAzC,gHAAA,kBAAkB,OAAA"}

package/dist/cjs/middleware/merge-options.d.ts

@@ -0,0 +1,16 @@
+import type { RateLimitInfo, RateLimitOptions, RateLimitResult } from '../types/index.js';
+export declare const baseDefaults: {
+    readonly headers: true;
+    readonly statusCode: 429;
+    readonly message: "Too many requests";
+    readonly skipFailedRequests: false;
+    readonly skipSuccessfulRequests: false;
+};
+export declare function getLimit(opts: RateLimitOptions): number;
+/**
+ * Merge partial options with strategy defaults and ensure a {@link MemoryStore} when `store` is omitted.
+ */
+export declare function mergeRateLimiterOptions(options: Partial<RateLimitOptions>): RateLimitOptions;
+export declare function toRateLimitInfo(opts: RateLimitOptions, result: RateLimitResult): RateLimitInfo;
+export declare function jsonErrorBody(message: string | object): object;
+//# sourceMappingURL=merge-options.d.ts.map

package/dist/cjs/middleware/merge-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-options.d.ts","sourceRoot":"","sources":["../../../src/middleware/merge-options.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG1F,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,wBAAgB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAKvD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAwC5F;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe,GAAG,aAAa,CAO9F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAE9D"}