@stacksjs/bun-router 0.0.15 → 0.0.17

package/src/router/group-organization.ts

@@ -38,7 +38,23 @@ export function registerGroupOrganization(RouterClass: typeof Router): void {
         this.currentGroup = newGroup
 
         // Execute the callback to register routes in this group
-        callback()
+        const result = callback() as unknown
+
+        // Async callbacks (e.g. `register()`'s dynamic import) register
+        // their routes after this call returns — the group must stay
+        // active until the promise settles, and callers must await.
+        if (result instanceof Promise) {
+          return result.then(
+            () => {
+              this.currentGroup = previousGroup
+              return this
+            },
+            (error: unknown) => {
+              this.currentGroup = previousGroup
+              throw error
+            },
+          ) as unknown as Router
+        }
 
         // Restore the previous group
         this.currentGroup = previousGroup

package/src/router/handler-resolver.ts

@@ -289,3 +289,39 @@ async function resolveStringHandler(
 export function createHandlerResolver(config: RouterConfig): (handler: unknown, req: EnhancedRequest) => Promise<Response> {
   return (handler: unknown, req: EnhancedRequest) => resolveHandler(handler, req, config)
 }
+
+/**
+ * Precompile the dispatch branch for a handler whose shape never changes
+ * (a registered route's handler). `resolveHandler` re-sniffs the handler
+ * type — instanceof / typeof / prototype checks — on every request; this
+ * resolves the branch once and returns a specialized invoker for the
+ * per-request hot path.
+ */
+export function createHandlerInvoker(
+  handler: unknown,
+  config: RouterConfig,
+): (req: EnhancedRequest) => Promise<Response> {
+  // Static Response routes
+  if (handler instanceof Response) {
+    return async () => handler.clone() as Response
+  }
+
+  // Plain function handlers (the common case)
+  if (isCallableHandler(handler)) {
+    return async (req: EnhancedRequest) => wrapResponse(await handler(req))
+  }
+
+  // Class constructors with a handle() method
+  if (
+    typeof handler === 'function'
+    && handler.prototype
+    && typeof handler.prototype.handle === 'function'
+  ) {
+    const HandlerClass = handler as new () => { handle: (req: EnhancedRequest) => unknown }
+    return async (req: EnhancedRequest) => wrapResponse(await new HandlerClass().handle(req))
+  }
+
+  // Strings (action paths, Controller@method) and anything exotic keep
+  // the full resolution flow
+  return (req: EnhancedRequest) => resolveHandler(handler, req, config)
+}

package/src/router/http-methods.ts

@@ -147,13 +147,17 @@ export function registerHttpMethods(RouterClass: typeof Router): void {
           registerNamedRoute(name, route.path)
         }
 
-        // Add to optimized route compiler if available
-        if (this.addRouteToCompiler) {
+        // Add to optimized route compiler if available. Domain-scoped routes
+        // stay out of the shared trie — its cache is keyed by method+path
+        // only, so a domain route in the trie could be served to the wrong
+        // host. They are matched by the domain-aware fallback instead.
+        if (this.addRouteToCompiler && !domain) {
           this.addRouteToCompiler(route)
         }
 
-        // Clear route cache when new routes are added
+        // Clear route caches when new routes are added
         this.routeCache.clear()
+        this._allowedMethodsCache?.clear()
 
         return this
       },
@@ -251,6 +255,23 @@ export function registerHttpMethods(RouterClass: typeof Router): void {
       configurable: true,
     },
 
+    // HTTP HEAD method. Note: GET routes already answer HEAD requests
+    // automatically — register an explicit HEAD route only when the HEAD
+    // behavior must differ from GET.
+    head: {
+      value(
+        path: string,
+        handler: ActionHandler,
+        type?: 'api' | 'web',
+        name?: string,
+        middleware?: (string | MiddlewareHandler)[],
+      ): Router {
+        return this.addRoute('HEAD', path, handler, type, name, middleware)
+      },
+      writable: true,
+      configurable: true,
+    },
+
     // Register a route that responds to multiple HTTP methods
     match: {
       value(
@@ -311,6 +332,15 @@ export function registerHttpMethods(RouterClass: typeof Router): void {
           url = url.replace(`{${param}?}`, encodeURIComponent(value))
         }
 
+        // Drop unfilled optional placeholders and tidy up the slashes
+        // they leave behind (`/posts/{page?}` → `/posts`)
+        if (url.includes('{')) {
+          url = url.replace(/\{[^}]+\?\}/g, '').replace(/\/{2,}/g, '/')
+          if (url.length > 1 && url.endsWith('/')) {
+            url = url.slice(0, -1)
+          }
+        }
+
         return url
       },
       writable: true,

package/src/router/index.ts

@@ -140,6 +140,9 @@ declare module './router' {
     renderView: (view: string, data?: Record<string, any>, options?: { layout?: string }) => Promise<string>
     view: (path: string, view: string, data?: Record<string, any>, options?: { layout?: string, status?: number, headers?: Record<string, string> }) => Router
 
+    // Keep the most recently registered route off the native route table
+    withoutNativeDispatch: () => Router
+
     // Route constraint methods
     where: ((_param: string, _pattern: string | RegExp) => Router) & ((constraints: Record<string, string | RegExp>) => Router)
     whereNumber: (param: string) => Router
@@ -162,6 +165,9 @@ declare module './router' {
       edit?: ActionHandler
     }) => Router
 
+    // HTTP HEAD method (GET routes already answer HEAD automatically)
+    head: (path: string, handler: ActionHandler, type?: 'api' | 'web', name?: string, middleware?: any[]) => Router
+
     // Redirect and utility methods
     onError: (handler: (error: Error) => Response | Promise<Response>) => Router
     redirect: (url: string, status?: 301 | 302 | 303 | 307 | 308) => Response

package/src/router/middleware.ts

@@ -18,6 +18,9 @@ export function registerMiddlewareHandling(RouterClass: typeof Router): void {
             this.globalMiddleware.push(resolvedMiddleware)
           }
         }
+        // Invalidate per-route compiled middleware chains — they bake in
+        // the global middleware stack as of build time
+        this._mwEpoch = (this._mwEpoch || 0) + 1
         return this
       },
       writable: true,

package/src/router/optimized-route-matching.ts

@@ -46,20 +46,38 @@ export function registerOptimizedRouteMatching(RouterClass: typeof Router): void
       value(path: string, method: HTTPMethod, domain?: string): MatchResult | undefined {
         this.initializeRouteCompiler()
 
-        // Use the optimized compiler for matching
-        const match = this.routeCompiler.match(path, method)
+        // Domain-scoped routes are matched by the domain-aware fallback.
+        // The trie (and its cache key) is method+path only, so letting it
+        // answer for hosts with registered domain routes would let one
+        // domain's cached match poison another's.
+        if (domain && this.domains[domain]) {
+          const domainMatch = this.fallbackMatchRoute(path, method, domain)
+          if (domainMatch) {
+            return domainMatch
+          }
+        }
+        else {
+          // Use the optimized compiler for matching
+          const match = this.routeCompiler.match(path, method)
 
-        if (match) {
-          // Check domain constraints if specified
-          if (domain && match.route.domain && match.route.domain !== domain) {
-            return undefined
+          if (match && (!domain || !match.route.domain || match.route.domain === domain)) {
+            return match
           }
 
-          return match
+          // Fallback to original matching for edge cases (optional params, etc.)
+          const fallback = this.fallbackMatchRoute(path, method, domain)
+          if (fallback) {
+            return fallback
+          }
+        }
+
+        // A HEAD request is served by the matching GET route when no
+        // explicit HEAD route exists (RFC 9110 §9.3.2)
+        if (method === 'HEAD') {
+          return this.matchRoute(path, 'GET', domain)
         }
 
-        // Fallback to original matching for edge cases
-        return this.fallbackMatchRoute(path, method, domain)
+        return undefined
       },
       writable: true,
       configurable: true,
@@ -80,6 +98,12 @@ export function registerOptimizedRouteMatching(RouterClass: typeof Router): void
           return this.routeCache.get(cacheKey)
         }
 
+        // Bound the legacy cache — high-cardinality dynamic paths would
+        // otherwise grow it without limit
+        if (this.routeCache.size >= 10_000) {
+          this.routeCache.clear()
+        }
+
         // Fast path for static routes
         if (this.staticRoutes.has(method)) {
           const staticRoute = this.staticRoutes.get(method)!.get(url.pathname)
@@ -128,6 +152,31 @@ export function registerOptimizedRouteMatching(RouterClass: typeof Router): void
           }
         }
 
+        // Try wildcard routes — domain-scoped first, then global
+        const wildcardPools: Route[][] = domain && this.domains[domain]
+          ? [this.domains[domain], this.routes]
+          : [this.routes]
+
+        for (const pool of wildcardPools) {
+          for (const route of pool) {
+            if (route.method !== method || !route.path.endsWith('*')) {
+              continue
+            }
+            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
+            }
+          }
+        }
+
+        // Cache the miss too — repeated requests for an unknown path skip
+        // the full scan (the cache is cleared whenever routes change)
+        this.routeCache.set(cacheKey, undefined)
         return undefined
       },
       writable: true,

package/src/router/route-compiler.ts

@@ -11,6 +11,12 @@ export interface RouteCompilerOptions {
   enablePriorityOptimization: boolean
   cacheSize: number
   precompilePatterns: boolean
+  /**
+   * Record per-match timing via `performance.now()`. Off by default —
+   * timing every request costs two clock reads per match on the hot path.
+   * Match/hit/miss counters are always collected (they're just integers).
+   */
+  enableProfiling: boolean
 }
 
 /**
@@ -30,8 +36,16 @@ export interface RouteMatchStats {
  */
 export class RouteCompiler {
   private trie: RouteTrie
+  // Bounded match cache with FIFO eviction (oldest key in Map iteration
+  // order). Cache hits are pure reads — refreshing recency on every hit
+  // (true LRU) costs a delete+set per request and buys almost nothing
+  // for route tables, where the hot set is small and stable. The old
+  // implementation kept a `cacheKeys` array whose indexOf/splice
+  // bookkeeping cost O(cacheSize) on every request.
   private matchCache: Map<string, MatchResult | null> = new Map()
-  private cacheKeys: string[] = [] // For LRU tracking
+  // O(1) duplicate detection by `method:path` (the old approach scanned
+  // every compiled route on each addRoute call — O(n²) registration).
+  private routeKeys: Set<string> = new Set()
   private stats: RouteMatchStats = {
     totalMatches: 0,
     cacheHits: 0,
@@ -50,6 +64,7 @@ export class RouteCompiler {
       enablePriorityOptimization: true,
       cacheSize: 1000,
       precompilePatterns: true,
+      enableProfiling: false,
       ...options,
     }
 
@@ -66,11 +81,12 @@ export class RouteCompiler {
       this.precompileRoutePattern(route)
     }
 
-    // Check for exact duplicates before adding
-    const isDuplicate = this.checkForDuplicateRoute(route)
-    if (isDuplicate) {
+    // Check for exact duplicates before adding — O(1) set lookup
+    const routeKey = `${route.method}:${route.path}`
+    if (this.routeKeys.has(routeKey)) {
       return false
     }
+    this.routeKeys.add(routeKey)
 
     // Add to trie for fast matching
     this.trie.addRoute(route)
@@ -87,24 +103,6 @@ export class RouteCompiler {
     return true
   }
 
-  /**
-   * Check if a route is an exact duplicate of an existing route
-   */
-  private checkForDuplicateRoute(route: Route): boolean {
-    const routes = this.trie.getAllRoutes()
-
-    for (const existingRoute of routes) {
-      if (
-        existingRoute.route.path === route.path
-        && existingRoute.route.method === route.method
-      ) {
-        return true
-      }
-    }
-
-    return false
-  }
-
   /**
    * Pre-compile route patterns for faster matching
    */
@@ -191,24 +189,33 @@ export class RouteCompiler {
     path: string,
     constraints?: Record<string, string>,
   ): { exec: (pathname: string) => { groups?: Record<string, string> } | null } {
-    // Convert {param} to named capture groups and {param:pattern} to constrained capture groups
-    let regexPattern = path.replace(/\{([^}:]+)(?::([^}]+))?\}/g, (_match, name, ..._args) => {
-      const pattern = _args[0]
-      // If there's a constraint for this parameter, use it instead of the default pattern
-      if (constraints && constraints[name]) {
-        return `(?<${name}>${constraints[name]})`
-      }
-      // If there's an inline pattern in the route path, use it
-      else if (pattern) {
-        return `(?<${name}>${pattern})`
-      }
-      // Default pattern for parameters without constraints
-      return `(?<${name}>[^/]+)`
+    // Pull params out as placeholder tokens so the static text can be
+    // regex-escaped safely — without this, a literal dot in a path like
+    // `/api/v1.0/users` would match any character.
+    const paramTokens: string[] = []
+    const withTokens = path.replace(/\{([^}]+)\}/g, (_m, inner: string) => {
+      paramTokens.push(inner)
+      return `\u0000${paramTokens.length - 1}\u0000`
+    })
+
+    let regexPattern = withTokens.replace(/[.+*?^${}()|[\]\\]/g, '\\$&')
+
+    // Convert placeholder tokens to named capture groups. Optional params
+    // (`{id?}`) make both the parameter and its leading slash optional.
+    regexPattern = regexPattern.replace(/\/?\u0000(\d+)\u0000/g, (token, idx: string) => {
+      const inner = paramTokens[Number(idx)]
+      const isOptional = inner.endsWith('?')
+      const core = isOptional ? inner.slice(0, -1) : inner
+      const colonIndex = core.indexOf(':')
+      const name = colonIndex === -1 ? core : core.slice(0, colonIndex)
+      const inlinePattern = colonIndex === -1 ? undefined : core.slice(colonIndex + 1)
+      const pattern = constraints?.[name] ?? inlinePattern ?? '[^/]+'
+      const group = `(?<${name}>${pattern})`
+      const leadingSlash = token.startsWith('/') ? '/' : ''
+      return isOptional ? `(?:${leadingSlash}${group})?` : `${leadingSlash}${group}`
     })
 
-    // Escape forward slashes and add anchors
-    regexPattern = `^${regexPattern.replace(/\//g, '\\/')}$`
-    const regex = new RegExp(regexPattern)
+    const regex = new RegExp(`^${regexPattern}$`)
 
     return {
       exec: (pathname: string) => {
@@ -227,21 +234,20 @@ export class RouteCompiler {
    * Match a request path and method to a route
    */
   match(path: string, method: HTTPMethod): MatchResult | null {
-    const startTime = performance.now()
+    const startTime = this.options.enableProfiling ? performance.now() : 0
     this.stats.totalMatches++
 
     // Check cache first if enabled
     if (this.options.enableCaching) {
       const cacheKey = `${method}:${path}`
-      if (this.matchCache.has(cacheKey)) {
+      const cached = this.matchCache.get(cacheKey)
+      if (cached !== undefined || this.matchCache.has(cacheKey)) {
         this.stats.cacheHits++
-
-        // Update LRU order - move this key to the end (most recently used)
-        this.updateCacheLRU(cacheKey)
-
-        const cached = this.matchCache.get(cacheKey)
-        this.updateMatchTime(startTime)
-        return cached || null
+        if (startTime)
+          this.updateMatchTime(startTime)
+        // Hand each request its own params object — cached results are
+        // shared, and handlers are allowed to mutate `req.params`.
+        return cached ? { route: cached.route, params: { ...cached.params } } : null
       }
       this.stats.cacheMisses++
     }
@@ -263,46 +269,29 @@ export class RouteCompiler {
       this.addToCache(cacheKey, result)
     }
 
-    this.updateMatchTime(startTime)
-    return result
+    if (startTime)
+      this.updateMatchTime(startTime)
+    return result ? { route: result.route, params: { ...result.params } } : null
   }
 
   /**
    * Add an entry to the cache with LRU eviction if needed
    */
   private addToCache(key: string, value: MatchResult | null): void {
-    // If cache is full, evict least recently used item
+    // If cache is full, evict the least recently used entry (oldest key
+    // in Map iteration order)
     if (this.matchCache.size >= this.options.cacheSize && !this.matchCache.has(key)) {
-      // Remove least recently used item (first in array)
-      if (this.cacheKeys.length > 0) {
-        const lruKey = this.cacheKeys.shift()!
+      const lruKey = this.matchCache.keys().next().value
+      if (lruKey !== undefined) {
         this.matchCache.delete(lruKey)
       }
     }
 
-    // Add new item to cache
     this.matchCache.set(key, value)
-
-    // Update LRU tracking
-    this.updateCacheLRU(key)
-  }
-
-  /**
-   * Update LRU tracking for a cache key
-   */
-  private updateCacheLRU(key: string): void {
-    // Remove key from current position if it exists
-    const index = this.cacheKeys.indexOf(key)
-    if (index !== -1) {
-      this.cacheKeys.splice(index, 1)
-    }
-
-    // Add key to end of array (most recently used)
-    this.cacheKeys.push(key)
   }
 
   /**
-   * Update average match time statistics
+   * Update average match time statistics (only when profiling is enabled)
    */
   private updateMatchTime(startTime: number): void {
     const matchTime = performance.now() - startTime
@@ -419,7 +408,7 @@ export class RouteCompiler {
   clear(): void {
     this.trie.clear()
     this.matchCache.clear()
-    this.cacheKeys = []
+    this.routeKeys.clear()
     this.stats = {
       totalMatches: 0,
       cacheHits: 0,

package/src/router/route-matching.ts

@@ -5,6 +5,7 @@ import { matchPath } from '../utils'
 /**
  * Route matching extension for Router class
  */
+// eslint-disable-next-line pickier/no-unused-vars -- false positive: used on the next line
 export function registerRouteMatching(RouterClass: typeof Router): void {
   Object.defineProperties(RouterClass.prototype, {
     /**
@@ -291,6 +292,24 @@ export function registerRouteMatching(RouterClass: typeof Router): void {
       configurable: true,
     },
 
+    /**
+     * Keep the most recently registered route on the fetch-handler
+     * matcher even when serving with `nativeRoutes: true`. Useful when a
+     * route must respect registration-order precedence against an
+     * overlapping pattern (Bun's native router resolves by specificity).
+     */
+    withoutNativeDispatch: {
+      value(): Router {
+        const lastRoute = this.routes[this.routes.length - 1]
+        if (lastRoute) {
+          lastRoute.nativeDispatch = false
+        }
+        return this
+      },
+      writable: true,
+      configurable: true,
+    },
+
     /**
      * Apply a numeric constraint to a parameter
      */

package/src/router/route-trie.ts

@@ -290,7 +290,13 @@ export class RouteTrie {
   }
 
   /**
-   * Recursively match path segments
+   * Recursively match path segments.
+   *
+   * Candidates are tried in specificity order — static, then parameter,
+   * then wildcard — and the first full match wins. This both fixes the
+   * old behavior (where a wildcard sibling could shadow a static route)
+   * and avoids allocating candidate arrays and params copies per segment:
+   * `params` is mutated in place and rolled back on backtrack.
    */
   private matchSegments(
     node: TrieNode,
@@ -313,65 +319,45 @@ export class RouteTrie {
     }
 
     const segment = segments[segmentIndex]
-    const candidates: Array<{ node: TrieNode, newParams: Record<string, string> }> = []
 
     // Try static match first (highest priority)
-    if (node.children.has(segment)) {
-      candidates.push({
-        node: node.children.get(segment)!,
-        newParams: { ...params },
-      })
+    const staticChild = node.children.get(segment)
+    if (staticChild) {
+      const match = this.matchSegments(staticChild, segments, segmentIndex + 1, params, method)
+      if (match)
+        return match
     }
 
     // Try parameter match
-    if (node.paramChild) {
-      const paramNode = node.paramChild
-      let matches = true
-
-      if (paramNode.pattern) {
-        matches = paramNode.pattern.test(segment)
-      }
-
-      if (matches && paramNode.paramName) {
-        candidates.push({
-          node: paramNode,
-          newParams: { ...params, [paramNode.paramName]: segment },
-        })
-      }
-    }
-
-    // Try wildcard match (lowest priority)
-    if (node.wildcardChild) {
-      const remainingPath = segments.slice(segmentIndex).join('/')
-      const match = this.matchSegments(
-        node.wildcardChild,
-        [], // Empty segments for wildcard - it matches everything
-        0,
-        { ...params, wildcard: remainingPath },
-        method,
-      )
+    const paramNode = node.paramChild
+    if (paramNode && paramNode.paramName
+      && (!paramNode.pattern || paramNode.pattern.test(segment))) {
+      const previous = params[paramNode.paramName]
+      params[paramNode.paramName] = segment
+      const match = this.matchSegments(paramNode, segments, segmentIndex + 1, params, method)
       if (match)
         return match
+      // Backtrack: restore params before trying lower-priority branches
+      if (previous === undefined)
+        delete params[paramNode.paramName]
+      else
+        params[paramNode.paramName] = previous
     }
 
-    // Try all candidates and return the best match
-    let bestMatch: RouteMatch | null = null
-
-    for (const candidate of candidates) {
-      const match = this.matchSegments(
-        candidate.node,
-        segments,
-        segmentIndex + 1,
-        candidate.newParams,
-        method,
-      )
-
-      if (match && (!bestMatch || match.score > bestMatch.score)) {
-        bestMatch = match
+    // Try wildcard match (lowest priority) — consumes all remaining segments
+    if (node.wildcardChild) {
+      const compiled = node.wildcardChild.getRoute(method)
+      if (compiled) {
+        params.wildcard = segments.slice(segmentIndex).join('/')
+        return {
+          route: compiled.route,
+          params,
+          score: compiled.priority,
+        }
       }
     }
 
-    return bestMatch
+    return null
   }
 
   /**