@davaux/rate-limit 0.8.0

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- pka-generated -->
+# @davaux/rate-limit
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.395Z
+
+## Overview
+
+Rate limiting middleware for Davaux
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+
+## Project Structure
+
+```
+├── CLAUDE.md
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (2)
+- `CLAUDE.md`
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@types/node, davaux, typescript
+
+
+
+
+
+
+
+
+
+## Exported Symbols
+
+**`src/index.ts`**
+`MemoryStore`, `rateLimit`, `RateLimitResult`, `RateLimitStore`, `RateLimitOptions`
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+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,63 @@
+# @davaux/rate-limit
+
+Rate limiting middleware for Davaux.
+
+## Installation
+
+```bash
+npm install @davaux/rate-limit
+```
+
+## Setup
+
+```ts
+// davaux.config.ts
+import { defineConfig } from 'davaux/config'
+import { rateLimit } from '@davaux/rate-limit'
+
+export default defineConfig({
+  middleware: [
+    rateLimit({ windowMs: 60_000, max: 100 }),
+  ],
+})
+```
+
+Or scope it to specific routes via `_middleware.ts`:
+
+```ts
+// src/routes/api/_middleware.ts
+import { rateLimit } from '@davaux/rate-limit'
+export default rateLimit({ windowMs: 60_000, max: 20 })
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `windowMs` | `number` | — | Time window in milliseconds (required) |
+| `max` | `number` | — | Maximum requests per window per key (required) |
+| `keyFn` | `(ctx) => string` | Client IP | Function to derive the rate-limit key |
+| `message` | `string` | `'Too Many Requests'` | Body of the 429 response |
+| `store` | `RateLimitStore` | `MemoryStore` | Backing store for counters |
+| `headers` | `boolean` | `true` | Send `RateLimit-*` headers on every response |
+| `trustProxy` | `boolean` | `false` | Use `X-Forwarded-For` as the key. Only enable behind a trusted reverse proxy |
+
+## Custom store
+
+Implement `RateLimitStore` to use Redis, Valkey, or any other distributed backend:
+
+```ts
+import type { RateLimitStore, RateLimitResult } from '@davaux/rate-limit'
+
+class RedisStore implements RateLimitStore {
+  async increment(key: string, windowMs: number): Promise<RateLimitResult> {
+    // ...
+  }
+}
+
+rateLimit({ windowMs: 60_000, max: 100, store: new RedisStore() })
+```
+
+## Documentation
+
+[davaux.codeberg.page/docs/rate-limit](https://davaux.codeberg.page/docs/rate-limit)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@davaux/rate-limit",
+  "version": "0.8.0",
+  "description": "Rate limiting middleware for Davaux",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "davaux": ">=0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+import type { MiddlewareFn, RequestContext } from 'davaux'
+
+// ─── Store interface ───────────────────────────────────────────────────────────
+
+export interface RateLimitResult {
+  /** Total hits in the current window. */
+  count: number
+  /** Unix timestamp (ms) when the current window resets. */
+  resetAt: number
+}
+
+/**
+ * Backing store for rate limit counters. The default `MemoryStore` works for
+ * single-process deployments. Implement this interface and pass it via
+ * `options.store` to use Redis, Valkey, or any other backend.
+ */
+export interface RateLimitStore {
+  increment(key: string, windowMs: number): Promise<RateLimitResult>
+}
+
+// ─── In-memory store ──────────────────────────────────────────────────────────
+
+/** In-memory rate-limit counter store. Suitable for single-process deployments. */
+export class MemoryStore implements RateLimitStore {
+  private readonly hits = new Map<string, RateLimitResult>()
+
+  async increment(key: string, windowMs: number): Promise<RateLimitResult> {
+    const now = Date.now()
+    const entry = this.hits.get(key)
+
+    if (!entry || now >= entry.resetAt) {
+      const result: RateLimitResult = { count: 1, resetAt: now + windowMs }
+      this.hits.set(key, result)
+      return result
+    }
+
+    entry.count++
+    return { count: entry.count, resetAt: entry.resetAt }
+  }
+}
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+export interface RateLimitOptions {
+  /** Time window in milliseconds. */
+  windowMs: number
+  /** Maximum number of requests allowed per window per key. */
+  max: number
+  /**
+   * Function that derives the rate-limit key from the request context.
+   * Default: the client's IP address (`req.socket.remoteAddress`).
+   */
+  keyFn?: (ctx: RequestContext) => string
+  /**
+   * Body of the 429 response.
+   * Default: `'Too Many Requests'`
+   */
+  message?: string
+  /**
+   * Backing store. Default: `MemoryStore` (suitable for single-process apps).
+   * Pass a custom implementation for Redis or other distributed stores.
+   */
+  store?: RateLimitStore
+  /**
+   * When `true`, rate-limit headers are sent on every response, not just 429s.
+   * Default: `true`
+   */
+  headers?: boolean
+  /**
+   * When `true`, the leftmost IP in `X-Forwarded-For` is used as the rate-limit
+   * key instead of `req.socket.remoteAddress`. Only enable when the app runs
+   * behind a trusted reverse proxy — clients can spoof this header otherwise.
+   * Default: `false`
+   */
+  trustProxy?: boolean
+}
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+/**
+ * Rate-limiting middleware. Counts requests per key within a rolling time
+ * window and returns `429 Too Many Requests` when the limit is exceeded.
+ * Standard `RateLimit-*` headers are sent on every response by default.
+ *
+ * @example
+ * import { rateLimit } from '@davaux/rate-limit'
+ * export default rateLimit({ windowMs: 60_000, max: 100 })
+ */
+export function rateLimit(options: RateLimitOptions): MiddlewareFn {
+  const store = options.store ?? new MemoryStore()
+  const keyFn = options.keyFn ?? ((ctx) => defaultKey(ctx, options.trustProxy))
+  const message = options.message ?? 'Too Many Requests'
+  const sendHeaders = options.headers !== false
+
+  return async (ctx, next) => {
+    const key = keyFn(ctx)
+    const { count, resetAt } = await store.increment(key, options.windowMs)
+    const remaining = Math.max(0, options.max - count)
+    const resetSecs = Math.ceil((resetAt - Date.now()) / 1000)
+
+    if (sendHeaders) {
+      ctx.res.setHeader('RateLimit-Limit', String(options.max))
+      ctx.res.setHeader('RateLimit-Remaining', String(remaining))
+      ctx.res.setHeader('RateLimit-Reset', String(resetSecs))
+    }
+
+    if (count > options.max) {
+      ctx.res.setHeader('Retry-After', String(resetSecs))
+      ctx.res.writeHead(429, { 'Content-Type': 'text/plain; charset=utf-8' })
+      ctx.res.end(message)
+      return
+    }
+
+    await next()
+  }
+}
+
+function defaultKey(ctx: RequestContext, trustProxy?: boolean): string {
+  if (trustProxy) {
+    const xff = ctx.req.headers['x-forwarded-for'] as string | undefined
+    if (xff) return xff.split(',')[0].trim()
+  }
+  return ctx.req.socket.remoteAddress ?? 'unknown'
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}