@stacksjs/bun-router 0.0.14 → 0.0.15

package/src/router/router.ts

@@ -0,0 +1,1604 @@
+import type { Server } from 'bun'
+import type { MiddlewareDependency, MiddlewarePipeline, MiddlewarePipelineStats, MiddlewareSkipCondition } from '../middleware/pipeline'
+import type {
+  ActionHandler,
+  CookieOptions,
+  CookieToSet,
+  EnhancedRequest,
+  MiddlewareHandler,
+  NextFunction,
+  Route,
+  RouteGroup,
+  RouteHandler,
+  RouterConfig,
+  ThrottlePattern,
+  WebSocketConfig,
+  WebSocketData,
+} from '../types'
+import { createRateLimitMiddleware, parseThrottleString } from '../routing/route-throttling'
+import { registerNamedRoute } from '../url'
+import { extractParamNames, joinPaths, matchPath } from '../utils'
+
+/**
+ * Route compiler interface for pattern matching
+ */
+export interface RouteCompiler {
+  compile: (path: string) => RegExp
+  match: (path: string, pattern: RegExp) => Record<string, string> | null
+}
+
+/**
+ * Middleware cache info interface
+ */
+export interface MiddlewareCacheInfo {
+  size: number
+  routes: string[]
+  hitRate: number
+}
+
+// Re-export types for module augmentation
+export type {
+  ActionHandler,
+  MiddlewareHandler,
+  Route,
+  RouteGroup,
+  RouteHandler,
+  RouterConfig,
+  WebSocketConfig,
+}
+
+// Middleware condition type
+export type MiddlewareCondition = (_req: EnhancedRequest) => boolean
+
+/**
+ * Unified Router class with advanced middleware patterns
+ */
+export class Router {
+  routes: Route[] = []
+  currentGroup: RouteGroup | null = null
+  globalMiddleware: MiddlewareHandler[] = []
+  namedRoutes: Map<string, Route> = new Map()
+  fallbackHandler: ActionHandler | null = null
+  patterns: Map<string, string> = new Map()
+  currentDomain: string | null = null
+  domains: Record<string, Route[]> = {}
+  serverInstance: Server<WebSocketData> | null = null
+  wsConfig: WebSocketConfig | null = null
+  errorHandler: ((_error: Error) => Response | Promise<Response>) | null = null
+  templateCache: Map<string, string> = new Map<string, string>()
+  routeCache: Map<string, { route: Route, params: Record<string, string> }> = new Map()
+  staticRoutes: Map<string, Map<string, Route>> = new Map()
+  staticResponses: Map<string, Response> = new Map()
+  precompiledPatterns: Map<string, RegExp> = new Map()
+  domainPatternCache: Map<string, RegExp> = new Map()
+  routeCompiler: RouteCompiler | null = null
+
+  // Advanced middleware features
+  private middlewareGroups: Map<string, MiddlewareHandler[]> = new Map()
+  private namedMiddleware: Map<string, (params?: string) => MiddlewareHandler> = new Map()
+  private conditionalMiddleware: Array<{ condition: MiddlewareCondition, middleware: MiddlewareHandler[] }> = []
+
+  // Middleware pipeline for advanced features
+  _middlewarePipeline?: MiddlewarePipeline
+
+  config: RouterConfig = {
+    verbose: false,
+    routesPath: 'routes',
+    apiRoutesPath: 'routes/api.ts',
+    webRoutesPath: 'routes/web.ts',
+    apiPrefix: '/api',
+    webPrefix: '',
+    actionsPath: 'actions',
+    controllersPath: 'controllers',
+    defaultMiddleware: {
+      api: [],
+      web: [],
+    },
+  }
+
+  constructor(config: Partial<RouterConfig> = {}) {
+    this.routes = []
+    this.config = { ...this.config, ...config }
+    this.initializeDefaultMiddleware()
+  }
+
+  /**
+   * Initialize default named middleware
+   */
+  private initializeDefaultMiddleware(): void {
+    // Auth middleware
+    this.namedMiddleware.set('auth', () => async (req: EnhancedRequest, next: NextFunction) => {
+      const token = req.headers.get('authorization')?.replace('Bearer ', '')
+      if (!token) {
+        return new Response('Unauthorized', { status: 401 })
+      }
+      return await next()
+    })
+
+    // Throttle middleware with parameters
+    this.namedMiddleware.set('throttle', (params?: string): MiddlewareHandler => {
+      const config = params ? parseThrottleString(params as ThrottlePattern) : { maxAttempts: 60, windowMs: 60000 }
+      return createRateLimitMiddleware({
+        maxAttempts: config.maxAttempts || 60,
+        windowMs: config.windowMs,
+        keyGenerator: (req: EnhancedRequest) => req.headers.get('x-forwarded-for') || 'anonymous',
+      })
+    })
+
+    // CORS middleware
+    this.namedMiddleware.set('cors', () => async (_req: EnhancedRequest, next: NextFunction) => {
+      const response = await next()
+      if (response) {
+        response.headers.set('Access-Control-Allow-Origin', '*')
+        response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
+        response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+      }
+      return response
+    })
+  }
+
+  /**
+   * Register a middleware group
+   */
+  middlewareGroup(name: string, middlewareNames: string[]): this {
+    const middlewareHandlers: MiddlewareHandler[] = []
+
+    for (const middlewareName of middlewareNames) {
+      const [name, params] = middlewareName.split(':')
+      const middlewareFactory = this.namedMiddleware.get(name)
+
+      if (middlewareFactory) {
+        middlewareHandlers.push(middlewareFactory(params))
+      }
+    }
+
+    this.middlewareGroups.set(name, middlewareHandlers)
+    return this
+  }
+
+  /**
+   * Apply middleware group to routes
+   */
+  middlewareGroupRoutes(name: string): RouteGroupBuilder {
+    const middlewareHandlers = this.middlewareGroups.get(name) || []
+    return new RouteGroupBuilder(this, middlewareHandlers)
+  }
+
+  /**
+   * Conditional middleware execution
+   */
+  when(condition: MiddlewareCondition): ConditionalBuilder {
+    return new ConditionalBuilder(this, condition)
+  }
+
+  /**
+   * Apply middleware with parameters
+   */
+  middleware(middlewareName: string): MiddlewareBuilder {
+    const [name, params] = middlewareName.split(':')
+    const middlewareFactory = this.namedMiddleware.get(name)
+
+    if (!middlewareFactory) {
+      throw new Error(`Unknown middleware: ${name}`)
+    }
+
+    const middlewareHandler = middlewareFactory(params)
+    return new MiddlewareBuilder(this, [middlewareHandler])
+  }
+
+  /**
+   * Get the server instance
+   */
+  getServer(): Server<WebSocketData> | null {
+    return this.serverInstance
+  }
+
+  /**
+   * Extend the router with custom methods
+   */
+  extend(methods: Record<string, (...args: unknown[]) => unknown>): Router {
+    for (const [name, method] of Object.entries(methods)) {
+      if (typeof method === 'function') {
+        // @ts-expect-error - dynamically extending the object
+        this[name] = method.bind(this)
+      }
+    }
+    return this
+  }
+
+  /**
+   * Register routes from a package or module file.
+   * Loads the route file within an optional group (prefix + middleware).
+   */
+  async register(routePath: string, options?: { prefix?: string, middleware?: MiddlewareHandler[] }): Promise<Router> {
+    const callback = async () => {
+      await import(routePath)
+    }
+
+    if (options?.prefix || (options?.middleware && options.middleware.length > 0)) {
+      await this.group({
+        prefix: options.prefix,
+        middleware: options.middleware,
+      }, callback)
+    }
+    else {
+      await callback()
+    }
+
+    return this
+  }
+
+  /**
+   * Invalidate route caches
+   */
+  invalidateCache(): void {
+    this.routeCache.clear()
+  }
+
+  /**
+   * Internal method to add a route with full HTTP method support
+   * This is the core route registration method used by get/post/put/patch/delete
+   */
+  registerRoute(
+    method: string,
+    path: string,
+    handler: ActionHandler,
+    type?: 'api' | 'web',
+    name?: string,
+    middleware?: (string | MiddlewareHandler)[],
+  ): Router {
+    // Apply current group settings if in a group
+    let routePath = path
+    let routeMiddleware: MiddlewareHandler[] = []
+    const routeType = type || 'web'
+
+    if (this.currentGroup) {
+      // Apply prefix if it exists
+      if (this.currentGroup.prefix) {
+        routePath = joinPaths(this.currentGroup.prefix, path)
+      }
+
+      // Apply middleware if it exists
+      if (this.currentGroup.middleware && this.currentGroup.middleware.length > 0) {
+        routeMiddleware = [...this.currentGroup.middleware] as MiddlewareHandler[]
+      }
+    }
+
+    // Apply route-specific middleware if provided
+    if (middleware && middleware.length > 0) {
+      for (const middlewareItem of middleware) {
+        const resolved = this.resolveMiddleware(middlewareItem)
+        if (resolved) {
+          routeMiddleware.push(resolved)
+        }
+      }
+    }
+
+    // Apply API/Web path prefixes
+    if (routeType === 'api' && this.config.apiPrefix) {
+      routePath = joinPaths(this.config.apiPrefix, routePath)
+    }
+    else if (routeType === 'web' && this.config.webPrefix) {
+      routePath = joinPaths(this.config.webPrefix, routePath)
+    }
+
+    // Apply domain if in a domain group
+    let domain: string | undefined
+    if (this.currentDomain) {
+      domain = this.currentDomain
+    }
+
+    // Create the route
+    const route: Route = {
+      method: method.toUpperCase(),
+      path: routePath,
+      handler,
+      domain,
+      params: {},
+      middleware: routeMiddleware,
+    }
+
+    // Apply constraints from patterns map
+    const paramNames = extractParamNames(routePath)
+    const constraints: Record<string, string> = {}
+
+    paramNames.forEach((param: string) => {
+      // Remove optional marker for constraint lookup
+      const baseParam = param.replace('?', '')
+      if (this.patterns.has(baseParam)) {
+        constraints[baseParam] = this.patterns.get(baseParam)!
+      }
+    })
+
+    if (Object.keys(constraints).length > 0) {
+      route.constraints = constraints
+    }
+
+    // Add pattern property for route matching
+    route.pattern = {
+      exec: (url: URL): { pathname: { groups: Record<string, string> } } | null => {
+        const params: Record<string, string> = {}
+        // Pass constraints directly to matchPath for more efficient matching
+        const constraintsRecord = route.constraints && !Array.isArray(route.constraints)
+          ? route.constraints as Record<string, string>
+          : undefined
+
+        const isMatch = matchPath(routePath, url.pathname, params, constraintsRecord)
+
+        if (!isMatch) {
+          return null
+        }
+
+        return {
+          pathname: {
+            groups: params,
+          },
+        }
+      },
+    }
+
+    // Add to the appropriate collection
+    if (domain) {
+      if (!this.domains[domain]) {
+        this.domains[domain] = []
+      }
+      this.domains[domain].push(route)
+    }
+    else {
+      this.routes.push(route)
+    }
+
+    // Add to static routes map for fast lookup if it's a static route
+    if (!routePath.includes('{') && !routePath.includes('*')) {
+      if (!this.staticRoutes.has(method.toUpperCase())) {
+        this.staticRoutes.set(method.toUpperCase(), new Map())
+      }
+      this.staticRoutes.get(method.toUpperCase())!.set(routePath, route)
+    }
+
+    // Add to named routes if name is provided
+    if (name) {
+      route.name = name
+      this.namedRoutes.set(name, route)
+      registerNamedRoute(name, route.path)
+    }
+
+    // Clear route cache when new routes are added
+    this.routeCache.clear()
+
+    return this
+  }
+
+  /**
+   * Resolve middleware from string or handler (synchronous)
+   */
+  resolveMiddleware(middleware: string | MiddlewareHandler): MiddlewareHandler | null {
+    if (typeof middleware === 'function') {
+      return middleware
+    }
+
+    // Parse middleware string like "auth:api" or "throttle:60,1"
+    const [name, params] = middleware.split(':')
+    const middlewareFactory = this.namedMiddleware.get(name)
+
+    if (middlewareFactory) {
+      return middlewareFactory(params)
+    }
+
+    return null
+  }
+
+  /**
+   * HTTP GET method.
+   *
+   * `TPath` is inferred from the path literal at the call site, so an
+   * inline handler's `request.params` narrows to the extracted keyset:
+   *
+   * ```ts
+   * router.get('/api/users/{id}', (req) => {
+   *   req.params.id // typed `string`, no `as any`
+   *   // @ts-expect-error wrong key
+   *   req.params.bogus
+   * })
+   * ```
+   *
+   * The string-action / class-handler forms (`'Actions/Foo/BarAction'`)
+   * keep working — `ActionHandler<TPath>` is a union that accepts them.
+   * See stacksjs/stacks#1851 for the broader typed-request work.
+   */
+  get<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    return this.registerRoute('GET', path, handler, type, name, middleware)
+  }
+
+  /**
+   * HTTP POST method. See {@link get} for `TPath`-driven param
+   * narrowing on inline handlers.
+   */
+  post<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    return this.registerRoute('POST', path, handler, type, name, middleware)
+  }
+
+  /**
+   * HTTP PUT method. See {@link get} for `TPath`-driven param
+   * narrowing on inline handlers.
+   */
+  put<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    return this.registerRoute('PUT', path, handler, type, name, middleware)
+  }
+
+  /**
+   * HTTP PATCH method. See {@link get} for `TPath`-driven param
+   * narrowing on inline handlers.
+   */
+  patch<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    return this.registerRoute('PATCH', path, handler, type, name, middleware)
+  }
+
+  /**
+   * HTTP DELETE method. See {@link get} for `TPath`-driven param
+   * narrowing on inline handlers.
+   */
+  delete<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    return this.registerRoute('DELETE', path, handler, type, name, middleware)
+  }
+
+  /**
+   * HTTP OPTIONS method. See {@link get} for `TPath`-driven param
+   * narrowing on inline handlers.
+   */
+  options<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    return this.registerRoute('OPTIONS', path, handler, type, name, middleware)
+  }
+
+  /**
+   * Register the same handler against multiple HTTP methods. The
+   * handler is type-narrowed via {@link ActionHandler}'s `TPath`
+   * generic, same as the single-method overloads.
+   */
+  match<TPath extends string>(methods: string[], path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    for (const method of methods) {
+      this.registerRoute(method, path, handler, type, name, middleware)
+    }
+    return this
+  }
+
+  /**
+   * Register the handler against every HTTP method. See {@link get}
+   * for `TPath`-driven param narrowing on inline handlers.
+   */
+  any<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router {
+    const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
+    return this.match(methods, path, handler, type, name, middleware)
+  }
+
+  /**
+   * Set fallback handler for unmatched routes
+   */
+  fallback(handler: ActionHandler): Router {
+    this.fallbackHandler = handler
+    return this
+  }
+
+  /**
+   * Generate URL for a named route
+   */
+  route(name: string, params: Record<string, string> = {}): string {
+    const route = this.namedRoutes.get(name)
+    if (!route) {
+      throw new Error(`Route with name "${name}" not found`)
+    }
+
+    let url = route.path
+    // Replace path parameters
+    for (const [param, value] of Object.entries(params)) {
+      url = url.replace(`{${param}}`, encodeURIComponent(value))
+      url = url.replace(`{${param}?}`, encodeURIComponent(value))
+    }
+
+    return url
+  }
+
+  /**
+   * Set error handler
+   */
+  onError(handler: (error: Error) => Response | Promise<Response>): Router {
+    this.errorHandler = handler
+    return this
+  }
+
+  /**
+   * Create redirect response
+   */
+  redirect(url: string, status: 301 | 302 | 303 | 307 | 308 = 302): Response {
+    const headers = new Headers()
+    headers.set('Location', url)
+    return new Response(null, {
+      status,
+      headers,
+    })
+  }
+
+  /**
+   * Create permanent redirect response
+   */
+  permanentRedirect(url: string): Response {
+    return this.redirect(url, 301)
+  }
+
+  /**
+   * Register redirect route
+   */
+  redirectRoute(from: string, to: string, status: 301 | 302 | 303 | 307 | 308 = 302): Router {
+    this.get(from, (_req: EnhancedRequest) => {
+      return this.redirect(to, status)
+    })
+    return this
+  }
+
+  /**
+   * Start the HTTP server
+   */
+  async serve(options?: { port?: number, hostname?: string }): Promise<Server<WebSocketData>> {
+    // Invalidate route cache before starting server
+    this.invalidateCache()
+
+    // Create server options - use type assertion for Bun.serve compatibility
+    const serverOptions = {
+      ...options,
+      fetch: this.handleRequest.bind(this),
+      websocket: this.wsConfig,
+    } as Parameters<typeof Bun.serve>[0]
+
+    // Start the server
+    this.serverInstance = Bun.serve(serverOptions) as Server<WebSocketData>
+
+    if (this.config.verbose) {
+      const port = this.serverInstance.port
+      const hostname = this.serverInstance.hostname
+      console.log(`\n🚀 Server running at http://${hostname}:${port}\n`)
+    }
+
+    return this.serverInstance
+  }
+
+  /**
+   * Handle an HTTP request
+   */
+  async handleRequest(req: Request): Promise<Response> {
+    try {
+      // Create URL for route matching
+      const url = new URL(req.url)
+
+      if (this.config.verbose) {
+        console.log(`${req.method} ${url.pathname}`)
+      }
+
+      // 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',
+              'Access-Control-Max-Age': '86400',
+            },
+          })
+        }
+        // Let the registered OPTIONS route handle it (fall through to normal route matching)
+      }
+
+      // Get domain from the host header
+      const hostname = url.hostname || req.headers.get('host')?.split(':')[0] || 'localhost'
+
+      // Find a matching route
+      const match = this.matchRoute(url.pathname, req.method as any, hostname)
+
+      // Enhance the request with params and other utilities
+      const enhancedReq = this.enhanceRequest(req, match?.params || {})
+
+      if (match) {
+        // Add the matched route to the request
+        enhancedReq.route = match.route
+
+        // Collect all middleware to run
+        const middlewareStack = [...this.globalMiddleware]
+
+        // Add route-specific middleware
+        if (match.route.middleware && match.route.middleware.length > 0) {
+          middlewareStack.push(...match.route.middleware)
+        }
+
+        // Create a final middleware that executes the route handler
+        const routeHandlerMiddleware = async (req: EnhancedRequest, _next: NextFunction) => {
+          return await this.resolveHandler(match.route.handler, req)
+        }
+
+        // Add the route handler as the final middleware
+        middlewareStack.push(routeHandlerMiddleware)
+
+        // Run middleware stack with the route handler at the end
+        const response = await this.runMiddleware(enhancedReq, middlewareStack)
+
+        // 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 })
+      }
+
+      // No route found - check if the path exists with a different method (405 vs 404).
+      // 404/405 bodies now include path + method so client-side debugging (typo'd
+      // endpoint, stale SPA cache, missing route registration) is one grep away.
+      // Both responses still flow through globalMiddleware so user middleware
+      // (X-Request-ID, audit, custom CORS) sees them.
+      const allowedMethods = this.getAllowedMethods(url.pathname, hostname)
+
+      if (allowedMethods.length > 0) {
+        const methodNotAllowedHandler = async (_req: EnhancedRequest, _next: NextFunction) => {
+          return new Response(JSON.stringify({
+            error: 'Method Not Allowed',
+            path: url.pathname,
+            method: req.method,
+            allowed: allowedMethods,
+          }), {
+            status: 405,
+            headers: {
+              'Content-Type': 'application/json',
+              'Allow': allowedMethods.join(', '),
+            },
+          })
+        }
+
+        if (this.globalMiddleware.length > 0) {
+          const middlewareStack = [...this.globalMiddleware, methodNotAllowedHandler]
+          const response = await this.runMiddleware(enhancedReq, middlewareStack)
+          if (response) {
+            return this.applyModifiedCookies(response, enhancedReq)
+          }
+        }
+
+        return methodNotAllowedHandler(enhancedReq, async () => new Response(null))
+      }
+
+      // No route found with any method - still run global middleware for CORS headers on 404
+      if (this.globalMiddleware.length > 0) {
+        const notFoundHandler = async (_req: EnhancedRequest, _next: NextFunction) => {
+          if (this.fallbackHandler) {
+            return await this.resolveHandler(this.fallbackHandler, enhancedReq)
+          }
+          return new Response(JSON.stringify({
+            error: 'Not Found',
+            path: url.pathname,
+            method: req.method,
+          }), {
+            status: 404,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+        const middlewareStack = [...this.globalMiddleware, notFoundHandler]
+        const response = await this.runMiddleware(enhancedReq, middlewareStack)
+        if (response) {
+          return this.applyModifiedCookies(response, enhancedReq)
+        }
+      }
+
+      // No global middleware, try the fallback handler directly
+      if (this.fallbackHandler) {
+        const response = await this.resolveHandler(this.fallbackHandler, enhancedReq)
+        return this.applyModifiedCookies(response, enhancedReq)
+      }
+
+      // No fallback handler, return a 404 with path context
+      return new Response(JSON.stringify({
+        error: 'Not Found',
+        path: url.pathname,
+        method: req.method,
+      }), {
+        status: 404,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+    catch (error) {
+      console.error('Error handling request:', error)
+
+      // Still run global middleware for CORS headers on errors
+      if (this.globalMiddleware.length > 0) {
+        const enhancedReq = this.enhanceRequest(req, {})
+        const errorHandler = async (_req: EnhancedRequest, _next: NextFunction) => {
+          if (this.errorHandler) {
+            return this.errorHandler(error as Error)
+          }
+          return new Response(JSON.stringify({
+            error: 'Internal Server Error',
+            message: error instanceof Error ? error.message : String(error),
+          }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+        const middlewareStack = [...this.globalMiddleware, errorHandler]
+        try {
+          const response = await this.runMiddleware(enhancedReq, middlewareStack)
+          if (response) {
+            return response
+          }
+        }
+        catch {
+          // Middleware itself failed, fall through to default error
+        }
+      }
+
+      // Use custom error handler if available
+      if (this.errorHandler) {
+        return this.errorHandler(error as Error)
+      }
+
+      // Default error response
+      return new Response(JSON.stringify({
+        error: 'Internal Server Error',
+        message: error instanceof Error ? error.message : String(error),
+      }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+  }
+
+  /**
+   * Get all allowed HTTP methods for a given path
+   * Used to determine if a 405 Method Not Allowed should be returned instead of 404
+   */
+  getAllowedMethods(path: string, domain?: string): string[] {
+    const url = new URL(path, 'http://localhost')
+    const methods: Set<string> = new Set()
+    const allMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
+
+    for (const method of allMethods) {
+      // Check static routes
+      if (this.staticRoutes.has(method)) {
+        const staticRoute = this.staticRoutes.get(method)!.get(url.pathname)
+        if (staticRoute && (!domain || !staticRoute.domain || staticRoute.domain === domain)) {
+          methods.add(method)
+          continue
+        }
+      }
+
+      // Get potential routes
+      const potentialRoutes: Route[] = domain && this.domains[domain]
+        ? this.domains[domain]
+        : this.routes
+
+      // Filter routes to only those matching the HTTP method
+      const methodRoutes = potentialRoutes.filter((route: Route) => route.method === method)
+
+      // Check exact match
+      for (const route of methodRoutes) {
+        if (route.path === url.pathname) {
+          methods.add(method)
+          break
+        }
+      }
+
+      // Check pattern match if not already found
+      if (!methods.has(method)) {
+        for (const route of methodRoutes) {
+          if (route.pattern) {
+            const match = route.pattern.exec(url)
+            if (match) {
+              methods.add(method)
+              break
+            }
+          }
+        }
+      }
+
+      // Check wildcard routes if not already found
+      if (!methods.has(method)) {
+        const wildcardRoutes = potentialRoutes.filter((route: Route) =>
+          route.method === method && route.path.endsWith('*'),
+        )
+
+        for (const route of wildcardRoutes) {
+          const basePath = route.path.slice(0, -1)
+          if (url.pathname.startsWith(basePath)) {
+            methods.add(method)
+            break
+          }
+        }
+      }
+    }
+
+    // If GET is allowed, HEAD is implicitly allowed too
+    if (methods.has('GET')) {
+      methods.add('HEAD')
+    }
+
+    return Array.from(methods)
+  }
+
+  /**
+   * Match a route based on the path, method, and domain
+   */
+  matchRoute(path: string, method: string, domain?: string): { route: Route, params: Record<string, string> } | undefined {
+    const url = new URL(path, 'http://localhost')
+
+    // Generate cache key
+    const cacheKey = `${domain || ''}:${method}:${url.pathname}`
+
+    // Check cache first
+    if (this.routeCache.has(cacheKey)) {
+      return this.routeCache.get(cacheKey)
+    }
+
+    // Fast path for static routes
+    if (this.staticRoutes.has(method)) {
+      const staticRoute = this.staticRoutes.get(method)!.get(url.pathname)
+      if (staticRoute && (!domain || !staticRoute.domain || staticRoute.domain === domain)) {
+        const result = {
+          route: staticRoute,
+          params: {},
+        }
+        this.routeCache.set(cacheKey, result)
+        return result
+      }
+    }
+
+    // Get potential routes - either all routes or domain-specific routes
+    const potentialRoutes: Route[] = domain && this.domains[domain]
+      ? this.domains[domain]
+      : this.routes
+
+    // Filter routes to only those matching the HTTP method
+    const methodRoutes = potentialRoutes.filter((route: Route) => route.method === method)
+
+    // First, try to find an exact match
+    for (const route of methodRoutes) {
+      if (route.path === url.pathname) {
+        const result = {
+          route,
+          params: {},
+        }
+        this.routeCache.set(cacheKey, result)
+        return result
+      }
+    }
+
+    // If no exact match, try matching patterns
+    for (const route of methodRoutes) {
+      if (route.pattern) {
+        const match = route.pattern.exec(url)
+        if (match) {
+          const result = {
+            route,
+            params: match.pathname.groups,
+          }
+          this.routeCache.set(cacheKey, result)
+          return result
+        }
+      }
+    }
+
+    // If still no match, try domain-specific * (wildcard) routes
+    if (domain && this.domains[domain]) {
+      const wildcardRoutes = this.domains[domain].filter((route: Route) =>
+        route.method === method && route.path.endsWith('*'),
+      )
+
+      for (const route of wildcardRoutes) {
+        const basePath = route.path.slice(0, -1) // Remove the '*'
+        if (url.pathname.startsWith(basePath)) {
+          const result = {
+            route,
+            params: {
+              wildcard: url.pathname.slice(basePath.length),
+            },
+          }
+          this.routeCache.set(cacheKey, result)
+          return result
+        }
+      }
+    }
+
+    // If no match in domain-specific routes, try global wildcard routes
+    const globalWildcardRoutes = this.routes.filter((route: Route) =>
+      route.method === method && route.path.endsWith('*') && (!domain || !route.domain),
+    )
+
+    for (const route of globalWildcardRoutes) {
+      const basePath = route.path.slice(0, -1) // Remove the '*'
+      if (url.pathname.startsWith(basePath)) {
+        const result = {
+          route,
+          params: {
+            wildcard: url.pathname.slice(basePath.length),
+          },
+        }
+        this.routeCache.set(cacheKey, result)
+        return result
+      }
+    }
+
+    // If no match for specific method, try HEAD for GET requests
+    if (method === 'HEAD') {
+      return this.matchRoute(path, 'GET', domain)
+    }
+
+    // No matching route found
+    return undefined
+  }
+
+  /**
+   * Enhance a request with params and other utilities
+   */
+  enhanceRequest(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
+    }
+
+    // Parse query string
+    const url = new URL(req.url)
+    const query: Record<string, string> = {}
+    url.searchParams.forEach((value, key) => {
+      query[key] = value
+    })
+
+    // Create a wrapper object that proxies to the original request
+    // This is necessary because native Request objects don't allow property assignment in Bun
+    const enhancedReq = {
+      // Proxy the native Request properties/methods
+      get url() { return req.url },
+      get method() { return req.method },
+      get headers() { return req.headers },
+      get body() { return req.body },
+      get bodyUsed() { return req.bodyUsed },
+      get cache() { return req.cache },
+      get credentials() { return req.credentials },
+      get destination() { return req.destination },
+      get integrity() { return req.integrity },
+      get keepalive() { return req.keepalive },
+      get mode() { return req.mode },
+      get redirect() { return req.redirect },
+      get referrer() { return req.referrer },
+      get referrerPolicy() { return req.referrerPolicy },
+      get signal() { return req.signal },
+      arrayBuffer: () => req.arrayBuffer(),
+      blob: () => req.blob(),
+      clone: () => req.clone(),
+      formData: () => req.formData(),
+      json: () => req.json(),
+      text: () => req.text(),
+
+      // Enhanced properties
+      params,
+      query,
+      jsonBody: null as any,
+      formBody: null as any,
+      _cookiesToSet: [] as CookieToSet[],
+      _cookiesToDelete: [] as { name: string, options: CookieOptions }[],
+
+    } as EnhancedRequest
+
+    // Helper to get all input data - needs to be defined before adding to object
+    const getAllInput = (): Record<string, any> => {
+      const input: Record<string, any> = {}
+
+      // Query parameters
+      for (const [key, value] of Object.entries(query)) {
+        input[key] = value
+      }
+
+      // JSON body
+      if (enhancedReq.jsonBody && typeof enhancedReq.jsonBody === 'object') {
+        for (const [key, value] of Object.entries(enhancedReq.jsonBody)) {
+          input[key] = value
+        }
+      }
+
+      // Form body
+      if (enhancedReq.formBody && typeof enhancedReq.formBody === 'object') {
+        for (const [key, value] of Object.entries(enhancedReq.formBody)) {
+          input[key] = value
+        }
+      }
+
+      // Route params
+      for (const [key, value] of Object.entries(params)) {
+        input[key] = value
+      }
+
+      return input
+    }
+
+    // Add cookie utilities
+    enhancedReq.cookies = {
+      get: (name: string) => getCookies()[name],
+      set: (name: string, value: string, options: CookieOptions = {}) => {
+        enhancedReq._cookiesToSet!.push({ name, value, options })
+      },
+      delete: (name: string, options: CookieOptions = {}) => {
+        enhancedReq._cookiesToDelete!.push({ name, options })
+      },
+      getAll: () => ({ ...getCookies() }),
+    }
+
+    // Add Laravel-style request methods directly to the wrapper object
+    // These are the methods that provide Laravel-like request handling
+    ;(enhancedReq as any).get = <T = any>(key: string, defaultValue?: T): T => {
+      const input = getAllInput()
+      const value = input[key]
+      return (value !== undefined ? value : defaultValue) as T
+    }
+
+    ;(enhancedReq as any).input = <T = any>(key: string, defaultValue?: T): T => {
+      const input = getAllInput()
+      const value = input[key]
+      return (value !== undefined ? value : defaultValue) as T
+    }
+
+    ;(enhancedReq as any).all = (): Record<string, any> => getAllInput()
+
+    ;(enhancedReq as any).only = <T extends Record<string, unknown>>(keys: string[]): T => {
+      const input = getAllInput()
+      const result = {} as T
+      for (const key of keys) {
+        if (key in input) {
+          (result as any)[key] = input[key]
+        }
+      }
+      return result
+    }
+
+    ;(enhancedReq as any).except = <T extends Record<string, unknown>>(keys: string[]): T => {
+      const input = getAllInput()
+      const result = { ...input } as T
+      for (const key of keys) {
+        delete (result as any)[key]
+      }
+      return result
+    }
+
+    ;(enhancedReq as any).has = (key: string | string[]): boolean => {
+      const input = getAllInput()
+      if (Array.isArray(key)) {
+        return key.every(k => k in input && input[k] !== undefined)
+      }
+      return key in input && input[key] !== undefined
+    }
+
+    ;(enhancedReq as any).hasAny = (keys: string[]): boolean => {
+      const input = getAllInput()
+      return keys.some(k => k in input && input[k] !== undefined)
+    }
+
+    ;(enhancedReq as any).filled = (key: string | string[]): boolean => {
+      const input = getAllInput()
+      const isFilled = (k: string): boolean => {
+        const value = input[k]
+        return value !== undefined && value !== null && value !== '' && !(Array.isArray(value) && value.length === 0)
+      }
+      if (Array.isArray(key)) {
+        return key.every(isFilled)
+      }
+      return isFilled(key)
+    }
+
+    ;(enhancedReq as any).missing = (key: string | string[]): boolean => {
+      const input = getAllInput()
+      if (Array.isArray(key)) {
+        return key.every(k => !(k in input) || input[k] === undefined)
+      }
+      return !(key in input) || input[key] === undefined
+    }
+
+    ;(enhancedReq as any).string = (key: string, defaultValue: string = ''): string => {
+      const input = getAllInput()
+      const value = input[key]
+      return value !== undefined && value !== null ? String(value) : defaultValue
+    }
+
+    ;(enhancedReq as any).integer = (key: string, defaultValue: number = 0): number => {
+      const input = getAllInput()
+      const value = input[key]
+      const parsed = Number.parseInt(String(value), 10)
+      return Number.isNaN(parsed) ? defaultValue : parsed
+    }
+
+    ;(enhancedReq as any).float = (key: string, defaultValue: number = 0): number => {
+      const input = getAllInput()
+      const value = input[key]
+      const parsed = Number.parseFloat(String(value))
+      return Number.isNaN(parsed) ? defaultValue : parsed
+    }
+
+    ;(enhancedReq as any).boolean = (key: string, defaultValue: boolean = false): boolean => {
+      const input = getAllInput()
+      const value = input[key]
+      if (value === undefined || value === null)
+        return defaultValue
+      if (typeof value === 'boolean')
+        return value
+      if (value === 'true' || value === '1' || value === 1)
+        return true
+      if (value === 'false' || value === '0' || value === 0)
+        return false
+      return defaultValue
+    }
+
+    ;(enhancedReq as any).array = <T = unknown>(key: string): T[] => {
+      const input = getAllInput()
+      const value = input[key]
+      if (Array.isArray(value))
+        return value as T[]
+      return value !== undefined && value !== null ? [value as T] : []
+    }
+
+    ;(enhancedReq as any).bearerToken = (): string | null => {
+      const authHeader
+        = req.headers.get('authorization')
+        || req.headers.get('Authorization')
+        || ''
+      if (authHeader.startsWith('Bearer '))
+        return authHeader.substring(7)
+      return null
+    }
+
+    ;(enhancedReq as any).header = (name: string): string | null => {
+      return req.headers.get(name) || req.headers.get(name.toLowerCase()) || null
+    }
+
+    // Convenience cookie reader. The full `enhancedReq.cookies.get(name)` API
+    // is also available below — `cookie(name)` is the shorter form callers
+    // (and the Laravel-style macros) reach for first, so it deserves a
+    // direct method on the enhanced request, not just on the macros class.
+    ;(enhancedReq as any).cookie = (name: string, defaultValue?: string): string | null => {
+      const value = getCookies()[name]
+      return value !== undefined ? value : (defaultValue ?? null)
+    }
+
+    ;(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).params = params || {}
+
+    return enhancedReq as EnhancedRequest
+  }
+
+  /**
+   * Apply modified cookies to a response
+   */
+  applyModifiedCookies(response: Response, req: EnhancedRequest): Response {
+    // Clone the response to modify headers
+    const newResponse = new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    })
+
+    // Apply cookies to set
+    if (req._cookiesToSet && req._cookiesToSet.length > 0) {
+      for (const { name, value, options } of req._cookiesToSet) {
+        const cookieString = this.serializeCookie(name, value, options)
+        newResponse.headers.append('Set-Cookie', cookieString)
+      }
+    }
+
+    // Apply cookies to delete
+    if (req._cookiesToDelete && req._cookiesToDelete.length > 0) {
+      for (const { name, options } of req._cookiesToDelete) {
+        const deletionOptions = {
+          ...options,
+          expires: new Date(0), // Set expiration to past date
+          maxAge: 0,
+        }
+        const cookieString = this.serializeCookie(name, '', deletionOptions)
+        newResponse.headers.append('Set-Cookie', cookieString)
+      }
+    }
+
+    return newResponse
+  }
+
+  /**
+   * Serialize a cookie for the Set-Cookie header
+   */
+  serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+    let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+
+    if (options.maxAge !== undefined) {
+      cookie += `; Max-Age=${options.maxAge}`
+    }
+
+    if (options.expires && options.expires instanceof Date) {
+      cookie += `; Expires=${options.expires.toUTCString()}`
+    }
+
+    if (options.path) {
+      cookie += `; Path=${options.path}`
+    }
+    else {
+      cookie += '; Path=/'
+    }
+
+    if (options.domain) {
+      cookie += `; Domain=${options.domain}`
+    }
+
+    if (options.secure) {
+      cookie += '; Secure'
+    }
+
+    if (options.httpOnly) {
+      cookie += '; HttpOnly'
+    }
+
+    if (options.sameSite) {
+      const sameSite = options.sameSite.toLowerCase()
+      cookie += `; SameSite=${sameSite.charAt(0).toUpperCase() + sameSite.slice(1)}`
+    }
+
+    return cookie
+  }
+
+  /**
+   * Build an optimized middleware chain
+   */
+  buildMiddlewareChain(middlewares: MiddlewareHandler[]): (req: EnhancedRequest) => Promise<Response | null> {
+    if (middlewares.length === 0) {
+      return async (_req: EnhancedRequest) => null
+    }
+
+    // Build the chain from the end to start for better performance
+    let chain = async (_req: EnhancedRequest): Promise<Response | null> => null
+
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+      const middleware = middlewares[i]
+      const nextChain = chain
+      chain = async (req: EnhancedRequest): Promise<Response | null> => {
+        const next = async (): Promise<Response> => {
+          const result = await nextChain(req)
+          return result || new Response(null, { status: 200 })
+        }
+        return middleware(req, next)
+      }
+    }
+
+    return chain
+  }
+
+  /**
+   * Run middleware stack for a request
+   */
+  async runMiddleware(req: EnhancedRequest, middlewareStack: MiddlewareHandler[]): Promise<Response | null> {
+    if (middlewareStack.length === 0) {
+      return null // No middleware to run
+    }
+
+    try {
+      // Build and execute optimized middleware chain
+      const chain = this.buildMiddlewareChain(middlewareStack)
+      return await chain(req)
+    }
+    catch (error) {
+      if (this.errorHandler) {
+        return this.errorHandler(error as Error)
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Resolve an action handler
+   */
+  async resolveHandler(handler: ActionHandler, req: EnhancedRequest): Promise<Response> {
+    // If it's a function, call it with the request
+    if (typeof handler === 'function' && !(handler as { prototype?: { handle?: unknown } }).prototype?.handle) {
+      return await (handler as (req: EnhancedRequest) => Response | Promise<Response>)(req)
+    }
+
+    // If it's a class constructor, instantiate it and call handle
+    if (typeof handler === 'function' && (handler as { prototype?: { handle?: unknown } }).prototype?.handle) {
+      const HandlerClass = handler as new () => { handle: (req: EnhancedRequest) => Response | Promise<Response> }
+      const handlerInstance = new HandlerClass()
+      return await handlerInstance.handle(req)
+    }
+
+    // If it's an object with a handle method
+    if (handler && typeof (handler as unknown as { handle?: unknown }).handle === 'function') {
+      return await (handler as unknown as { handle: (req: EnhancedRequest) => Response | Promise<Response> }).handle(req)
+    }
+
+    throw new Error(`Invalid action handler: ${typeof handler}`)
+  }
+
+  /**
+   * Add middleware to the router
+   */
+  use(...middleware: (string | MiddlewareHandler)[]): Router {
+    for (const mw of middleware) {
+      const resolvedMiddleware = this.resolveMiddleware(mw)
+      if (resolvedMiddleware) {
+        this.globalMiddleware.push(resolvedMiddleware)
+      }
+    }
+    return this
+  }
+
+  /**
+   * Create a route group with prefix and middleware
+   */
+  group(options: { prefix?: string, middleware?: (string | MiddlewareHandler)[] }, callback: () => void | Promise<void>): Router {
+    // Save current group state
+    const previousGroup = this.currentGroup
+
+    // Create new group
+    this.currentGroup = {
+      prefix: options.prefix || '',
+      middleware: [],
+    }
+
+    // Resolve middleware if provided
+    if (options.middleware) {
+      for (const mw of options.middleware) {
+        if (typeof mw === 'function') {
+          this.currentGroup.middleware!.push(mw)
+        }
+      }
+    }
+
+    // Execute callback
+    const result = callback()
+
+    // Handle async callbacks
+    if (result instanceof Promise) {
+      result.then(() => {
+        this.currentGroup = previousGroup
+      })
+    }
+    else {
+      // Restore previous group state
+      this.currentGroup = previousGroup
+    }
+
+    return this
+  }
+
+  /**
+   * Add route to the router
+   */
+  addRoute(route: Route): this {
+    this.routes.push(route)
+    if (route.name) {
+      this.namedRoutes.set(route.name, route)
+      registerNamedRoute(route.name, route.path)
+    }
+    return this
+  }
+
+  /**
+   * Register middleware dependency
+   */
+  registerMiddlewareDependency(dependency: MiddlewareDependency): this {
+    if (this._middlewarePipeline) {
+      this._middlewarePipeline.registerDependency(dependency)
+    }
+    return this
+  }
+
+  /**
+   * Register middleware skip conditions
+   */
+  registerMiddlewareSkipConditions(_middlewareName: string, _conditions: MiddlewareSkipCondition[]): this {
+    // Implementation would register skip conditions with the pipeline
+    return this
+  }
+
+  /**
+   * Get middleware statistics
+   */
+  getMiddlewareStats(): MiddlewarePipelineStats | Record<string, never> {
+    if (this._middlewarePipeline) {
+      return this._middlewarePipeline.getStats()
+    }
+    return {}
+  }
+
+  /**
+   * Get middleware cache info
+   */
+  getMiddlewareCacheInfo(): MiddlewareCacheInfo {
+    // Return cache info based on compiled pipelines
+    return {
+      size: 0,
+      routes: [],
+      hitRate: 0,
+    }
+  }
+
+  /**
+   * Clear middleware cache
+   */
+  clearMiddlewareCache(): this {
+    if (this._middlewarePipeline) {
+      this._middlewarePipeline.clear()
+    }
+    return this
+  }
+
+  /**
+   * Execute middleware pipeline
+   */
+  async executeMiddleware(middleware: MiddlewareHandler[], request: EnhancedRequest, handler: () => Promise<Response>): Promise<Response> {
+    if (middleware.length === 0) {
+      return handler()
+    }
+
+    let currentIndex = 0
+
+    const next = async (): Promise<Response> => {
+      if (currentIndex >= middleware.length) {
+        return handler()
+      }
+
+      const mw = middleware[currentIndex++]
+      const result = await mw(request, next)
+      return result || new Response('No response from middleware', { status: 500 })
+    }
+
+    return next()
+  }
+}
+
+/**
+ * Builder for conditional middleware
+ */
+export class ConditionalBuilder {
+  constructor(
+    private router: Router,
+    private condition: MiddlewareCondition,
+  ) {}
+
+  middleware(middlewareName: string): this {
+    const [name, params] = middlewareName.split(':')
+    const middlewareFactory = (this.router as any).namedMiddleware.get(name)
+
+    if (!middlewareFactory) {
+      throw new Error(`Unknown middleware: ${name}`)
+    }
+
+    const middlewareHandler = middlewareFactory(params);
+    (this.router as any).conditionalMiddleware.push({
+      condition: this.condition,
+      middleware: [middlewareHandler],
+    })
+
+    return this
+  }
+}
+
+/**
+ * Builder for middleware with parameters
+ */
+export class MiddlewareBuilder {
+  constructor(
+    private router: Router,
+    private middleware: MiddlewareHandler[],
+  ) {}
+
+  get(_path: string, _handler: RouteHandler): this {
+    // This would integrate with the router's route registration
+    return this
+  }
+
+  post(_path: string, _handler: RouteHandler): this {
+    return this
+  }
+
+  put(_path: string, _handler: RouteHandler): this {
+    return this
+  }
+
+  delete(_path: string, _handler: RouteHandler): this {
+    return this
+  }
+}
+
+/**
+ * Builder for route groups with middleware
+ */
+export class RouteGroupBuilder {
+  constructor(
+    private router: Router,
+    private middleware: MiddlewareHandler[],
+  ) {}
+
+  get(_path: string, _handler: RouteHandler): this {
+    // This would integrate with the router's route registration
+    return this
+  }
+
+  post(_path: string, _handler: RouteHandler): this {
+    return this
+  }
+
+  put(_path: string, _handler: RouteHandler): this {
+    return this
+  }
+
+  delete(_path: string, _handler: RouteHandler): this {
+    return this
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Standalone enhancement helper
+// ---------------------------------------------------------------------------
+
+// Singleton scratch Router used to expose `enhanceRequest` as a standalone
+// function. Downstream consumers (frameworks layered on bun-router) often
+// need to attach the request macros to a request that was created outside
+// of `route.serve()` — for instance, when a higher-level router wraps
+// each handler with its own middleware chain. Without an exported function,
+// those consumers either spin up their own `new Router()` per call or
+// duplicate the attachment logic in user code.
+//
+// We share one instance because `enhanceRequest` does not depend on any
+// per-router state (route table, middleware groups, etc.) — it only reads
+// from the request and the supplied params.
+let _enhancementHost: Router | null = null
+
+function getEnhancementHost(): Router {
+  if (_enhancementHost === null) _enhancementHost = new Router()
+  return _enhancementHost
+}
+
+/**
+ * Attach bun-router's request macros (`bearerToken`, `getParam`, `cookie`,
+ * `cookies`, `header`, `params`, plus the Laravel-style input helpers
+ * `get`, `input`, `string`, `integer`, `float`, `boolean`, `array`, `has`,
+ * `filled`, etc.) to a request.
+ *
+ * Idempotent: calling on an already-enhanced request returns it unchanged.
+ * We sniff `req.bearerToken` as the marker — cheap and reliable since no
+ * native Request has it.
+ *
+ * @example
+ * import { applyRequestEnhancements } from '@stacksjs/bun-router'
+ *
+ * const enhanced = applyRequestEnhancements(req, { id: '42' })
+ * enhanced.bearerToken()  // → string | null
+ * enhanced.getParam('id') // → '42'
+ */
+export function applyRequestEnhancements(
+  req: Request | EnhancedRequest,
+  params: Record<string, string> = {},
+): EnhancedRequest {
+  if (typeof (req as any).bearerToken === 'function')
+    return req as EnhancedRequest
+  return getEnhancementHost().enhanceRequest(req as Request, params)
+}