@stacksjs/bun-router 0.0.15 → 0.0.17

package/src/router/server.ts

@@ -1,12 +1,80 @@
 import type { Server } from 'bun'
-import type { EnhancedRequest, HTTPMethod, ServerOptions } from '../types'
+import type { EnhancedRequest, HTTPMethod, Route, ServerOptions } from '../types'
 import type { Router } from './router'
-import { RequestWithMacros } from '../request/macros'
+import { getParsedCookies, getParsedURL, RequestWithMacros } from '../request/macros'
 import { runWithRequest, setCurrentRequest } from '../request/context'
+import { createHandlerInvoker } from './handler-resolver'
+
+// Helpers that frameworks layered on bun-router treat as guaranteed but
+// that aren't shaped as built-in macros. Registered once at module load —
+// they ride the shared macro prototype instead of being closure-assigned
+// per request. (`cookie` is already a built-in macro.)
+if (!RequestWithMacros.hasMacro('getParam')) {
+  RequestWithMacros.macro('getParam', function (this: EnhancedRequest, name: string, defaultValue?: unknown) {
+    const value = this.params?.[name]
+    return value !== undefined ? value : defaultValue
+  })
+}
+// `get(key)` — read query params (and only query params; the full input
+// merge with body etc. is provided by the `input` macro). Only registered
+// when no macro already claimed the name.
+if (!RequestWithMacros.hasMacro('get')) {
+  RequestWithMacros.macro('get', function (this: EnhancedRequest, key: string, defaultValue?: unknown) {
+    const value = getParsedURL(this).searchParams.get(key)
+    return value !== null && value !== undefined ? value : defaultValue
+  })
+}
+// `cookies` — dual-shape, mirroring the response macros (#1857): callable
+// as `req.cookies()` (the legacy built-in macro form, returns the parsed
+// map) while also carrying the name→value entries for direct access and
+// the get/set/delete/getAll utility methods `EnhancedRequest` declares.
+// Installed as a shared-prototype accessor: the hybrid materializes on
+// first access and is cached as an own property, so requests that never
+// touch cookies do zero cookie work.
+RequestWithMacros.macroAccessor('cookies', function (this: EnhancedRequest) {
+  const req = this
+  const cookies = (): Record<string, string> => ({ ...getParsedCookies(req) })
+
+  // Direct map access (req.cookies.session). defineProperty instead of
+  // Object.assign — a cookie literally named `name` or `length` would
+  // collide with the function's own non-writable properties.
+  for (const [key, value] of Object.entries(getParsedCookies(req))) {
+    Object.defineProperty(cookies, key, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
+  }
+
+  cookies.get = (name: string) => getParsedCookies(req)[name]
+  cookies.set = (name: string, value: string, options: any = {}) => {
+    if (!req._cookiesToSet) {
+      req._cookiesToSet = []
+    }
+    req._cookiesToSet.push({ name, value, options })
+  }
+  cookies.delete = (name: string, options: any = {}) => {
+    if (!req._cookiesToDelete) {
+      req._cookiesToDelete = []
+    }
+    req._cookiesToDelete.push({ name, options })
+  }
+  cookies.getAll = () => ({ ...getParsedCookies(req) })
+
+  Object.defineProperty(req, 'cookies', {
+    value: cookies,
+    writable: true,
+    configurable: true,
+    enumerable: true,
+  })
+  return cookies
+})
 
 /**
  * Server handling extension for Router class
  */
+// eslint-disable-next-line pickier/no-unused-vars -- false positive: used on the next line
 export function registerServerHandling(RouterClass: typeof Router): void {
   Object.defineProperties(RouterClass.prototype, {
     /**
@@ -55,6 +123,18 @@ export function registerServerHandling(RouterClass: typeof Router): void {
           serverOptions.development = options.development
         }
 
+        // Opt-in: hand compatible routes to Bun's native router so they
+        // skip the fetch handler's URL parsing and matching entirely.
+        // Incompatible routes and 404/405/HEAD/preflight semantics keep
+        // flowing through the fetch fallback unchanged.
+        this._nativeRoutesEnabled = options.nativeRoutes === true
+        if (this._nativeRoutesEnabled) {
+          const nativeRoutes = this._buildNativeRoutes()
+          if (nativeRoutes) {
+            serverOptions.routes = nativeRoutes
+          }
+        }
+
         // Apply WebSocket configuration if provided
         if (this.wsConfig) {
           serverOptions.websocket = this.wsConfig
@@ -94,13 +174,22 @@ export function registerServerHandling(RouterClass: typeof Router): void {
         // Close the current server
         this.serverInstance.stop()
 
-        // Start a new server with the same configuration
-        this.serverInstance = Bun.serve({
+        // Start a new server with the same configuration. The native
+        // route table is rebuilt so routes registered since serve()
+        // join it.
+        const reloadOptions: any = {
           port,
           hostname,
           fetch: this.handleRequest.bind(this),
           websocket: this.wsConfig || undefined,
-        })
+        }
+        if (this._nativeRoutesEnabled) {
+          const nativeRoutes = this._buildNativeRoutes()
+          if (nativeRoutes) {
+            reloadOptions.routes = nativeRoutes
+          }
+        }
+        this.serverInstance = Bun.serve(reloadOptions)
 
         if (this.config.verbose) {
           console.log(`🔄 Server reloaded at http://${hostname}:${port}`)
@@ -125,77 +214,264 @@ export function registerServerHandling(RouterClass: typeof Router): void {
     },
 
     /**
-     * Internal: actual request handling, executed inside the request context scope.
+     * Internal: dispatch a matched route — enhance the request, run the
+     * cached middleware chain (global + route middleware + handler) and
+     * apply queued cookies. Shared by the fetch handler and the native
+     * Bun route wrappers.
      */
-    handleRequestImpl: {
-      async value(req: Request): Promise<Response> {
+    _dispatchMatchedRoute: {
+      async value(matchedRoute: Route, req: Request, params: Record<string, string>): Promise<Response> {
+        const enhancedReq = this.enhanceRequest(req, params)
+        setCurrentRequest(enhancedReq)
+
+        // Add the matched route to the request
+        enhancedReq.route = matchedRoute
+
+        // Resolve the middleware chain for this route. The composed
+        // chain is cached on the route and only rebuilt when `use()`
+        // registers new global middleware or the route's own stack
+        // changes — building the closure chain per request was a
+        // hot-path cost.
+        const route = matchedRoute as Route & {
+          _compiledChain?: (req: EnhancedRequest) => Promise<Response | null>
+          _chainEpoch?: number
+          _chainMwLen?: number
+        }
+        const epoch: number = this._mwEpoch || 0
+        const routeMwLen = route.middleware ? route.middleware.length : 0
+
+        let chain = route._compiledChain
+        if (!chain || route._chainEpoch !== epoch || route._chainMwLen !== routeMwLen) {
+          // The handler's dispatch branch (function vs class vs string
+          // action) is resolved once here instead of per request
+          const invoke = createHandlerInvoker(route.handler, this.config)
+
+          if (routeMwLen === 0 && this.globalMiddleware.length === 0) {
+            // No middleware: the chain is the bare invoker — no
+            // closure tower, no next() allocations per request
+            chain = invoke
+          }
+          else {
+            const middlewareStack = routeMwLen > 0
+              ? [...this.globalMiddleware, ...route.middleware]
+              : [...this.globalMiddleware]
+            middlewareStack.push((handlerReq: EnhancedRequest, _next: any) => invoke(handlerReq))
+            chain = this.buildMiddlewareChain(middlewareStack)!
+          }
+          route._compiledChain = chain
+          route._chainEpoch = epoch
+          route._chainMwLen = routeMwLen
+        }
+
+        let response: Response | null
         try {
-          // Create URL for route matching
-          const url = new URL(req.url)
+          response = await chain!(enhancedReq)
+        }
+        catch (error) {
+          if (this.errorHandler) {
+            response = await this.errorHandler(error as Error)
+          }
+          else {
+            throw error
+          }
+        }
 
-          // Handle CORS preflight OPTIONS requests - but check for registered OPTIONS routes first
-          // This ensures explicitly registered OPTIONS routes work while still providing CORS support
-          if (req.method === 'OPTIONS') {
-            const hostname = url.hostname || req.headers.get('host')?.split(':')[0] || 'localhost'
-            const optionsMatch = this.matchRoute(url.pathname, 'OPTIONS', hostname)
-            if (!optionsMatch) {
-              // No explicit OPTIONS route - return generic CORS preflight response
-              return new Response(null, {
-                status: 204,
-                headers: {
-                  'Access-Control-Allow-Origin': '*',
-                  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
-                  'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
-                  'Access-Control-Max-Age': '86400',
-                  'Access-Control-Allow-Credentials': 'true',
-                },
-              })
+        // Apply modified cookies to the response
+        if (response) {
+          return this.applyModifiedCookies(response, enhancedReq)
+        }
+
+        // This should not happen since we're always returning a response now
+        return new Response('No response from middleware chain', { status: 500 })
+      },
+      writable: true,
+      configurable: true,
+    },
+
+    /**
+     * Internal: build Bun.serve's native `routes` table from compatible
+     * registered routes (see `ServerOptions.nativeRoutes`). Returns null
+     * when nothing qualifies.
+     */
+    _buildNativeRoutes: {
+      value(): Record<string, Record<string, (req: Request) => Promise<Response>>> | null {
+        const NATIVE_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'])
+
+        // Convert `{param}` paths to Bun's `:param` syntax. Returns null
+        // for shapes the native router can't express with our semantics:
+        // optional params, constraints, mixed segments like `user-{id}`,
+        // and non-trailing wildcards.
+        const convertPath = (path: string): string | null => {
+          if (path === '*') {
+            return '/*'
+          }
+          const segments = path.split('/')
+          const converted: string[] = []
+          for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i]
+            if (segment === '') {
+              converted.push(segment)
+              continue
             }
-            // Let the registered OPTIONS route handle it (fall through to normal route matching)
+            if (segment === '*') {
+              // Wildcards only in the trailing position
+              return i === segments.length - 1 ? [...converted, '*'].join('/') : null
+            }
+            const paramMatch = segment.match(/^\{([A-Z_$][\w$]*)\}$/i)
+            if (paramMatch) {
+              converted.push(`:${paramMatch[1]}`)
+              continue
+            }
+            if (segment.includes('{') || segment.includes(':') || segment.includes('*')) {
+              return null
+            }
+            converted.push(segment)
           }
+          return converted.join('/')
+        }
 
-          // Get domain from the host header
-          const hostname = url.hostname || req.headers.get('host')?.split(':')[0] || 'localhost'
+        // Wrap a route in the same context/error envelope the fetch
+        // handler provides, so handlers can't tell which router matched
+        const self = this
+        const wrapRoute = (route: Route, isWildcard: boolean) => {
+          return (req: Request & { params?: Record<string, string> }) => {
+            return runWithRequest(req as EnhancedRequest, async () => {
+              try {
+                let params: Record<string, string> = req.params ?? {}
+                if (isWildcard) {
+                  // Bun doesn't expose the wildcard remainder as a param;
+                  // mirror the fetch matcher's `wildcard` key
+                  const pathname = new URL(req.url).pathname
+                  const basePath = route.path === '*' ? '/' : route.path.slice(0, -1)
+                  params = { ...params, wildcard: pathname.slice(basePath.length) }
+                }
+                return await self._dispatchMatchedRoute(route, req, params)
+              }
+              catch (error) {
+                console.error('Error handling request:', error)
+                if (self.errorHandler) {
+                  return self.errorHandler(error as Error)
+                }
+                return new Response(JSON.stringify({
+                  success: false,
+                  message: 'Internal Server Error',
+                  error: error instanceof Error ? error.message : String(error),
+                }), {
+                  status: 500,
+                  headers: {
+                    'Content-Type': 'application/json',
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
+                  },
+                })
+              }
+            })
+          }
+        }
 
-          // Find a matching route
-          const match = this.matchRoute(url.pathname, req.method as HTTPMethod, hostname)
+        const natives: Record<string, Record<string, (req: Request) => Promise<Response>>> = {}
+        // Bun resolves same-shape patterns by specificity, not by our
+        // registration order — only the first registration of a given
+        // shape goes native; later ones would silently shadow it
+        const claimedShapes = new Map<string, string>()
 
-          // Enhance the request with params and other utilities
-          const enhancedReq = this.enhanceRequest(req, match?.params || {})
-          setCurrentRequest(enhancedReq)
+        for (const route of this.routes as Route[]) {
+          if (!NATIVE_METHODS.has(route.method)) {
+            continue
+          }
+          // Explicit per-route opt-out (router.withoutNativeDispatch())
+          if (route.nativeDispatch === false) {
+            continue
+          }
+          // Constrained params need our matcher
+          if (route.constraints && Object.keys(route.constraints).length > 0) {
+            continue
+          }
+          // Response-handler routes are already served via Bun's static map
+          if (route.handler instanceof Response) {
+            continue
+          }
+          const bunPath = convertPath(route.path)
+          if (!bunPath) {
+            continue
+          }
 
-          if (match) {
-            // Add the matched route to the request
-            enhancedReq.route = match.route
+          const shape = bunPath.replace(/:[^/]+/g, ':p')
+          const claimedBy = claimedShapes.get(shape)
+          if (claimedBy && claimedBy !== bunPath) {
+            continue
+          }
+          claimedShapes.set(shape, bunPath)
 
-            // Collect all middleware to run
-            const middlewareStack = [...this.globalMiddleware]
+          const entry = (natives[bunPath] ??= {})
+          if (entry[route.method]) {
+            continue // first registration wins, matching the fetch matcher
+          }
+          entry[route.method] = wrapRoute(route, route.path.endsWith('*'))
+        }
 
-            // Add route-specific middleware
-            if (match.route.middleware && match.route.middleware.length > 0) {
-              middlewareStack.push(...match.route.middleware)
-            }
+        // GET routes answer HEAD automatically (mirrors the fetch
+        // matcher's HEAD→GET fallback, but stays on the native fast path)
+        for (const entry of Object.values(natives)) {
+          if (entry.GET && !entry.HEAD) {
+            entry.HEAD = entry.GET
+          }
+        }
 
-            // Create a final middleware that executes the route handler
-            const routeHandlerMiddleware = async (req: EnhancedRequest, _next: any) => {
-              return await this.resolveHandler(match.route.handler, req)
-            }
+        return Object.keys(natives).length > 0 ? natives : null
+      },
+      writable: true,
+      configurable: true,
+    },
 
-            // Add the route handler as the final middleware
-            middlewareStack.push(routeHandlerMiddleware)
+    /**
+     * Internal: actual request handling, executed inside the request context scope.
+     */
+    handleRequestImpl: {
+      async value(req: Request): Promise<Response> {
+        try {
+          // Create URL for route matching, and share it with the request
+          // macros (path()/root()/get()/fingerprint() reuse it instead of
+          // reparsing req.url)
+          const url = new URL(req.url)
+          ;(req as any)._parsedURL = url
 
-            // Run middleware stack with the route handler at the end
-            const response = await this.runMiddleware(enhancedReq, middlewareStack)
+          // Get domain from the host header
+          const hostname = url.hostname || req.headers.get('host')?.split(':')[0] || 'localhost'
 
-            // Apply modified cookies to the response
-            if (response) {
-              return this.applyModifiedCookies(response, enhancedReq)
+          // Find a matching route
+          const match = this.matchRoute(url.pathname, req.method as HTTPMethod, hostname)
+
+          // CORS preflight: when no explicit OPTIONS route is registered,
+          // answer with a generic preflight response. A request with an
+          // Origin header gets that origin reflected (plus Vary: Origin)
+          // so credentials stay usable — `Access-Control-Allow-Credentials`
+          // combined with a wildcard origin is rejected by browsers.
+          if (req.method === 'OPTIONS' && !match) {
+            const origin = req.headers.get('origin')
+            const preflightHeaders: Record<string, string> = {
+              'Access-Control-Allow-Origin': origin || '*',
+              'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+              'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
+              'Access-Control-Max-Age': '86400',
+            }
+            if (origin) {
+              preflightHeaders['Access-Control-Allow-Credentials'] = 'true'
+              preflightHeaders.Vary = 'Origin'
             }
+            return new Response(null, { status: 204, headers: preflightHeaders })
+          }
 
-            // This should not happen since we're always returning a response now
-            return new Response('No response from middleware chain', { status: 500 })
+          if (match) {
+            return await this._dispatchMatchedRoute(match.route, req, match.params)
           }
 
+          // Enhance the request with params and other utilities (the
+          // matched-route path enhances inside _dispatchMatchedRoute)
+          const enhancedReq = this.enhanceRequest(req, {})
+          setCurrentRequest(enhancedReq)
+
           // No route found - check if the path exists with a different method (405 vs 404).
           // The 404/405 responses below now (a) include path + method in the body so client
           // debugging is one grep away, and (b) flow through globalMiddleware so cross-cutting
@@ -282,93 +558,31 @@ export function registerServerHandling(RouterClass: typeof Router): void {
     },
 
     /**
-     * Enhance a request with params and other utilities
+     * Enhance a request with params and other utilities.
+     *
+     * Per-request work is intentionally minimal: assign `params` and
+     * insert the shared macro prototype. Everything else (cookies,
+     * input helpers, URL parsing) lives on the prototype and
+     * materializes lazily on first access.
      */
     enhanceRequest: {
       value(req: Request, params: Record<string, string> = {}): EnhancedRequest {
-        // Lazy cookie parsing
-        let parsedCookies: Record<string, string> | null = null
-
-        const getCookies = () => {
-          if (parsedCookies === null) {
-            parsedCookies = {}
-            const cookieHeader = req.headers.get('cookie') || ''
-
-            cookieHeader.split(';').forEach((cookie) => {
-              const parts = cookie.trim().split('=')
-              if (parts.length >= 2) {
-                const name = parts[0].trim()
-                const value = parts.slice(1).join('=').trim()
-                parsedCookies![name] = decodeURIComponent(value)
-              }
-            })
-          }
-          return parsedCookies
+        const enhancedReq = req as unknown as EnhancedRequest
+        if ('params' in req) {
+          // Bun's native-route requests expose `params` as a readonly
+          // prototype getter — plain assignment throws. An own property
+          // shadows it (and carries our augmentations, e.g. `wildcard`).
+          Object.defineProperty(enhancedReq, 'params', {
+            value: params,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+          })
         }
-
-        // Create cookie utilities with lazy parsing
-        const cookies = {
-          get: (name: string) => getCookies()[name],
-          set: (name: string, value: string, options: any = {}) => {
-            const enhancedRequest = req as EnhancedRequest
-            if (!enhancedRequest._cookiesToSet) {
-              enhancedRequest._cookiesToSet = []
-            }
-            enhancedRequest._cookiesToSet.push({ name, value, options })
-          },
-          delete: (name: string, options: any = {}) => {
-            const enhancedRequest = req as EnhancedRequest
-            if (!enhancedRequest._cookiesToDelete) {
-              enhancedRequest._cookiesToDelete = []
-            }
-            enhancedRequest._cookiesToDelete.push({ name, options })
-          },
-          getAll: () => ({ ...getCookies() }),
-        }
-
-        // Create enhanced request
-        const enhancedReq = Object.assign(req, {
-          params,
-          cookies: getCookies(), // Set cookies as plain object for direct access
-          _cookiesToSet: [],
-          _cookiesToDelete: [],
-        }) as unknown as EnhancedRequest
-
-        // Attach registered request macros (input, has, bearerToken, etc.) so
-        // they're available in middleware and handlers without manual setup.
-        // Applied *before* the cookie utility so the cookies macro doesn't
-        // overwrite the get/set/delete object form consumers depend on.
-        RequestWithMacros.applyMacros(enhancedReq)
-
-        // Attach the helpers consumers reach for that aren't shaped as
-        // generic input macros — `getParam`, the function-form `cookie`,
-        // the parsed-query `get` shorthand. These mirror the methods the
-        // bare `Router.enhanceRequest` (router.ts) attaches; without them
-        // here, requests that flow through the registered server.ts
-        // override are missing exactly the helpers that frameworks
-        // layered on bun-router (Stacks, etc.) treat as guaranteed.
-        ;(enhancedReq as any).getParam = <T = string>(name: string, defaultValue?: T): T | undefined => {
-          const value = params?.[name] as T | undefined
-          return value !== undefined ? value : defaultValue
-        }
-        ;(enhancedReq as any).cookie = (name: string, defaultValue?: string): string | null => {
-          const value = getCookies()[name]
-          return value !== undefined ? value : (defaultValue ?? null)
-        }
-        // `get(key)` — read query params (and only query params; the full
-        // input merge with body etc. is provided by the `input` macro).
-        // Skip if a macro already registered it under the same name.
-        if (typeof (enhancedReq as any).get !== 'function') {
-          ;(enhancedReq as any).get = <T = unknown>(key: string, defaultValue?: T): T | undefined => {
-            const url = new URL(req.url)
-            const value = url.searchParams.get(key) as T | null
-            return value !== null && value !== undefined ? value : defaultValue
-          }
+        else {
+          enhancedReq.params = params
         }
-
-        // Add cookie methods to the request (overrides any macro named `cookies`).
-        Object.assign(enhancedReq, { cookies: { ...getCookies(), ...cookies } })
-
+        RequestWithMacros.applyMacros(enhancedReq)
         return enhancedReq
       },
       writable: true,
@@ -380,6 +594,14 @@ export function registerServerHandling(RouterClass: typeof Router): void {
      */
     applyModifiedCookies: {
       value(response: Response, req: EnhancedRequest): Response {
+        // Fast path: nothing to apply — return the response untouched
+        // instead of paying for a clone on every request
+        const hasSet = req._cookiesToSet && req._cookiesToSet.length > 0
+        const hasDelete = req._cookiesToDelete && req._cookiesToDelete.length > 0
+        if (!hasSet && !hasDelete) {
+          return response
+        }
+
         // Clone the response to modify headers
         const newResponse = new Response(response.body, {
           status: response.status,

package/src/router/validation-integration.ts

@@ -2,7 +2,7 @@
  * Router Validation Integration
  *
  * Integration layer for validation and macros with the router.
- * Provides RouteBuilder and FluentRouter for building routes with validation support.
+ * Provides RouteBuilder and ValidationFluentRouter for building routes with validation support.
  */
 
 import type { EnhancedRequest, MiddlewareHandler, NextFunction, RouteHandler } from '../types'
@@ -62,9 +62,15 @@ export class RouteBuilder {
 }
 
 /**
- * Fluent router for enhanced routing functionality
+ * Minimal route collector with validation support.
+ *
+ * Renamed from `FluentRouter`: this module used to declare a third class
+ * with that name. It was shadowed by the canonical `FluentRouter` exported
+ * from `fluent-routing.ts` (explicit exports win over `export *`), so
+ * `createFluentRouter()` silently returned a different class than the
+ * public `FluentRouter` symbol. The distinct name removes the ambiguity.
  */
-export class FluentRouter {
+export class ValidationFluentRouter {
   private routes: Array<{
     method: string
     path: string
@@ -320,8 +326,8 @@ export const RouteHelpers: {
 /**
  * Fluent router factory
  */
-export function createFluentRouter(): FluentRouter {
-  return new FluentRouter()
+export function createFluentRouter(): ValidationFluentRouter {
+  return new ValidationFluentRouter()
 }
 
 /**

package/src/testing/auth-testing.ts

@@ -44,11 +44,13 @@ export class AuthTester {
   withJWT(token: string, type: 'Bearer' | 'Basic' = 'Bearer'): AuthTester {
     const headers = new Headers(this.request.headers)
     headers.set('Authorization', `${type} ${token}`)
-    // Create a new request object with updated headers
+    // Create a new request object with updated headers. The spread drops
+    // prototype methods (e.g. `clone`) from the inferred type, so re-assert
+    // the shape — the mock still carries them at runtime.
     this.request = {
       ...this.request,
       headers,
-    }
+    } as EnhancedRequest
     return this
   }
 
@@ -66,7 +68,7 @@ export class AuthTester {
   withApiKey(apiKey: string, headerName: string = 'X-API-Key'): AuthTester {
     const headers = new Headers(this.request.headers)
     headers.set(headerName, apiKey)
-    this.request = { ...this.request, headers }
+    this.request = { ...this.request, headers } as EnhancedRequest
     return this
   }
 
@@ -77,7 +79,7 @@ export class AuthTester {
     const credentials = btoa(`${username}:${password}`)
     const headers = new Headers(this.request.headers)
     headers.set('Authorization', `Basic ${credentials}`)
-    this.request = { ...this.request, headers }
+    this.request = { ...this.request, headers } as EnhancedRequest
     return this
   }
 

package/src/types/middleware-types.ts

@@ -6,12 +6,15 @@
 
 import type { RouteHandler, TypedRequest } from './route-inference'
 
-// Base middleware interface with generic constraints
+// Base middleware interface with generic constraints. The defaults are
+// the narrowest types that hold for every middleware (`Request` in,
+// `Response` out via an async `next`) — `any` defaults let unconstrained
+// middleware slip through composition unchecked.
 export interface TypedMiddleware<
-  TInput = any,
-  TOutput = TInput,
+  TInput = Request,
+  TOutput = Response,
   _TContext = object,
-  TNext = any,
+  TNext = () => Promise<TOutput>,
 > {
   (
     request: TInput,