@jellyfungus/hono-rate-limiter 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# @jellyfungus/hono-rate-limiter
+
+Rate limiting middleware for [Hono](https://hono.dev) web framework.
+
+[![npm version](https://img.shields.io/npm/v/@jellyfungus/hono-rate-limiter.svg)](https://www.npmjs.com/package/@jellyfungus/hono-rate-limiter)
+[![CI](https://github.com/rokasta12/hono-rate-limiter/actions/workflows/ci.yml/badge.svg)](https://github.com/rokasta12/hono-rate-limiter/actions/workflows/ci.yml)
+
+## Features
+
+- **Sliding Window Algorithm** - Accurate rate limiting with Cloudflare's approach
+- **Fixed Window Algorithm** - Simple alternative
+- **Multiple Stores** - Memory (default), Redis, Cloudflare KV
+- **IETF Headers** - RateLimit headers (draft-6, draft-7)
+- **Dynamic Limits** - Per-user or per-route limits
+- **TypeScript** - Full type support
+- **Zero Dependencies** - Only requires Hono as peer dependency
+
+## Installation
+
+```bash
+npm install @jellyfungus/hono-rate-limiter
+# or
+bun add @jellyfungus/hono-rate-limiter
+```
+
+## Basic Usage
+
+```ts
+import { Hono } from "hono";
+import { rateLimiter } from "@jellyfungus/hono-rate-limiter";
+
+const app = new Hono();
+
+// 60 requests per minute (default)
+app.use(rateLimiter());
+
+// Custom configuration
+app.use(
+  "/api/*",
+  rateLimiter({
+    limit: 100,
+    windowMs: 60 * 1000, // 1 minute
+  }),
+);
+
+app.get("/", (c) => c.text("Hello!"));
+
+export default app;
+```
+
+## Options
+
+| Option                   | Type                                 | Default            | Description                   |
+| ------------------------ | ------------------------------------ | ------------------ | ----------------------------- |
+| `limit`                  | `number \| Function`                 | `60`               | Max requests per window       |
+| `windowMs`               | `number`                             | `60000`            | Window duration in ms         |
+| `algorithm`              | `'sliding-window' \| 'fixed-window'` | `'sliding-window'` | Rate limiting algorithm       |
+| `store`                  | `RateLimitStore`                     | `MemoryStore`      | Storage backend               |
+| `keyGenerator`           | `Function`                           | IP address         | Generate client key           |
+| `handler`                | `Function`                           | 429 response       | Custom rate limit handler     |
+| `headers`                | `'draft-6' \| 'draft-7' \| false`    | `'draft-6'`        | Header format                 |
+| `skip`                   | `Function`                           | -                  | Skip rate limiting            |
+| `skipSuccessfulRequests` | `boolean`                            | `false`            | Don't count 2xx responses     |
+| `skipFailedRequests`     | `boolean`                            | `false`            | Don't count 4xx/5xx responses |
+| `onRateLimited`          | `Function`                           | -                  | Callback when rate limited    |
+
+## Stores
+
+### Memory Store (Default)
+
+```ts
+import { rateLimiter } from "@jellyfungus/hono-rate-limiter";
+
+app.use(rateLimiter()); // Uses MemoryStore by default
+```
+
+### Redis Store
+
+```ts
+import { rateLimiter } from "@jellyfungus/hono-rate-limiter";
+import { RedisStore } from "@jellyfungus/hono-rate-limiter/store/redis";
+import Redis from "ioredis";
+
+const redis = new Redis(process.env.REDIS_URL);
+
+app.use(
+  rateLimiter({
+    store: new RedisStore({ client: redis }),
+  }),
+);
+```
+
+### Cloudflare KV Store
+
+```ts
+import { rateLimiter } from "@jellyfungus/hono-rate-limiter";
+import { CloudflareKVStore } from "@jellyfungus/hono-rate-limiter/store/cloudflare-kv";
+
+type Bindings = { RATE_LIMIT_KV: KVNamespace };
+
+app.use("*", async (c, next) => {
+  const limiter = rateLimiter({
+    store: new CloudflareKVStore({ namespace: c.env.RATE_LIMIT_KV }),
+  });
+  return limiter(c, next);
+});
+```
+
+## Dynamic Limits
+
+```ts
+app.use(
+  rateLimiter({
+    limit: async (c) => {
+      const user = c.get("user");
+      if (user?.tier === "premium") return 1000;
+      if (user?.tier === "pro") return 500;
+      return 100;
+    },
+  }),
+);
+```
+
+## Custom Key Generator
+
+```ts
+app.use(
+  rateLimiter({
+    keyGenerator: (c) => {
+      // Rate limit by API key instead of IP
+      return c.req.header("x-api-key") ?? "anonymous";
+    },
+  }),
+);
+```
+
+## Skip Certain Requests
+
+```ts
+app.use(
+  rateLimiter({
+    skip: (c) => {
+      // Don't rate limit health checks
+      return c.req.path === "/health";
+    },
+  }),
+);
+```
+
+## Access Rate Limit Info
+
+```ts
+app.get("/status", (c) => {
+  const info = c.get("rateLimit");
+  return c.json({
+    limit: info?.limit,
+    remaining: info?.remaining,
+    reset: info?.reset,
+  });
+});
+```
+
+## Custom Handler
+
+```ts
+app.use(
+  rateLimiter({
+    handler: (c, info) => {
+      return c.json(
+        {
+          error: "Rate limit exceeded",
+          retryAfter: Math.ceil((info.reset - Date.now()) / 1000),
+        },
+        429,
+      );
+    },
+  }),
+);
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,220 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryStore: () => MemoryStore,
+  getClientIP: () => getClientIP,
+  rateLimiter: () => rateLimiter
+});
+module.exports = __toCommonJS(index_exports);
+var MemoryStore = class {
+  entries = /* @__PURE__ */ new Map();
+  windowMs = 6e4;
+  cleanupTimer;
+  init(windowMs) {
+    this.windowMs = windowMs;
+    this.cleanupTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.entries) {
+        if (entry.reset <= now) {
+          this.entries.delete(key);
+        }
+      }
+    }, 6e4);
+    if (typeof this.cleanupTimer.unref === "function") {
+      this.cleanupTimer.unref();
+    }
+  }
+  increment(key) {
+    const now = Date.now();
+    const existing = this.entries.get(key);
+    if (!existing || existing.reset <= now) {
+      const reset = now + this.windowMs;
+      this.entries.set(key, { count: 1, reset });
+      return { count: 1, reset };
+    }
+    existing.count++;
+    return { count: existing.count, reset: existing.reset };
+  }
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry || entry.reset <= Date.now()) {
+      return void 0;
+    }
+    return { count: entry.count, reset: entry.reset };
+  }
+  decrement(key) {
+    const entry = this.entries.get(key);
+    if (entry && entry.count > 0) {
+      entry.count--;
+    }
+  }
+  resetKey(key) {
+    this.entries.delete(key);
+  }
+  shutdown() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+    this.entries.clear();
+  }
+};
+var defaultStore;
+function setHeaders(c, info, format) {
+  if (format === false) {
+    return;
+  }
+  const resetSeconds = Math.max(0, Math.ceil((info.reset - Date.now()) / 1e3));
+  switch (format) {
+    case "draft-7":
+      c.header("RateLimit-Limit", String(info.limit));
+      c.header("RateLimit-Remaining", String(info.remaining));
+      c.header("RateLimit-Reset", String(resetSeconds));
+      break;
+    case "draft-6":
+    default:
+      c.header("X-RateLimit-Limit", String(info.limit));
+      c.header("X-RateLimit-Remaining", String(info.remaining));
+      c.header("X-RateLimit-Reset", String(Math.ceil(info.reset / 1e3)));
+      break;
+  }
+}
+function getClientIP(c) {
+  const cfIP = c.req.header("cf-connecting-ip");
+  if (cfIP) {
+    return cfIP;
+  }
+  const xRealIP = c.req.header("x-real-ip");
+  if (xRealIP) {
+    return xRealIP;
+  }
+  const xff = c.req.header("x-forwarded-for");
+  if (xff) {
+    return xff.split(",")[0].trim();
+  }
+  return "unknown";
+}
+function createDefaultResponse(info) {
+  const retryAfter = Math.max(0, Math.ceil((info.reset - Date.now()) / 1e3));
+  return new Response("Rate limit exceeded", {
+    status: 429,
+    headers: {
+      "Content-Type": "text/plain",
+      "Retry-After": String(retryAfter)
+    }
+  });
+}
+async function checkSlidingWindow(store, key, limit, windowMs) {
+  const now = Date.now();
+  const currentWindowStart = Math.floor(now / windowMs) * windowMs;
+  const previousWindowStart = currentWindowStart - windowMs;
+  const previousKey = `${key}:${previousWindowStart}`;
+  const currentKey = `${key}:${currentWindowStart}`;
+  const current = await store.increment(currentKey);
+  let previousCount = 0;
+  if (store.get) {
+    const prev = await store.get(previousKey);
+    previousCount = prev?.count ?? 0;
+  }
+  const elapsedMs = now - currentWindowStart;
+  const weight = (windowMs - elapsedMs) / windowMs;
+  const estimatedCount = Math.floor(previousCount * weight) + current.count;
+  const remaining = Math.max(0, limit - estimatedCount);
+  const allowed = estimatedCount <= limit;
+  const reset = currentWindowStart + windowMs;
+  return {
+    allowed,
+    info: { limit, remaining, reset }
+  };
+}
+async function checkFixedWindow(store, key, limit, windowMs) {
+  const now = Date.now();
+  const windowStart = Math.floor(now / windowMs) * windowMs;
+  const windowKey = `${key}:${windowStart}`;
+  const { count, reset } = await store.increment(windowKey);
+  const remaining = Math.max(0, limit - count);
+  const allowed = count <= limit;
+  return {
+    allowed,
+    info: { limit, remaining, reset }
+  };
+}
+var rateLimiter = (options) => {
+  const opts = {
+    limit: 60,
+    windowMs: 6e4,
+    algorithm: "sliding-window",
+    store: void 0,
+    keyGenerator: getClientIP,
+    handler: void 0,
+    headers: "draft-6",
+    skip: void 0,
+    skipSuccessfulRequests: false,
+    skipFailedRequests: false,
+    onRateLimited: void 0,
+    ...options
+  };
+  const store = opts.store ?? (defaultStore ??= new MemoryStore());
+  let initialized = false;
+  return async function rateLimiter2(c, next) {
+    if (!initialized && store.init) {
+      await store.init(opts.windowMs);
+      initialized = true;
+    }
+    if (opts.skip) {
+      const shouldSkip = await opts.skip(c);
+      if (shouldSkip) {
+        return next();
+      }
+    }
+    const key = await opts.keyGenerator(c);
+    const limit = typeof opts.limit === "function" ? await opts.limit(c) : opts.limit;
+    const { allowed, info } = opts.algorithm === "sliding-window" ? await checkSlidingWindow(store, key, limit, opts.windowMs) : await checkFixedWindow(store, key, limit, opts.windowMs);
+    c.set("rateLimit", info);
+    setHeaders(c, info, opts.headers);
+    if (!allowed) {
+      if (opts.onRateLimited) {
+        await opts.onRateLimited(c, info);
+      }
+      if (opts.handler) {
+        return opts.handler(c, info);
+      }
+      return createDefaultResponse(info);
+    }
+    await next();
+    if (opts.skipSuccessfulRequests || opts.skipFailedRequests) {
+      const status = c.res.status;
+      const shouldDecrement = opts.skipSuccessfulRequests && status >= 200 && status < 300 || opts.skipFailedRequests && status >= 400;
+      if (shouldDecrement && store.decrement) {
+        const windowStart = Math.floor(Date.now() / opts.windowMs) * opts.windowMs;
+        const windowKey = `${key}:${windowStart}`;
+        await store.decrement(windowKey);
+      }
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryStore,
+  getClientIP,
+  rateLimiter
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @module\n * Rate Limit Middleware for Hono.\n */\n\nimport type { Context, Env, MiddlewareHandler } from \"hono\";\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Rate limit information for a single request\n */\nexport type RateLimitInfo = {\n  /** Maximum requests allowed in window */\n  limit: number;\n  /** Remaining requests in current window */\n  remaining: number;\n  /** Unix timestamp (ms) when window resets */\n  reset: number;\n};\n\n/**\n * Result from store increment operation\n */\nexport type StoreResult = {\n  /** Current request count in window */\n  count: number;\n  /** When the window resets (Unix timestamp ms) */\n  reset: number;\n};\n\n/**\n * Header format versions\n */\nexport type HeadersFormat =\n  | \"draft-6\" // X-RateLimit-* headers\n  | \"draft-7\" // RateLimit-* without structured fields\n  | false; // Disable headers\n\n/**\n * Rate limit algorithm\n */\nexport type Algorithm = \"fixed-window\" | \"sliding-window\";\n\n/**\n * Store interface for rate limit state\n */\nexport type RateLimitStore = {\n  /**\n   * Initialize store. Called once before first use.\n   */\n  init?: (windowMs: number) => void | Promise<void>;\n\n  /**\n   * Increment counter for key and return current state.\n   */\n  increment: (key: string) => StoreResult | Promise<StoreResult>;\n\n  /**\n   * Decrement counter for key.\n   */\n  decrement?: (key: string) => void | Promise<void>;\n\n  /**\n   * Reset a specific key.\n   */\n  resetKey: (key: string) => void | Promise<void>;\n\n  /**\n   * Get current state for key.\n   */\n  get?: (\n    key: string,\n  ) => StoreResult | Promise<StoreResult | undefined> | undefined;\n\n  /**\n   * Graceful shutdown.\n   */\n  shutdown?: () => void | Promise<void>;\n};\n\n/**\n * Options for rate limit middleware\n */\nexport type RateLimitOptions<E extends Env = Env> = {\n  /**\n   * Maximum requests allowed in the time window.\n   * @default 60\n   */\n  limit?: number | ((c: Context<E>) => number | Promise<number>);\n\n  /**\n   * Time window in milliseconds.\n   * @default 60000 (1 minute)\n   */\n  windowMs?: number;\n\n  /**\n   * Rate limiting algorithm.\n   * @default 'sliding-window'\n   */\n  algorithm?: Algorithm;\n\n  /**\n   * Storage backend for rate limit state.\n   * @default MemoryStore\n   */\n  store?: RateLimitStore;\n\n  /**\n   * Generate unique key for each client.\n   * @default IP address from headers\n   */\n  keyGenerator?: (c: Context<E>) => string | Promise<string>;\n\n  /**\n   * Handler called when rate limit is exceeded.\n   */\n  handler?: (\n    c: Context<E>,\n    info: RateLimitInfo,\n  ) => Response | Promise<Response>;\n\n  /**\n   * HTTP header format to use.\n   * @default 'draft-6'\n   */\n  headers?: HeadersFormat;\n\n  /**\n   * Skip rate limiting for certain requests.\n   */\n  skip?: (c: Context<E>) => boolean | Promise<boolean>;\n\n  /**\n   * Don't count successful (2xx) requests against limit.\n   * @default false\n   */\n  skipSuccessfulRequests?: boolean;\n\n  /**\n   * Don't count failed (4xx, 5xx) requests against limit.\n   * @default false\n   */\n  skipFailedRequests?: boolean;\n\n  /**\n   * Callback when a request is rate limited.\n   */\n  onRateLimited?: (c: Context<E>, info: RateLimitInfo) => void | Promise<void>;\n};\n\n// ============================================================================\n// Context Variable Type Extension\n// ============================================================================\n\ndeclare module \"hono\" {\n  interface ContextVariableMap {\n    rateLimit?: RateLimitInfo;\n  }\n}\n\n// ============================================================================\n// Memory Store\n// ============================================================================\n\ntype MemoryEntry = {\n  count: number;\n  reset: number;\n};\n\n/**\n * In-memory store for rate limiting.\n * Suitable for single-instance deployments.\n */\nexport class MemoryStore implements RateLimitStore {\n  private entries = new Map<string, MemoryEntry>();\n  private windowMs = 60_000;\n  private cleanupTimer?: ReturnType<typeof setInterval>;\n\n  init(windowMs: number): void {\n    this.windowMs = windowMs;\n\n    // Cleanup expired entries every minute\n    this.cleanupTimer = setInterval(() => {\n      const now = Date.now();\n      for (const [key, entry] of this.entries) {\n        if (entry.reset <= now) {\n          this.entries.delete(key);\n        }\n      }\n    }, 60_000);\n\n    // Don't keep process alive for cleanup\n    if (typeof this.cleanupTimer.unref === \"function\") {\n      this.cleanupTimer.unref();\n    }\n  }\n\n  increment(key: string): StoreResult {\n    const now = Date.now();\n    const existing = this.entries.get(key);\n\n    if (!existing || existing.reset <= now) {\n      // New window\n      const reset = now + this.windowMs;\n      this.entries.set(key, { count: 1, reset });\n      return { count: 1, reset };\n    }\n\n    // Increment existing\n    existing.count++;\n    return { count: existing.count, reset: existing.reset };\n  }\n\n  get(key: string): StoreResult | undefined {\n    const entry = this.entries.get(key);\n    if (!entry || entry.reset <= Date.now()) {\n      return undefined;\n    }\n    return { count: entry.count, reset: entry.reset };\n  }\n\n  decrement(key: string): void {\n    const entry = this.entries.get(key);\n    if (entry && entry.count > 0) {\n      entry.count--;\n    }\n  }\n\n  resetKey(key: string): void {\n    this.entries.delete(key);\n  }\n\n  shutdown(): void {\n    if (this.cleanupTimer) {\n      clearInterval(this.cleanupTimer);\n    }\n    this.entries.clear();\n  }\n}\n\n// Singleton default store\nlet defaultStore: MemoryStore | undefined;\n\n// ============================================================================\n// Header Generation\n// ============================================================================\n\nfunction setHeaders(\n  c: Context,\n  info: RateLimitInfo,\n  format: HeadersFormat,\n): void {\n  if (format === false) {\n    return;\n  }\n\n  const resetSeconds = Math.max(0, Math.ceil((info.reset - Date.now()) / 1000));\n\n  switch (format) {\n    case \"draft-7\":\n      c.header(\"RateLimit-Limit\", String(info.limit));\n      c.header(\"RateLimit-Remaining\", String(info.remaining));\n      c.header(\"RateLimit-Reset\", String(resetSeconds));\n      break;\n\n    case \"draft-6\":\n    default:\n      c.header(\"X-RateLimit-Limit\", String(info.limit));\n      c.header(\"X-RateLimit-Remaining\", String(info.remaining));\n      c.header(\"X-RateLimit-Reset\", String(Math.ceil(info.reset / 1000)));\n      break;\n  }\n}\n\n// ============================================================================\n// Default Key Generator\n// ============================================================================\n\nfunction getClientIP(c: Context): string {\n  // Platform-specific headers (most reliable)\n  const cfIP = c.req.header(\"cf-connecting-ip\");\n  if (cfIP) {\n    return cfIP;\n  }\n\n  const xRealIP = c.req.header(\"x-real-ip\");\n  if (xRealIP) {\n    return xRealIP;\n  }\n\n  // X-Forwarded-For - take first IP\n  const xff = c.req.header(\"x-forwarded-for\");\n  if (xff) {\n    return xff.split(\",\")[0].trim();\n  }\n\n  return \"unknown\";\n}\n\n// ============================================================================\n// Default Handler\n// ============================================================================\n\nfunction createDefaultResponse(info: RateLimitInfo): Response {\n  const retryAfter = Math.max(0, Math.ceil((info.reset - Date.now()) / 1000));\n\n  return new Response(\"Rate limit exceeded\", {\n    status: 429,\n    headers: {\n      \"Content-Type\": \"text/plain\",\n      \"Retry-After\": String(retryAfter),\n    },\n  });\n}\n\n// ============================================================================\n// Sliding Window Algorithm\n// ============================================================================\n\nasync function checkSlidingWindow(\n  store: RateLimitStore,\n  key: string,\n  limit: number,\n  windowMs: number,\n): Promise<{ allowed: boolean; info: RateLimitInfo }> {\n  const now = Date.now();\n  const currentWindowStart = Math.floor(now / windowMs) * windowMs;\n  const previousWindowStart = currentWindowStart - windowMs;\n\n  const previousKey = `${key}:${previousWindowStart}`;\n  const currentKey = `${key}:${currentWindowStart}`;\n\n  // Increment current window\n  const current = await store.increment(currentKey);\n\n  // Get previous window (may not exist)\n  let previousCount = 0;\n  if (store.get) {\n    const prev = await store.get(previousKey);\n    previousCount = prev?.count ?? 0;\n  }\n\n  // Cloudflare's weighted formula\n  const elapsedMs = now - currentWindowStart;\n  const weight = (windowMs - elapsedMs) / windowMs;\n  const estimatedCount = Math.floor(previousCount * weight) + current.count;\n\n  const remaining = Math.max(0, limit - estimatedCount);\n  const allowed = estimatedCount <= limit;\n  const reset = currentWindowStart + windowMs;\n\n  return {\n    allowed,\n    info: { limit, remaining, reset },\n  };\n}\n\n// ============================================================================\n// Fixed Window Algorithm\n// ============================================================================\n\nasync function checkFixedWindow(\n  store: RateLimitStore,\n  key: string,\n  limit: number,\n  windowMs: number,\n): Promise<{ allowed: boolean; info: RateLimitInfo }> {\n  const now = Date.now();\n  const windowStart = Math.floor(now / windowMs) * windowMs;\n  const windowKey = `${key}:${windowStart}`;\n\n  const { count, reset } = await store.increment(windowKey);\n\n  const remaining = Math.max(0, limit - count);\n  const allowed = count <= limit;\n\n  return {\n    allowed,\n    info: { limit, remaining, reset },\n  };\n}\n\n// ============================================================================\n// Main Middleware\n// ============================================================================\n\n/**\n * Rate Limit Middleware for Hono.\n *\n * @param {RateLimitOptions} [options] - Configuration options\n * @returns {MiddlewareHandler} Middleware handler\n *\n * @example\n * ```ts\n * import { Hono } from 'hono'\n * import { rateLimiter } from 'hono-rate-limit'\n *\n * const app = new Hono()\n *\n * // Basic usage - 60 requests per minute\n * app.use(rateLimiter())\n *\n * // Custom configuration\n * app.use('/api/*', rateLimiter({\n *   limit: 100,\n *   windowMs: 60 * 1000,\n * }))\n * ```\n */\nexport const rateLimiter = <E extends Env = Env>(\n  options?: RateLimitOptions<E>,\n): MiddlewareHandler<E> => {\n  // Merge with defaults\n  const opts = {\n    limit: 60 as number | ((c: Context<E>) => number | Promise<number>),\n    windowMs: 60_000,\n    algorithm: \"sliding-window\" as Algorithm,\n    store: undefined as RateLimitStore | undefined,\n    keyGenerator: getClientIP as (c: Context<E>) => string | Promise<string>,\n    handler: undefined as\n      | ((c: Context<E>, info: RateLimitInfo) => Response | Promise<Response>)\n      | undefined,\n    headers: \"draft-6\" as HeadersFormat,\n    skip: undefined as\n      | ((c: Context<E>) => boolean | Promise<boolean>)\n      | undefined,\n    skipSuccessfulRequests: false,\n    skipFailedRequests: false,\n    onRateLimited: undefined as\n      | ((c: Context<E>, info: RateLimitInfo) => void | Promise<void>)\n      | undefined,\n    ...options,\n  };\n\n  // Use default store if none provided\n  const store = opts.store ?? (defaultStore ??= new MemoryStore());\n\n  // Track initialization\n  let initialized = false;\n\n  return async function rateLimiter(c, next) {\n    // Initialize store on first request\n    if (!initialized && store.init) {\n      await store.init(opts.windowMs);\n      initialized = true;\n    }\n\n    // Check if should skip\n    if (opts.skip) {\n      const shouldSkip = await opts.skip(c);\n      if (shouldSkip) {\n        return next();\n      }\n    }\n\n    // Generate key\n    const key = await opts.keyGenerator(c);\n\n    // Get limit (may be dynamic)\n    const limit =\n      typeof opts.limit === \"function\" ? await opts.limit(c) : opts.limit;\n\n    // Check rate limit\n    const { allowed, info } =\n      opts.algorithm === \"sliding-window\"\n        ? await checkSlidingWindow(store, key, limit, opts.windowMs)\n        : await checkFixedWindow(store, key, limit, opts.windowMs);\n\n    // Set context variable for downstream middleware\n    c.set(\"rateLimit\", info);\n\n    // Set headers\n    setHeaders(c, info, opts.headers);\n\n    // Handle rate limited\n    if (!allowed) {\n      // Fire callback\n      if (opts.onRateLimited) {\n        await opts.onRateLimited(c, info);\n      }\n\n      // Custom handler or default\n      if (opts.handler) {\n        return opts.handler(c, info);\n      }\n      return createDefaultResponse(info);\n    }\n\n    // Continue\n    await next();\n\n    // Handle skip options after response\n    if (opts.skipSuccessfulRequests || opts.skipFailedRequests) {\n      const status = c.res.status;\n      const shouldDecrement =\n        (opts.skipSuccessfulRequests && status >= 200 && status < 300) ||\n        (opts.skipFailedRequests && status >= 400);\n\n      if (shouldDecrement && store.decrement) {\n        const windowStart =\n          Math.floor(Date.now() / opts.windowMs) * opts.windowMs;\n        const windowKey = `${key}:${windowStart}`;\n        await store.decrement(windowKey);\n      }\n    }\n  };\n};\n\n// ============================================================================\n// Exports\n// ============================================================================\n\nexport { getClientIP };\n"],"mappings":"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","names":["rateLimiter"]}

package/dist/index.d.cts

@@ -0,0 +1,168 @@
+import { Env, Context, MiddlewareHandler } from 'hono';
+
+/**
+ * @module
+ * Rate Limit Middleware for Hono.
+ */
+
+/**
+ * Rate limit information for a single request
+ */
+type RateLimitInfo = {
+    /** Maximum requests allowed in window */
+    limit: number;
+    /** Remaining requests in current window */
+    remaining: number;
+    /** Unix timestamp (ms) when window resets */
+    reset: number;
+};
+/**
+ * Result from store increment operation
+ */
+type StoreResult = {
+    /** Current request count in window */
+    count: number;
+    /** When the window resets (Unix timestamp ms) */
+    reset: number;
+};
+/**
+ * Header format versions
+ */
+type HeadersFormat = "draft-6" | "draft-7" | false;
+/**
+ * Rate limit algorithm
+ */
+type Algorithm = "fixed-window" | "sliding-window";
+/**
+ * Store interface for rate limit state
+ */
+type RateLimitStore = {
+    /**
+     * Initialize store. Called once before first use.
+     */
+    init?: (windowMs: number) => void | Promise<void>;
+    /**
+     * Increment counter for key and return current state.
+     */
+    increment: (key: string) => StoreResult | Promise<StoreResult>;
+    /**
+     * Decrement counter for key.
+     */
+    decrement?: (key: string) => void | Promise<void>;
+    /**
+     * Reset a specific key.
+     */
+    resetKey: (key: string) => void | Promise<void>;
+    /**
+     * Get current state for key.
+     */
+    get?: (key: string) => StoreResult | Promise<StoreResult | undefined> | undefined;
+    /**
+     * Graceful shutdown.
+     */
+    shutdown?: () => void | Promise<void>;
+};
+/**
+ * Options for rate limit middleware
+ */
+type RateLimitOptions<E extends Env = Env> = {
+    /**
+     * Maximum requests allowed in the time window.
+     * @default 60
+     */
+    limit?: number | ((c: Context<E>) => number | Promise<number>);
+    /**
+     * Time window in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Rate limiting algorithm.
+     * @default 'sliding-window'
+     */
+    algorithm?: Algorithm;
+    /**
+     * Storage backend for rate limit state.
+     * @default MemoryStore
+     */
+    store?: RateLimitStore;
+    /**
+     * Generate unique key for each client.
+     * @default IP address from headers
+     */
+    keyGenerator?: (c: Context<E>) => string | Promise<string>;
+    /**
+     * Handler called when rate limit is exceeded.
+     */
+    handler?: (c: Context<E>, info: RateLimitInfo) => Response | Promise<Response>;
+    /**
+     * HTTP header format to use.
+     * @default 'draft-6'
+     */
+    headers?: HeadersFormat;
+    /**
+     * Skip rate limiting for certain requests.
+     */
+    skip?: (c: Context<E>) => boolean | Promise<boolean>;
+    /**
+     * Don't count successful (2xx) requests against limit.
+     * @default false
+     */
+    skipSuccessfulRequests?: boolean;
+    /**
+     * Don't count failed (4xx, 5xx) requests against limit.
+     * @default false
+     */
+    skipFailedRequests?: boolean;
+    /**
+     * Callback when a request is rate limited.
+     */
+    onRateLimited?: (c: Context<E>, info: RateLimitInfo) => void | Promise<void>;
+};
+declare module "hono" {
+    interface ContextVariableMap {
+        rateLimit?: RateLimitInfo;
+    }
+}
+/**
+ * In-memory store for rate limiting.
+ * Suitable for single-instance deployments.
+ */
+declare class MemoryStore implements RateLimitStore {
+    private entries;
+    private windowMs;
+    private cleanupTimer?;
+    init(windowMs: number): void;
+    increment(key: string): StoreResult;
+    get(key: string): StoreResult | undefined;
+    decrement(key: string): void;
+    resetKey(key: string): void;
+    shutdown(): void;
+}
+declare function getClientIP(c: Context): string;
+/**
+ * Rate Limit Middleware for Hono.
+ *
+ * @param {RateLimitOptions} [options] - Configuration options
+ * @returns {MiddlewareHandler} Middleware handler
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono'
+ * import { rateLimiter } from 'hono-rate-limit'
+ *
+ * const app = new Hono()
+ *
+ * // Basic usage - 60 requests per minute
+ * app.use(rateLimiter())
+ *
+ * // Custom configuration
+ * app.use('/api/*', rateLimiter({
+ *   limit: 100,
+ *   windowMs: 60 * 1000,
+ * }))
+ * ```
+ */
+declare const rateLimiter: <E extends Env = Env>(options?: RateLimitOptions<E>) => MiddlewareHandler<E>;
+
+export { type Algorithm, type HeadersFormat, MemoryStore, type RateLimitInfo, type RateLimitOptions, type RateLimitStore, type StoreResult, getClientIP, rateLimiter };