@mantiq/core 0.2.1 → 0.4.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/core",
-  "version": "0.2.1",
+  "version": "0.4.0-rc.1",
   "description": "Service container, router, middleware, HTTP kernel, config, and exception handler",
   "type": "module",
   "license": "MIT",

package/src/application/Application.ts

@@ -30,7 +30,7 @@ export class Application extends ContainerImpl {
   private constructor(private readonly basePath: string = process.cwd()) {
     super()
     // Register the application itself so it can be resolved from the container
-    this.instance(Application, this)
+    this.instance(Application as any, this)
   }
 
   // ── Singleton access ──────────────────────────────────────────────────────
@@ -191,7 +191,7 @@ export class Application extends ContainerImpl {
    * Override make() to handle deferred provider loading.
    * If a binding isn't found in the container, check deferred providers.
    */
-  make<T>(abstract: Bindable<T>): T {
+  override make<T>(abstract: Bindable<T>): T {
     try {
       return super.make(abstract)
     } catch (err) {

package/src/contracts/Router.ts

@@ -19,14 +19,14 @@ export interface RouteMatch {
   action: RouteAction
   params: Record<string, any>
   middleware: string[]
-  routeName?: string
+  routeName?: string | undefined
 }
 
 export interface RouteDefinition {
   method: HttpMethod | HttpMethod[]
   path: string
   action: RouteAction
-  name?: string
+  name?: string | undefined
   middleware: string[]
   wheres: Record<string, RegExp>
 }

package/src/discovery/Discoverer.ts

@@ -0,0 +1,200 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+
+/**
+ * Auto-discovers application classes by scanning conventional directories.
+ *
+ * In development: scans the filesystem and rebuilds the manifest.
+ * In production: reads a cached manifest from bootstrap/manifest.json.
+ *
+ * Usage:
+ *   const discoverer = new Discoverer(app.basePath)
+ *   const manifest = await discoverer.build()  // scan + cache
+ *   const manifest = discoverer.cached()        // read cache only
+ */
+
+export interface DiscoveryManifest {
+  providers: string[]
+  commands: string[]
+  routes: string[]
+  models: string[]
+  policies: string[]
+  middleware: string[]
+  observers: string[]
+  listeners: string[]
+  jobs: string[]
+  timestamp: number
+}
+
+const EMPTY_MANIFEST: DiscoveryManifest = {
+  providers: [],
+  commands: [],
+  routes: [],
+  models: [],
+  policies: [],
+  middleware: [],
+  observers: [],
+  listeners: [],
+  jobs: [],
+  timestamp: 0,
+}
+
+/** Directories to scan, relative to basePath. */
+const DISCOVERY_MAP: Array<{ key: keyof DiscoveryManifest; dir: string; pattern: string }> = [
+  { key: 'providers',  dir: 'app/Providers',            pattern: '*ServiceProvider.ts' },
+  { key: 'commands',   dir: 'app/Console/Commands',     pattern: '*Command.ts' },
+  { key: 'routes',     dir: 'routes',                   pattern: '*.ts' },
+  { key: 'models',     dir: 'app/Models',               pattern: '*.ts' },
+  { key: 'policies',   dir: 'app/Policies',             pattern: '*Policy.ts' },
+  { key: 'middleware',  dir: 'app/Http/Middleware',      pattern: '*.ts' },
+  { key: 'observers',  dir: 'app/Observers',            pattern: '*Observer.ts' },
+  { key: 'listeners',  dir: 'app/Listeners',            pattern: '*Listener.ts' },
+  { key: 'jobs',       dir: 'app/Jobs',                 pattern: '*.ts' },
+]
+
+export class Discoverer {
+  private manifestPath: string
+
+  constructor(private basePath: string) {
+    this.manifestPath = join(basePath, 'bootstrap', 'manifest.json')
+  }
+
+  /**
+   * Scan all directories and build a fresh manifest.
+   * Writes to bootstrap/manifest.json for caching.
+   */
+  async build(): Promise<DiscoveryManifest> {
+    const manifest: DiscoveryManifest = { ...EMPTY_MANIFEST, timestamp: Date.now() }
+
+    for (const { key, dir, pattern } of DISCOVERY_MAP) {
+      if (key === 'timestamp') continue
+      const fullDir = join(this.basePath, dir)
+      const files = await this.scanDirectory(fullDir, pattern)
+      ;(manifest[key] as string[]) = files.map((f) => join(dir, f))
+    }
+
+    // Write cache
+    this.writeManifest(manifest)
+    return manifest
+  }
+
+  /**
+   * Read the cached manifest. Returns null if no cache exists.
+   */
+  cached(): DiscoveryManifest | null {
+    if (!existsSync(this.manifestPath)) return null
+    try {
+      const raw = readFileSync(this.manifestPath, 'utf-8')
+      return JSON.parse(raw) as DiscoveryManifest
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Get the manifest — cached in production, fresh in development.
+   */
+  async resolve(isDev = true): Promise<DiscoveryManifest> {
+    if (!isDev) {
+      const cached = this.cached()
+      if (cached) return cached
+    }
+    return this.build()
+  }
+
+  /**
+   * Load and instantiate all discovered service providers.
+   * Returns provider instances ready for registration.
+   */
+  async loadProviders(manifest: DiscoveryManifest): Promise<any[]> {
+    const providers: any[] = []
+    for (const file of manifest.providers) {
+      const fullPath = join(this.basePath, file)
+      try {
+        const mod = await import(fullPath)
+        const ProviderClass = this.findExport(mod, (v) =>
+          typeof v === 'function' && v.prototype?.register && v.prototype?.boot
+        )
+        if (ProviderClass) providers.push(ProviderClass)
+      } catch {
+        // Skip unloadable providers
+      }
+    }
+    return providers
+  }
+
+  /**
+   * Load and register all discovered route files.
+   * Each route file should export a default function: (router) => void
+   */
+  async loadRoutes(manifest: DiscoveryManifest, router: any): Promise<void> {
+    for (const file of manifest.routes) {
+      const fullPath = join(this.basePath, file)
+      try {
+        const mod = await import(fullPath)
+        if (typeof mod.default === 'function') {
+          mod.default(router)
+        }
+      } catch {
+        // Skip unloadable routes
+      }
+    }
+  }
+
+  /**
+   * Load all discovered command classes for CLI kernel.
+   */
+  async loadCommands(manifest: DiscoveryManifest): Promise<any[]> {
+    const commands: any[] = []
+    for (const file of manifest.commands) {
+      const fullPath = join(this.basePath, file)
+      try {
+        const mod = await import(fullPath)
+        for (const exported of Object.values(mod)) {
+          if (typeof exported !== 'function') continue
+          try {
+            const instance = new (exported as any)()
+            if (instance.name && typeof instance.handle === 'function') {
+              commands.push(instance)
+            }
+          } catch {
+            // Not a command
+          }
+        }
+      } catch {
+        // Skip
+      }
+    }
+    return commands
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private async scanDirectory(dir: string, pattern: string): Promise<string[]> {
+    const files: string[] = []
+    try {
+      const glob = new Bun.Glob(pattern)
+      for await (const file of glob.scan({ cwd: dir, absolute: false })) {
+        // Skip dotfiles and test files
+        if (file.startsWith('.') || file.includes('.test.') || file.includes('.spec.')) continue
+        files.push(file)
+      }
+    } catch {
+      // Directory doesn't exist
+    }
+    return files.sort()
+  }
+
+  private writeManifest(manifest: DiscoveryManifest): void {
+    const dir = dirname(this.manifestPath)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    writeFileSync(this.manifestPath, JSON.stringify(manifest, null, 2))
+  }
+
+  private findExport(mod: any, predicate: (v: any) => boolean): any {
+    for (const exported of Object.values(mod)) {
+      if (predicate(exported)) return exported
+    }
+    return null
+  }
+}

package/src/exceptions/Handler.ts

@@ -54,10 +54,7 @@ export class DefaultExceptionHandler implements ExceptionHandler {
       return MantiqResponse.redirect((err as any).redirectTo)
     }
 
-    if (debug) {
-      return MantiqResponse.html(renderDevErrorPage(request, err), err.statusCode)
-    }
-
+    // API routes always get JSON — even in debug mode
     if (request.expectsJson()) {
       const body: Record<string, any> = {
         error: { message: err.message, status: err.statusCode },
@@ -65,9 +62,16 @@ export class DefaultExceptionHandler implements ExceptionHandler {
       if (err instanceof ValidationError) {
         body['error']['errors'] = err.errors
       }
+      if (debug && err.stack) {
+        body['error']['trace'] = err.stack.split('\n').map((l: string) => l.trim())
+      }
       return MantiqResponse.json(body, err.statusCode, err.headers)
     }
 
+    if (debug) {
+      return MantiqResponse.html(renderDevErrorPage(request, err), err.statusCode)
+    }
+
     return MantiqResponse.html(
       this.genericHtmlPage(err.statusCode, err.message),
       err.statusCode,
@@ -79,15 +83,18 @@ export class DefaultExceptionHandler implements ExceptionHandler {
     err: Error,
     debug: boolean,
   ): Response {
-    if (debug) {
-      return MantiqResponse.html(renderDevErrorPage(request, err), 500)
+    // API routes always get JSON — even in debug mode
+    if (request.expectsJson()) {
+      const body: Record<string, any> = { error: { message: 'Internal Server Error', status: 500 } }
+      if (debug && err.stack) {
+        body['error']['message'] = err.message
+        body['error']['trace'] = err.stack.split('\n').map((l: string) => l.trim())
+      }
+      return MantiqResponse.json(body, 500)
     }
 
-    if (request.expectsJson()) {
-      return MantiqResponse.json(
-        { error: { message: 'Internal Server Error', status: 500 } },
-        500,
-      )
+    if (debug) {
+      return MantiqResponse.html(renderDevErrorPage(request, err), 500)
     }
 
     return MantiqResponse.html(this.genericHtmlPage(500, 'Internal Server Error'), 500)

package/src/http/Kernel.ts

@@ -2,6 +2,7 @@ import type { Container, Constructor } from '../contracts/Container.ts'
 import type { ExceptionHandler } from '../contracts/ExceptionHandler.ts'
 import type { Middleware } from '../contracts/Middleware.ts'
 import type { Router, RouteMatch } from '../contracts/Router.ts'
+import type { MantiqRequest as MantiqRequestContract } from '../contracts/Request.ts'
 import { MantiqRequest } from './Request.ts'
 import { MantiqResponse } from './Response.ts'
 import { Pipeline } from '../middleware/Pipeline.ts'
@@ -90,7 +91,7 @@ export class HttpKernel {
   /**
    * Main entry point. Passed to Bun.serve() as the fetch handler.
    */
-  async handle(bunRequest: Request, server: Server): Promise<Response> {
+  async handle(bunRequest: Request, server: Bun.Server<any>): Promise<Response> {
     // WebSocket upgrade
     if (bunRequest.headers.get('upgrade')?.toLowerCase() === 'websocket') {
       return this.wsKernel.handleUpgrade(bunRequest, server)
@@ -145,7 +146,7 @@ export class HttpKernel {
           port,
           hostname,
           fetch: (req, server) => this.handle(req, server),
-          websocket: this.wsKernel.getBunHandlers(),
+          websocket: this.wsKernel.getBunHandlers() as Bun.WebSocketHandler<any>,
         })
 
         const display = hostname === '0.0.0.0' ? 'localhost' : hostname
@@ -172,7 +173,7 @@ export class HttpKernel {
    * Call the route action (controller method or closure).
    * Converts the return value to a Response.
    */
-  private async callAction(match: RouteMatch, request: MantiqRequest): Promise<Response> {
+  private async callAction(match: RouteMatch, request: MantiqRequestContract): Promise<Response> {
     const action = match.action
 
     let result: any

package/src/http/Request.ts

@@ -133,6 +133,8 @@ export class MantiqRequest implements MantiqRequestContract {
   }
 
   expectsJson(): boolean {
+    // Routes under /api/ always expect JSON responses
+    if (this.path().startsWith('/api/') || this.path() === '/api') return true
     const accept = this.header('accept') ?? ''
     return accept.includes('application/json') || accept.includes('text/json')
   }
@@ -226,7 +228,7 @@ export class MantiqRequest implements MantiqRequestContract {
 
     try {
       if (contentType.includes('application/json')) {
-        this.parsedBody = await this.bunRequest.clone().json()
+        this.parsedBody = await this.bunRequest.clone().json() as Record<string, any>
       } else if (contentType.includes('application/x-www-form-urlencoded')) {
         const text = await this.bunRequest.clone().text()
         this.parsedBody = Object.fromEntries(new URLSearchParams(text).entries())

package/src/index.ts

@@ -53,9 +53,14 @@ export { TrimStringsMiddleware } from './middleware/TrimStrings.ts'
 export { StartSession } from './middleware/StartSession.ts'
 export { EncryptCookies } from './middleware/EncryptCookies.ts'
 export { VerifyCsrfToken } from './middleware/VerifyCsrfToken.ts'
+export { RateLimiter, MemoryStore } from './rateLimit/RateLimiter.ts'
+export type { RateLimitConfig, RateLimitStore, LimiterResolver } from './rateLimit/RateLimiter.ts'
+export { ThrottleRequests, getDefaultRateLimiter, setDefaultRateLimiter } from './rateLimit/ThrottleRequests.ts'
 export { WebSocketKernel } from './websocket/WebSocketKernel.ts'
 export { DefaultExceptionHandler } from './exceptions/Handler.ts'
 export { CoreServiceProvider } from './providers/CoreServiceProvider.ts'
+export { Discoverer } from './discovery/Discoverer.ts'
+export type { DiscoveryManifest } from './discovery/Discoverer.ts'
 
 // ── Encryption ────────────────────────────────────────────────────────────────
 export { AesEncrypter } from './encryption/Encrypter.ts'

package/src/macroable/Macroable.ts

@@ -48,7 +48,7 @@ export interface MacroableInstance {
  */
 export function Macroable<T extends Constructor>(Base: T): T & MacroableStatic {
   class MacroableClass extends (Base as Constructor) {
-    private static _macros = new Map<string, Function>()
+    static _macros = new Map<string, Function>()
 
     static macro(name: string, fn: Function): void {
       this._ensureOwnMacros()

package/src/providers/CoreServiceProvider.ts

@@ -9,6 +9,7 @@ import { TrimStringsMiddleware } from '../middleware/TrimStrings.ts'
 import { StartSession } from '../middleware/StartSession.ts'
 import { EncryptCookies } from '../middleware/EncryptCookies.ts'
 import { VerifyCsrfToken } from '../middleware/VerifyCsrfToken.ts'
+import { ThrottleRequests } from '../rateLimit/ThrottleRequests.ts'
 import { ROUTER } from '../helpers/route.ts'
 import { ENCRYPTER } from '../helpers/encrypt.ts'
 import { AesEncrypter } from '../encryption/Encrypter.ts'
@@ -77,6 +78,9 @@ export class CoreServiceProvider extends ServiceProvider {
     this.app.bind(EncryptCookies, (c) => new EncryptCookies(c.make<AesEncrypter>(ENCRYPTER)))
     this.app.bind(VerifyCsrfToken, (c) => new VerifyCsrfToken(c.make<AesEncrypter>(ENCRYPTER)))
 
+    // Rate limiting — zero-config, uses shared in-memory store
+    this.app.singleton(ThrottleRequests, () => new ThrottleRequests())
+
     // HTTP kernel — singleton, depends on Router + ExceptionHandler + WsKernel
     this.app.singleton(HttpKernel, (c) => {
       const router = c.make(RouterImpl)
@@ -93,5 +97,9 @@ export class CoreServiceProvider extends ServiceProvider {
       const encrypter = await AesEncrypter.fromAppKey(appKey)
       this.app.instance(ENCRYPTER, encrypter)
     }
+
+    // ── Auto-register middleware aliases on HttpKernel ─────────────────────
+    const kernel = this.app.make(HttpKernel)
+    kernel.registerMiddleware('throttle', ThrottleRequests)
   }
 }

package/src/rateLimit/RateLimiter.ts

@@ -0,0 +1,146 @@
+/**
+ * Rate limiter — tracks request counts per key within time windows.
+ *
+ * Supports named limiters with custom resolvers, and pluggable stores
+ * (memory by default, cache/Redis when available).
+ *
+ * @example
+ * const limiter = new RateLimiter()
+ *
+ * // Define a named limiter
+ * limiter.for('api', (request) => ({
+ *   key: request.ip(),
+ *   maxAttempts: 60,
+ *   decayMinutes: 1,
+ * }))
+ *
+ * // Or with multiple limits
+ * limiter.for('uploads', (request) => [
+ *   { key: request.ip(), maxAttempts: 10, decayMinutes: 1 },
+ *   { key: request.user()?.id ?? request.ip(), maxAttempts: 100, decayMinutes: 60 },
+ * ])
+ */
+
+export interface RateLimitConfig {
+  key: string
+  maxAttempts: number
+  decayMinutes: number
+  responseCallback?: (request: any, headers: Record<string, string>) => Response | void
+}
+
+export interface RateLimitStore {
+  /** Get current hit count for key. */
+  get(key: string): Promise<number>
+  /** Increment hit count. Returns new count. */
+  increment(key: string, decaySeconds: number): Promise<number>
+  /** Get remaining seconds until the key resets. */
+  availableIn(key: string): Promise<number>
+  /** Reset a key. */
+  clear(key: string): Promise<void>
+}
+
+export type LimiterResolver = (request: any) => RateLimitConfig | RateLimitConfig[]
+
+export class RateLimiter {
+  private limiters = new Map<string, LimiterResolver>()
+  private store: RateLimitStore
+
+  constructor(store?: RateLimitStore) {
+    this.store = store ?? new MemoryStore()
+  }
+
+  /** Define a named rate limiter. */
+  for(name: string, resolver: LimiterResolver): this {
+    this.limiters.set(name, resolver)
+    return this
+  }
+
+  /** Get a named limiter resolver. */
+  limiter(name: string): LimiterResolver | undefined {
+    return this.limiters.get(name)
+  }
+
+  /** Check if a key has too many attempts. */
+  async tooManyAttempts(key: string, maxAttempts: number): Promise<boolean> {
+    const attempts = await this.store.get(key)
+    return attempts >= maxAttempts
+  }
+
+  /** Record a hit for a key. Returns the new count. */
+  async hit(key: string, decaySeconds: number): Promise<number> {
+    return this.store.increment(key, decaySeconds)
+  }
+
+  /** Get current attempt count. */
+  async attempts(key: string): Promise<number> {
+    return this.store.get(key)
+  }
+
+  /** Get remaining attempts. */
+  async remaining(key: string, maxAttempts: number): Promise<number> {
+    const current = await this.store.get(key)
+    return Math.max(0, maxAttempts - current)
+  }
+
+  /** Get seconds until the rate limit resets. */
+  async availableIn(key: string): Promise<number> {
+    return this.store.availableIn(key)
+  }
+
+  /** Reset a key's attempt count. */
+  async clear(key: string): Promise<void> {
+    return this.store.clear(key)
+  }
+
+  /** Set the backing store (memory, cache, redis). */
+  setStore(store: RateLimitStore): void {
+    this.store = store
+  }
+}
+
+// ── Memory Store (default) ───────────────────────────────────────────────────
+
+interface MemoryEntry {
+  count: number
+  expiresAt: number // unix ms
+}
+
+export class MemoryStore implements RateLimitStore {
+  private entries = new Map<string, MemoryEntry>()
+
+  async get(key: string): Promise<number> {
+    const entry = this.entries.get(key)
+    if (!entry) return 0
+    if (Date.now() > entry.expiresAt) {
+      this.entries.delete(key)
+      return 0
+    }
+    return entry.count
+  }
+
+  async increment(key: string, decaySeconds: number): Promise<number> {
+    const existing = this.entries.get(key)
+    const now = Date.now()
+
+    if (existing && now <= existing.expiresAt) {
+      existing.count++
+      return existing.count
+    }
+
+    // New window
+    const entry: MemoryEntry = { count: 1, expiresAt: now + decaySeconds * 1000 }
+    this.entries.set(key, entry)
+    return 1
+  }
+
+  async availableIn(key: string): Promise<number> {
+    const entry = this.entries.get(key)
+    if (!entry) return 0
+    const remaining = Math.ceil((entry.expiresAt - Date.now()) / 1000)
+    return Math.max(0, remaining)
+  }
+
+  async clear(key: string): Promise<void> {
+    this.entries.delete(key)
+  }
+}

package/src/rateLimit/ThrottleRequests.ts

@@ -0,0 +1,154 @@
+import type { MantiqRequest } from '../contracts/Request.ts'
+import type { Middleware } from '../contracts/Middleware.ts'
+import { HttpError } from '../errors/HttpError.ts'
+import { RateLimiter } from './RateLimiter.ts'
+import type { RateLimitConfig } from './RateLimiter.ts'
+
+/** Shared default RateLimiter instance. */
+let _defaultLimiter: RateLimiter | null = null
+export function getDefaultRateLimiter(): RateLimiter {
+  if (!_defaultLimiter) _defaultLimiter = new RateLimiter()
+  return _defaultLimiter
+}
+export function setDefaultRateLimiter(limiter: RateLimiter): void {
+  _defaultLimiter = limiter
+}
+
+/**
+ * Middleware that throttles requests using the RateLimiter.
+ *
+ * Usage with named limiter:
+ *   router.get('/api/data', handler).middleware('throttle:api')
+ *
+ * Usage with inline limits:
+ *   router.get('/api/data', handler).middleware('throttle:60,1')
+ *   // 60 requests per 1 minute, keyed by IP
+ *
+ * Response headers:
+ *   X-RateLimit-Limit: 60
+ *   X-RateLimit-Remaining: 45
+ *   Retry-After: 30 (only when rate limited)
+ */
+export class ThrottleRequests implements Middleware {
+  private params: string[] = []
+  private rateLimiter: RateLimiter = getDefaultRateLimiter()
+
+  constructor() {}
+
+  /** Use a custom RateLimiter instead of the default shared instance. */
+  useRateLimiter(limiter: RateLimiter): this {
+    this.rateLimiter = limiter
+    return this
+  }
+
+  setParameters(params: string[]): void {
+    this.params = params
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const configs = this.resolveConfigs(request)
+
+    // Check all limits before proceeding
+    for (const config of configs) {
+      const fullKey = `rate_limit:${config.key}`
+
+      if (await this.rateLimiter.tooManyAttempts(fullKey, config.maxAttempts)) {
+        const retryAfter = await this.rateLimiter.availableIn(fullKey)
+        return this.buildTooManyResponse(request, config, retryAfter)
+      }
+    }
+
+    // Record hits
+    for (const config of configs) {
+      const fullKey = `rate_limit:${config.key}`
+      await this.rateLimiter.hit(fullKey, config.decayMinutes * 60)
+    }
+
+    // Process request
+    const response = await next()
+
+    // Add rate limit headers (use the most restrictive limit)
+    return this.addHeaders(response, configs)
+  }
+
+  private resolveConfigs(request: MantiqRequest): RateLimitConfig[] {
+    if (this.params.length === 0) {
+      // Default: 60 per minute by IP
+      return [{ key: request.ip(), maxAttempts: 60, decayMinutes: 1 }]
+    }
+
+    const first = this.params[0]!
+
+    // Check if it's a named limiter
+    const resolver = this.rateLimiter.limiter(first)
+    if (resolver) {
+      const result = resolver(request)
+      return Array.isArray(result) ? result : [result]
+    }
+
+    // Inline: throttle:maxAttempts,decayMinutes
+    const maxAttempts = parseInt(first, 10) || 60
+    const decayMinutes = parseInt(this.params[1] ?? '1', 10) || 1
+
+    return [{
+      key: request.ip(),
+      maxAttempts,
+      decayMinutes,
+    }]
+  }
+
+  private buildTooManyResponse(
+    request: MantiqRequest,
+    config: RateLimitConfig,
+    retryAfter: number,
+  ): Response {
+    if (config.responseCallback) {
+      const headers: Record<string, string> = {
+        'Retry-After': String(retryAfter),
+        'X-RateLimit-Limit': String(config.maxAttempts),
+        'X-RateLimit-Remaining': '0',
+      }
+      const custom = config.responseCallback(request, headers)
+      if (custom) return custom
+    }
+
+    const body = request.expectsJson()
+      ? JSON.stringify({ message: 'Too Many Requests', retry_after: retryAfter })
+      : 'Too Many Requests'
+
+    return new Response(body, {
+      status: 429,
+      headers: {
+        'Content-Type': request.expectsJson() ? 'application/json' : 'text/plain',
+        'Retry-After': String(retryAfter),
+        'X-RateLimit-Limit': String(config.maxAttempts),
+        'X-RateLimit-Remaining': '0',
+      },
+    })
+  }
+
+  private async addHeaders(response: Response, configs: RateLimitConfig[]): Promise<Response> {
+    // Use the most restrictive limit for headers
+    let minRemaining = Infinity
+    let limit = 0
+
+    for (const config of configs) {
+      const fullKey = `rate_limit:${config.key}`
+      const remaining = await this.rateLimiter.remaining(fullKey, config.maxAttempts)
+      if (remaining < minRemaining) {
+        minRemaining = remaining
+        limit = config.maxAttempts
+      }
+    }
+
+    const headers = new Headers(response.headers)
+    headers.set('X-RateLimit-Limit', String(limit))
+    headers.set('X-RateLimit-Remaining', String(minRemaining))
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,3 @@
+// Optional peer dependencies
+declare module 'ioredis' { const x: any; export = x; export default x; }
+declare module 'memjs' { const x: any; export = x; export default x; }

package/src/websocket/WebSocketContext.ts

@@ -1,7 +1,7 @@
 import type { MantiqRequest } from '../contracts/Request.ts'
 
 export interface WebSocketContext {
-  userId?: string | number
+  userId?: string | number | undefined
   channels: Set<string>
   metadata: Record<string, any>
 }