nextlimiter 1.0.3 → 1.0.4

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Production-ready rate limiting for Node.js — sliding window, token bucket, SaaS plans, smart limiting, and built-in analytics.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./fastify": "./src/adapters/fastify.js",
+    "./next": "./src/adapters/next.js",
+    "./hono": "./src/adapters/hono.js"
+  },
   "files": [
     "src/",
     "types/",
@@ -36,7 +42,10 @@
   },
   "peerDependencies": {
     "express": ">=4.0.0",
-    "ioredis": ">=4.0.0"
+    "ioredis": ">=4.0.0",
+    "fastify": ">=4.0.0",
+    "fastify-plugin": ">=4.0.0",
+    "hono": ">=3.0.0"
   },
   "peerDependenciesMeta": {
     "express": {
@@ -44,6 +53,15 @@
     },
     "ioredis": {
       "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "fastify-plugin": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/adapters/fastify.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * NextLimiter — Fastify adapter
+ *
+ * Registers a Fastify plugin that applies rate limiting via an onRequest hook.
+ * Uses the same createLimiter() core — no rate limit logic lives here.
+ *
+ * Peer dependency: fastify-plugin (npm install fastify-plugin)
+ *
+ * @example
+ * const fastify = require('fastify')();
+ * const fastifyRateLimit = require('nextlimiter/fastify');
+ *
+ * fastify.register(fastifyRateLimit, { max: 100, windowMs: 60_000 });
+ */
+
+const { createLimiter } = require('../index');
+
+/**
+ * Extract the best available IP from a Fastify request.
+ * @param {object} request - Fastify request object
+ * @returns {string}
+ */
+function extractIp(request) {
+  return (
+    request.headers['cf-connecting-ip'] ||
+    request.headers['x-forwarded-for']?.split(',')[0]?.trim() ||
+    request.ip ||
+    'unknown'
+  );
+}
+
+/**
+ * Fastify plugin factory.
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} options - Same options as createLimiter()
+ * @param {function} done
+ */
+async function plugin(fastify, options) {
+  const limiter = createLimiter(options);
+
+  fastify.addHook('onRequest', async (request, reply) => {
+    try {
+      const ip     = extractIp(request);
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return reply.code(429).send({
+          error:      'Too Many Requests',
+          retryAfter: result.retryAfter,
+          limit:      result.limit,
+          resetAt:    new Date(result.resetAt).toISOString(),
+        });
+      }
+
+      // Set rate limit headers on allowed requests
+      reply.header('X-RateLimit-Limit',     String(result.limit));
+      reply.header('X-RateLimit-Remaining', String(result.remaining));
+      reply.header('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      reply.header('X-RateLimit-Strategy',  result.strategy);
+    } catch (err) {
+      // Fail open — never let the rate limiter take down the app
+      request.log.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+    }
+  });
+}
+
+let fastifyPlugin;
+try {
+  fastifyPlugin = require('fastify-plugin');
+} catch {
+  // If fastify-plugin is not installed, wrap minimally so the plugin still works
+  fastifyPlugin = (fn, meta) => fn;
+}
+
+module.exports = fastifyPlugin(plugin, {
+  fastify:  '>=4.0.0',
+  name:     'nextlimiter',
+});

package/src/adapters/hono.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * NextLimiter — Hono adapter
+ *
+ * Provides a Hono-compatible middleware factory for Cloudflare Workers,
+ * Bun, Deno, and any edge runtime supported by Hono.
+ *
+ * Uses Web APIs only (fetch/Request/Response/Headers) — no Node.js built-ins.
+ * Safe to deploy on Cloudflare Workers, Vercel Edge, and Deno Deploy.
+ *
+ * No peer dependencies required beyond Hono itself.
+ *
+ * @example
+ * const { Hono } = require('hono');
+ * const { rateLimitMiddleware } = require('nextlimiter/hono');
+ *
+ * const app = new Hono();
+ * app.use('*', rateLimitMiddleware({ max: 100, windowMs: 60_000 }));
+ *
+ * app.get('/', (c) => c.text('Hello World!'));
+ * export default app;
+ */
+
+const { createLimiter } = require('../index');
+
+/**
+ * Extract the real client IP from a Hono context.
+ * Prioritises Cloudflare's CF-Connecting-IP header, then X-Forwarded-For.
+ *
+ * @param {import('hono').Context} c
+ * @returns {string}
+ */
+function extractIp(c) {
+  return (
+    c.req.header('cf-connecting-ip') ||
+    c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+    c.req.header('x-real-ip') ||
+    'unknown'
+  );
+}
+
+/**
+ * Hono middleware factory.
+ *
+ * @param {object} options - Same options as createLimiter()
+ * @returns {import('hono').MiddlewareHandler}
+ *
+ * @example
+ * app.use('/api/*', rateLimitMiddleware({ max: 100, windowMs: 60_000, strategy: 'sliding-window' }));
+ */
+function rateLimitMiddleware(options = {}) {
+  const limiter = createLimiter(options);
+
+  return async function honoRateLimitMiddleware(c, next) {
+    try {
+      const ip     = extractIp(c);
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return c.json(
+          {
+            error:      'Too Many Requests',
+            retryAfter: result.retryAfter,
+            limit:      result.limit,
+            resetAt:    new Date(result.resetAt).toISOString(),
+          },
+          429
+        );
+      }
+
+      // Set rate limit headers before passing to next handler
+      c.header('X-RateLimit-Limit',     String(result.limit));
+      c.header('X-RateLimit-Remaining', String(result.remaining));
+      c.header('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      c.header('X-RateLimit-Strategy',  result.strategy);
+
+      await next();
+    } catch (err) {
+      // Fail open — never let the rate limiter crash the Hono app
+      console.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+      await next();
+    }
+  };
+}
+
+module.exports = { rateLimitMiddleware };

package/src/adapters/next.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * NextLimiter — Next.js adapter
+ *
+ * Provides two higher-order wrappers:
+ *   withRateLimit()     — for Next.js Pages Router API routes (Node.js runtime)
+ *   withRateLimitEdge() — for App Router / middleware.js (Edge runtime, Web APIs only)
+ *
+ * No peer dependencies required.
+ *
+ * @example
+ * // Pages Router (pages/api/hello.js)
+ * const { withRateLimit } = require('nextlimiter/next');
+ * export default withRateLimit(handler, { max: 100, windowMs: 60_000 });
+ *
+ * // App Router / Edge (middleware.js)
+ * const { withRateLimitEdge } = require('nextlimiter/next');
+ * export default withRateLimitEdge(handler, { max: 50 });
+ */
+
+const { createLimiter } = require('../index');
+
+// ── Shared helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Memoize limiter instances per options reference so the limiter is only
+ * created once per HOC call, not on every request.
+ */
+const limiterCache = new WeakMap();
+
+function getLimiter(options) {
+  if (limiterCache.has(options)) return limiterCache.get(options);
+  const limiter = createLimiter(options);
+  limiterCache.set(options, limiter);
+  return limiter;
+}
+
+// ── Pages Router (Node.js runtime) ───────────────────────────────────────────
+
+/**
+ * Higher-order function for Next.js Pages Router API routes.
+ * Wraps a handler with rate limiting using the Node.js HTTP req/res API.
+ *
+ * @param {function} handler - Next.js API route handler (req, res) => void
+ * @param {object}   options - createLimiter() options
+ * @returns {function} wrapped async handler
+ *
+ * @example
+ * export default withRateLimit(async (req, res) => {
+ *   res.json({ hello: 'world' });
+ * }, { max: 100, windowMs: 60_000 });
+ */
+function withRateLimit(handler, options = {}) {
+  const limiter = getLimiter(options);
+
+  return async function rateLimitedHandler(req, res) {
+    try {
+      const ip =
+        (req.headers['x-forwarded-for']?.split(',')[0]?.trim()) ||
+        req.socket?.remoteAddress ||
+        'unknown';
+
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return res.status(429).json({
+          error:      'Too Many Requests',
+          retryAfter: result.retryAfter,
+          limit:      result.limit,
+          resetAt:    new Date(result.resetAt).toISOString(),
+        });
+      }
+
+      // Set rate limit headers
+      res.setHeader('X-RateLimit-Limit',     String(result.limit));
+      res.setHeader('X-RateLimit-Remaining', String(result.remaining));
+      res.setHeader('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      res.setHeader('X-RateLimit-Strategy',  result.strategy);
+
+      return handler(req, res);
+    } catch (err) {
+      // Fail open — never let the rate limiter crash the API route
+      console.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+      return handler(req, res);
+    }
+  };
+}
+
+// ── App Router / Edge runtime (Web APIs only) ─────────────────────────────────
+
+/**
+ * Higher-order function for Next.js App Router or middleware.js.
+ * Uses Web Request/Response API only — no Node.js built-ins.
+ * Safe to run on Vercel Edge, Cloudflare Workers, and Deno.
+ *
+ * @param {function} handler - async (request: Request) => Response
+ * @param {object}   options - createLimiter() options
+ * @returns {function} wrapped async handler
+ *
+ * @example
+ * // middleware.js
+ * export default withRateLimitEdge(async (req) => {
+ *   return new Response('OK');
+ * }, { max: 50, windowMs: 60_000 });
+ */
+function withRateLimitEdge(handler, options = {}) {
+  const limiter = getLimiter(options);
+
+  return async function rateLimitedEdgeHandler(request) {
+    try {
+      const ip =
+        request.headers.get('cf-connecting-ip') ||
+        request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+        'unknown';
+
+      const result = await limiter.check(ip);
+
+      if (!result.allowed) {
+        return new Response(
+          JSON.stringify({
+            error:      'Too Many Requests',
+            retryAfter: result.retryAfter,
+            limit:      result.limit,
+            resetAt:    new Date(result.resetAt).toISOString(),
+          }),
+          {
+            status:  429,
+            headers: { 'Content-Type': 'application/json' },
+          }
+        );
+      }
+
+      // Call the handler and inject rate limit headers into the response
+      const response = await handler(request);
+
+      // Clone with additional headers (Response is immutable)
+      const headers = new Headers(response.headers);
+      headers.set('X-RateLimit-Limit',     String(result.limit));
+      headers.set('X-RateLimit-Remaining', String(result.remaining));
+      headers.set('X-RateLimit-Reset',     String(Math.ceil(result.resetAt / 1000)));
+      headers.set('X-RateLimit-Strategy',  result.strategy);
+
+      return new Response(response.body, {
+        status:     response.status,
+        statusText: response.statusText,
+        headers,
+      });
+    } catch (err) {
+      // Fail open
+      console.warn(`[NextLimiter] Rate limiter error: ${err.message}. Failing open.`);
+      return handler(request);
+    }
+  };
+}
+
+module.exports = { withRateLimit, withRateLimitEdge };

package/types/index.d.ts

@@ -275,3 +275,52 @@ export declare class RedisStore implements Store {
 
 export declare const PRESETS: Record<BuiltInPreset, LimiterOptions>;
 export declare const DEFAULT_PLANS: Record<BuiltInPlan, PlanDefinition>;
+
+// ── Adapters ─────────────────────────────────────────────────────────────────
+//
+// These are available as subpath imports:
+//   import fastifyRateLimit from 'nextlimiter/fastify'
+//   import { withRateLimit, withRateLimitEdge } from 'nextlimiter/next'
+//   import { rateLimitMiddleware } from 'nextlimiter/hono'
+
+// fastify adapter
+declare module 'nextlimiter/fastify' {
+  import { FastifyPluginAsync } from 'fastify';
+  const fastifyRateLimit: FastifyPluginAsync<LimiterOptions>;
+  export default fastifyRateLimit;
+}
+
+// next.js adapter
+declare module 'nextlimiter/next' {
+  import type { NextApiRequest, NextApiResponse } from 'next';
+
+  /**
+   * Wrap a Next.js Pages Router API handler with rate limiting (Node.js runtime).
+   */
+  export function withRateLimit<T extends (req: NextApiRequest, res: NextApiResponse) => any>(
+    handler: T,
+    options?: LimiterOptions
+  ): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+
+  /**
+   * Wrap a Next.js App Router / middleware handler with rate limiting (Edge runtime).
+   * Uses Web Request / Response API only — no Node.js built-ins.
+   */
+  export function withRateLimitEdge<T extends (req: Request) => Promise<Response>>(
+    handler: T,
+    options?: LimiterOptions
+  ): (req: Request) => Promise<Response>;
+}
+
+// hono adapter
+declare module 'nextlimiter/hono' {
+  /**
+   * Returns a Hono middleware that applies rate limiting.
+   * Safe for Cloudflare Workers, Bun, Deno — uses Web APIs only.
+   *
+   * @example
+   * app.use('*', rateLimitMiddleware({ max: 100, windowMs: 60_000 }));
+   */
+  export function rateLimitMiddleware(options?: LimiterOptions): (c: any, next: () => Promise<void>) => Promise<void>;
+}
+