@stacksjs/bun-router 0.0.15 → 0.0.17

package/src/request/macros.ts

@@ -9,6 +9,58 @@ import type { EnhancedRequest } from '../types'
 export interface RequestMacro {
   name: string
   handler: (this: EnhancedRequest, ...args: any[]) => any
+  /**
+   * Accessor macros are installed as getters on the macro prototype —
+   * `req.<name>` invokes the handler instead of returning a function.
+   * Assignment shadows the accessor with an own property.
+   */
+  accessor?: boolean
+}
+
+// Hoisted hot-path helpers — compiled once instead of per call
+const MOBILE_REGEX = /Mobile|Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i
+const BOT_REGEX = /bot|crawler|spider|crawling/i
+const GLOB_PATTERN_CACHE = new Map<string, RegExp>()
+
+/** Parsed-state cache slots attached to a request on first use. */
+interface RequestParseCache {
+  _parsedURL?: URL
+  _parsedCookies?: Record<string, string>
+}
+
+export function getParsedURL(req: EnhancedRequest): URL {
+  const cache = req as EnhancedRequest & RequestParseCache
+  if (!cache._parsedURL) {
+    cache._parsedURL = new URL(req.url)
+  }
+  return cache._parsedURL
+}
+
+export function getParsedCookies(req: EnhancedRequest): Record<string, string> {
+  const cache = req as EnhancedRequest & RequestParseCache
+  if (!cache._parsedCookies) {
+    const cookies: Record<string, string> = {}
+    const cookieHeader = req.headers.get('cookie')
+    if (cookieHeader) {
+      for (const cookie of cookieHeader.split(';')) {
+        const eqIndex = cookie.indexOf('=')
+        if (eqIndex === -1)
+          continue
+        const key = cookie.slice(0, eqIndex).trim()
+        if (!key)
+          continue
+        const value = cookie.slice(eqIndex + 1).trim()
+        try {
+          cookies[key] = decodeURIComponent(value)
+        }
+        catch {
+          cookies[key] = value
+        }
+      }
+    }
+    cache._parsedCookies = cookies
+  }
+  return cache._parsedCookies
 }
 
 /**
@@ -16,12 +68,15 @@ export interface RequestMacro {
  */
 class RequestMacroRegistry {
   private macros: Map<string, RequestMacro> = new Map()
+  // Bumped on every mutation so cached macro prototypes can be rebuilt
+  private epoch = 0
 
   /**
    * Register a request macro
    */
-  register(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any): void {
-    this.macros.set(name, { name, handler })
+  register(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any, accessor = false): void {
+    this.macros.set(name, { name, handler, accessor })
+    this.epoch++
   }
 
   /**
@@ -49,7 +104,10 @@ class RequestMacroRegistry {
    * Remove a macro
    */
   remove(name: string): boolean {
-    return this.macros.delete(name)
+    const removed = this.macros.delete(name)
+    if (removed)
+      this.epoch++
+    return removed
   }
 
   /**
@@ -57,6 +115,14 @@ class RequestMacroRegistry {
    */
   clear(): void {
     this.macros.clear()
+    this.epoch++
+  }
+
+  /**
+   * Monotonic registry version (see `RequestWithMacros.applyMacros`)
+   */
+  getEpoch(): number {
+    return this.epoch
   }
 }
 
@@ -65,6 +131,15 @@ class RequestMacroRegistry {
  */
 export const requestMacroRegistry: RequestMacroRegistry = new RequestMacroRegistry()
 
+// Marker symbols for prototype-based macro attachment
+const MACRO_PROTO = Symbol('bunRouterMacroProto')
+const MACRO_BASE = Symbol('bunRouterMacroBase')
+
+// Cache of generated macro prototypes, keyed by the request's original
+// prototype. Rebuilt whenever the registry epoch moves.
+let macroProtoCache = new WeakMap<object, Record<PropertyKey, unknown>>()
+let macroProtoEpoch = -1
+
 /**
  * Request class with macro support
  */
@@ -77,15 +152,71 @@ export class RequestWithMacros {
   }
 
   /**
-   * Apply macros to a request object
+   * Register an accessor macro: `req.<name>` evaluates the getter
+   * (instead of exposing a callable). Assignment to the property
+   * shadows the accessor with an own value, so consumers that set
+   * `req.<name> = ...` keep working.
+   */
+  static macroAccessor(name: string, getter: (this: EnhancedRequest) => any): void {
+    requestMacroRegistry.register(name, getter, true)
+  }
+
+  /**
+   * Apply macros to a request object.
+   *
+   * Macros are attached via a shared prototype inserted between the
+   * request and its original prototype — one `setPrototypeOf` per
+   * request. The previous implementation looped over every macro and
+   * `bind`-assigned it, costing ~40 property writes and closures per
+   * request on the dispatch hot path. Macro handlers receive the
+   * request as `this`, so no per-request binding is needed.
    */
   static applyMacros(request: EnhancedRequest): EnhancedRequest {
-    const macros = requestMacroRegistry.all()
+    const epoch = requestMacroRegistry.getEpoch()
+    if (epoch !== macroProtoEpoch) {
+      macroProtoCache = new WeakMap()
+      macroProtoEpoch = epoch
+    }
 
-    macros.forEach((macro) => {
-      ;(request as any)[macro.name] = macro.handler.bind(request)
-    })
+    let base = (Object.getPrototypeOf(request) ?? Object.prototype) as Record<PropertyKey, unknown>
+    if (base[MACRO_PROTO]) {
+      // Request was already enhanced. Current generation: nothing to do.
+      if (macroProtoCache.get(base[MACRO_BASE] as object) === base) {
+        return request
+      }
+      // Stale generation: rebuild on top of the original prototype
+      base = base[MACRO_BASE] as Record<PropertyKey, unknown>
+    }
+
+    let proto = macroProtoCache.get(base)
+    if (!proto) {
+      proto = Object.create(base) as Record<PropertyKey, unknown>
+      for (const macro of requestMacroRegistry.all()) {
+        if (macro.accessor) {
+          Object.defineProperty(proto, macro.name, {
+            get: macro.handler,
+            // Assignment shadows the accessor with an own property
+            set(value: unknown) {
+              Object.defineProperty(this, macro.name, {
+                value,
+                writable: true,
+                configurable: true,
+                enumerable: true,
+              })
+            },
+            configurable: true,
+          })
+        }
+        else {
+          proto[macro.name] = macro.handler
+        }
+      }
+      Object.defineProperty(proto, MACRO_PROTO, { value: true })
+      Object.defineProperty(proto, MACRO_BASE, { value: base })
+      macroProtoCache.set(base, proto)
+    }
 
+    Object.setPrototypeOf(request, proto)
     return request
   }
 
@@ -150,18 +281,14 @@ export const BuiltInRequestMacros = {
    * Check if request is from mobile device
    */
   isMobile(this: EnhancedRequest): boolean {
-    const userAgent = this.headers.get('user-agent') || ''
-    const mobileRegex = /Mobile|Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i
-    return mobileRegex.test(userAgent)
+    return MOBILE_REGEX.test(this.headers.get('user-agent') || '')
   },
 
   /**
    * Check if request is from bot/crawler
    */
   isBot(this: EnhancedRequest): boolean {
-    const userAgent = this.headers.get('user-agent') || ''
-    const botRegex = /bot|crawler|spider|crawling/i
-    return botRegex.test(userAgent)
+    return BOT_REGEX.test(this.headers.get('user-agent') || '')
   },
 
   /**
@@ -220,6 +347,29 @@ export const BuiltInRequestMacros = {
     return null
   },
 
+  /**
+   * Get the raw, unparsed request body as a string.
+   *
+   * The body stream can only be consumed once, so this caches the result on
+   * `_rawBody`. Signature-verifying callbacks (Stripe/GitHub/Slack webhooks)
+   * need the exact bytes the client sent, before any JSON parsing — a parsed
+   * `jsonBody` re-serialized is NOT byte-identical and will fail HMAC checks.
+   * A framework body parser that has already read the body may populate
+   * `_rawBody` up front so this returns without re-reading.
+   */
+  async rawBody(this: EnhancedRequest): Promise<string> {
+    if (typeof this._rawBody === 'string')
+      return this._rawBody
+    try {
+      const text = await this.clone().text()
+      this._rawBody = text
+      return text
+    }
+    catch {
+      return ''
+    }
+  },
+
   /**
    * Get basic auth credentials
    */
@@ -398,38 +548,15 @@ export const BuiltInRequestMacros = {
    * Get cookie value
    */
   cookie(this: EnhancedRequest, name: string, defaultValue?: string): string | null {
-    const cookies = this.headers.get('cookie')
-    if (!cookies)
-      return defaultValue || null
-
-    const cookieArray = cookies.split(';')
-    for (const cookie of cookieArray) {
-      const [key, value] = cookie.trim().split('=')
-      if (key === name) {
-        return decodeURIComponent(value)
-      }
-    }
-
-    return defaultValue || null
+    const value = getParsedCookies(this)[name]
+    return value !== undefined ? value : (defaultValue || null)
   },
 
   /**
    * Get all cookies
    */
   cookies(this: EnhancedRequest): Record<string, string> {
-    const cookies: Record<string, string> = {}
-    const cookieHeader = this.headers.get('cookie')
-
-    if (cookieHeader) {
-      cookieHeader.split(';').forEach((cookie) => {
-        const [key, value] = cookie.trim().split('=')
-        if (key && value) {
-          cookies[key] = decodeURIComponent(value)
-        }
-      })
-    }
-
-    return cookies
+    return { ...getParsedCookies(this) }
   },
 
   /**
@@ -450,7 +577,7 @@ export const BuiltInRequestMacros = {
    * Get request path without query string
    */
   path(this: EnhancedRequest): string {
-    return new URL(this.url).pathname
+    return getParsedURL(this).pathname
   },
 
   /**
@@ -464,7 +591,7 @@ export const BuiltInRequestMacros = {
    * Get request root URL
    */
   root(this: EnhancedRequest): string {
-    const url = new URL(this.url)
+    const url = getParsedURL(this)
     return `${url.protocol}//${url.host}`
   },
 
@@ -474,12 +601,19 @@ export const BuiltInRequestMacros = {
   is(this: EnhancedRequest, pattern: string): boolean {
     const path = this.path()
 
-    // Convert pattern to regex
-    const regexPattern = pattern
-      .replace(/\*/g, '.*')
-      .replace(/\?/g, '.')
-
-    const regex = new RegExp(`^${regexPattern}$`)
+    // Compiled glob patterns are memoized — route checks tend to reuse a
+    // small set of patterns across many requests
+    let regex = GLOB_PATTERN_CACHE.get(pattern)
+    if (!regex) {
+      const regexPattern = pattern
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.')
+      regex = new RegExp(`^${regexPattern}$`)
+      if (GLOB_PATTERN_CACHE.size >= 1000) {
+        GLOB_PATTERN_CACHE.clear()
+      }
+      GLOB_PATTERN_CACHE.set(pattern, regex)
+    }
     return regex.test(path)
   },
 
@@ -494,7 +628,7 @@ export const BuiltInRequestMacros = {
    * Get request fingerprint for caching
    */
   fingerprint(this: EnhancedRequest): string {
-    const url = new URL(this.url)
+    const url = getParsedURL(this)
     const data = {
       method: this.method,
       path: url.pathname,

package/src/response/macros.ts

@@ -11,17 +11,17 @@ export interface ResponseMacro {
   handler: (...args: any[]) => Response
 }
 
-export interface ApiResponse<T = any> {
+export interface ApiResponse<T = unknown> {
   data?: T
   message?: string
   error?: string
   errors?: Record<string, string[]>
-  meta?: Record<string, any>
+  meta?: Record<string, unknown>
   links?: Record<string, string>
   timestamp?: string
 }
 
-export interface PaginatedResponse<T = any> extends ApiResponse<T[]> {
+export interface PaginatedResponse<T = unknown> extends ApiResponse<T[]> {
   meta: {
     current_page: number
     per_page: number

package/src/router/file-based-routing.ts

@@ -538,19 +538,26 @@ export function registerFileBasedRouting(RouterClass: typeof Router): void {
         // Store viewsDir for use in handlers
         this._viewsDir = viewsDir
 
-        // Register each discovered route
-        for (const route of routes) {
-          const handler = createViewHandler(route.filePath, viewsDir, config, this.config.queryPreservation)
+        // Register each discovered route. The existing GET paths are
+        // collected once — the previous per-route `.find()` scan made
+        // startup O(routes²) for large route tables.
+        const existingGetPaths = new Set<string>()
+        for (const r of this.routes as Array<{ path: string, method: string }>) {
+          if (r.method === 'GET') {
+            existingGetPaths.add(r.path)
+          }
+        }
 
+        for (const route of routes) {
           // Only register if no explicit route exists for this path
-          const existingRoute = this.routes.find(
-            (r: { path: string; method: string }) => r.path === route.routePath && r.method === 'GET'
-          )
-
-          if (!existingRoute) {
-            this.get(route.routePath, handler, 'web')
-            this._fileBasedRoutes.push(route)
+          if (existingGetPaths.has(route.routePath)) {
+            continue
           }
+
+          const handler = createViewHandler(route.filePath, viewsDir, config, this.config.queryPreservation)
+          this.get(route.routePath, handler, 'web')
+          this._fileBasedRoutes.push(route)
+          existingGetPaths.add(route.routePath)
         }
 
         this._fileRoutesInitialized = true

package/src/router/fluent-routing.ts

@@ -6,7 +6,34 @@ import { createModelBindingMiddleware } from '../model-binding'
 import { createRouteCacheMiddleware, RouteCacheFactory } from '../routing/route-caching'
 import { createRateLimitMiddleware, parseThrottleString, ThrottleFactory } from '../routing/route-throttling'
 import { DomainGroup, DomainMatcher, SubdomainRouter } from '../routing/subdomain-routing'
-import { registerNamedRoute } from '../url'
+import { getNamedRoutePath, registerNamedRoute } from '../url'
+import { matchPath } from '../utils'
+
+/**
+ * A route registered on a {@link FluentRouter}
+ */
+export interface RegisteredFluentRoute {
+  method: string
+  path: string
+  handler: RouteHandler
+  middleware: MiddlewareHandler[]
+  name?: string
+}
+
+/**
+ * Laravel-style resource controller shape accepted by
+ * {@link FluentRouter.resource}. Every action is optional — only the
+ * actions present (and allowed by `only`/`except`) are registered.
+ */
+export interface FluentResourceController {
+  index?: RouteHandler
+  create?: RouteHandler
+  store?: RouteHandler
+  show?: RouteHandler
+  edit?: RouteHandler
+  update?: RouteHandler
+  destroy?: RouteHandler
+}
 
 /**
  * Fluent route builder with chainable API
@@ -97,7 +124,9 @@ export class FluentRouteBuilder {
     // Add model binding middleware
     if (Object.keys(this.modelBindings).length > 0) {
       const parameters = Object.keys(this.modelBindings).map(name => ({ name }))
-      const modelBindingMiddleware = createModelBindingMiddleware(parameters as any, this.modelBindings as any)
+      const modelBindingMiddleware = createModelBindingMiddleware(parameters, this.modelBindings)
+      // The model-binding middleware's `next` is `() => Promise<Response>`;
+      // the fluent executor always provides one, so the adapter is safe
       finalMiddleware.push(modelBindingMiddleware as unknown as MiddlewareHandler)
     }
 
@@ -150,16 +179,15 @@ export class FluentConditionalBuilder {
 
   middleware(middlewareName: string): this {
     const [name, params] = middlewareName.split(':')
-    const middlewareFactory = (this.router as any).namedMiddleware.get(name)
+    const middlewareFactory = this.router.resolveNamedMiddleware(name)
 
     if (!middlewareFactory) {
       throw new Error(`Unknown middleware: ${name}`)
     }
 
-    const middlewareHandler = middlewareFactory(params)
-    ;(this.router as any).conditionalMiddleware.push({
+    this.router.addConditionalMiddleware({
       condition: this.condition,
-      middleware: [middlewareHandler],
+      middleware: [middlewareFactory(params)],
     })
 
     return this
@@ -230,13 +258,7 @@ export class FluentRouteGroupBuilder {
  * Fluent router with chainable API and advanced features
  */
 export class FluentRouter {
-  private routes: Array<{
-    method: string
-    path: string
-    handler: RouteHandler
-    middleware: MiddlewareHandler[]
-    name?: string
-  }> = []
+  private routes: RegisteredFluentRoute[] = []
 
   private globalMiddleware: MiddlewareHandler[] = []
   private subdomainRouter = new SubdomainRouter()
@@ -286,7 +308,7 @@ export class FluentRouter {
 
     // Auth middleware
     this.namedMiddleware.set('auth', () => {
-      return async (req: EnhancedRequest, next: any) => {
+      return async (req: EnhancedRequest, next: NextFunction) => {
         const token = req.headers.get('Authorization')?.replace('Bearer ', '')
         if (!token) {
           return new Response('Unauthorized', { status: 401 })
@@ -299,7 +321,7 @@ export class FluentRouter {
 
     // CORS middleware
     this.namedMiddleware.set('cors', () => {
-      return async (_req: EnhancedRequest, next: any) => {
+      return async (_req: EnhancedRequest, next: NextFunction) => {
         const response = await next()
         if (response) {
           const headers = new Headers(response.headers)
@@ -350,6 +372,22 @@ export class FluentRouter {
     return new FluentConditionalBuilder(this, condition)
   }
 
+  /**
+   * Look up a named middleware factory.
+   * @internal Used by the fluent builders — avoids `as any` reach-ins.
+   */
+  resolveNamedMiddleware(name: string): ((params?: string) => MiddlewareHandler) | undefined {
+    return this.namedMiddleware.get(name)
+  }
+
+  /**
+   * Register conditional middleware, evaluated per request in {@link handle}.
+   * @internal Used by the fluent builders.
+   */
+  addConditionalMiddleware(conditional: ConditionalMiddleware): void {
+    this.conditionalMiddleware.push(conditional)
+  }
+
   /**
    * Apply middleware with parameters
    */
@@ -547,7 +585,7 @@ export class FluentRouter {
   /**
    * Create resource routes (Laravel-style)
    */
-  resource(name: string, controller: any, options: {
+  resource(name: string, controller: FluentResourceController, options: {
     only?: string[]
     except?: string[]
     model?: BunQueryBuilderModel
@@ -584,13 +622,7 @@ export class FluentRouter {
   /**
    * Get all registered routes
    */
-  getRoutes(): Array<{
-    method: string
-    path: string
-    handler: RouteHandler
-    middleware: MiddlewareHandler[]
-    name?: string
-  }> {
+  getRoutes(): RegisteredFluentRoute[] {
     return [...this.routes, ...this.subdomainRouter.getAllRoutes()]
   }
 
@@ -598,10 +630,9 @@ export class FluentRouter {
    * Handle incoming request
    */
   async handle(request: EnhancedRequest): Promise<Response | null> {
-    const _url = new URL(request.url)
+    const url = new URL(request.url)
 
     // Try subdomain routing first
-    const url = new URL(request.url)
     const domain = url.hostname
     const match = this.subdomainRouter.findDomainGroup(domain)
     if (match) {
@@ -611,16 +642,18 @@ export class FluentRouter {
 
       // Find matching route in domain group
       for (const route of match.group.getRoutes()) {
-        if (this.matchesRoute(route, request)) {
-          return await this.executeRoute(route, enhancedReq)
+        const params = this.matchRouteParams(route, request.method, url.pathname)
+        if (params) {
+          return await this.executeRoute(route, enhancedReq, params)
         }
       }
     }
 
     // Find matching route
     for (const route of this.routes) {
-      if (this.matchesRoute(route, request)) {
-        return await this.executeRoute(route, request)
+      const params = this.matchRouteParams(route, request.method, url.pathname)
+      if (params) {
+        return await this.executeRoute(route, request, params)
       }
     }
 
@@ -628,32 +661,58 @@ export class FluentRouter {
   }
 
   /**
-   * Check if route matches request
+   * Match a route against the request, extracting path parameters.
+   *
+   * Delegates to the same `matchPath` used by the main `Router`, so the
+   * fluent API has identical semantics for `{param}`, optional `{param?}`,
+   * and wildcard segments (the previous ad-hoc regex neither escaped
+   * static text nor extracted params at all).
+   *
+   * @returns the extracted params, or `null` when the route doesn't match
    */
-  private matchesRoute(route: any, request: EnhancedRequest): boolean {
-    if (route.method !== request.method) {
-      return false
+  private matchRouteParams(
+    route: RegisteredFluentRoute,
+    method: string,
+    pathname: string,
+  ): Record<string, string> | null {
+    if (route.method !== method) {
+      return null
     }
 
-    const url = new URL(request.url)
-    // eslint-disable-next-line regexp/no-super-linear-backtracking
-    const routePattern = route.path.replace(/\{([^:}]+):?([^}]*)\}/g, '([^/]+)')
-    const regex = new RegExp(`^${routePattern}$`)
-
-    return regex.test(url.pathname)
+    const params: Record<string, string> = {}
+    return matchPath(route.path, pathname, params) ? params : null
   }
 
   /**
-   * Execute route with middleware
+   * Execute route with middleware (global → conditional → route-specific)
    */
-  private async executeRoute(route: any, request: EnhancedRequest): Promise<Response> {
-    const allMiddleware = [...this.globalMiddleware, ...route.middleware]
+  private async executeRoute(
+    route: RegisteredFluentRoute,
+    request: EnhancedRequest,
+    params: Record<string, string>,
+  ): Promise<Response> {
+    // Expose extracted path parameters to middleware and the handler
+    ;(request as { params?: Record<string, string> }).params = params
+
+    const allMiddleware = [...this.globalMiddleware]
+
+    // Conditional middleware (registered via `when(...)`) runs when its
+    // condition holds for this request — previously it was collected but
+    // never consulted
+    for (const conditional of this.conditionalMiddleware) {
+      if (await conditional.condition(request)) {
+        allMiddleware.push(...conditional.middleware)
+      }
+    }
+
+    allMiddleware.push(...route.middleware)
 
     let index = 0
     const next = async (): Promise<Response> => {
       if (index < allMiddleware.length) {
         const middleware = allMiddleware[index++]
-        return await middleware(request, next)
+        const result = await middleware(request, next)
+        return result ?? new Response(null)
       }
       return await route.handler(request)
     }
@@ -747,14 +806,24 @@ export const RouteFactory: {
  */
 export const RouterUtils = {
   /**
-   * Generate route URL with parameters
+   * Generate a URL for a named route. Resolves the path from the shared
+   * named-route registry (the same one `router.route()`/`url()` use);
+   * falls back to `/<name>` when the name was never registered.
    */
   route: (name: string, params: Record<string, string> = {}, query: Record<string, string> = {}): string => {
-    // Mock route URL generation
-    let url = `/${name}`
+    let url = getNamedRoutePath(name) ?? `/${name}`
 
     for (const [key, value] of Object.entries(params)) {
-      url = url.replace(`{${key}}`, value)
+      const encoded = encodeURIComponent(value)
+      url = url.replace(`{${key}}`, encoded)
+      url = url.replace(`{${key}?}`, encoded)
+    }
+
+    // Drop unfilled optional placeholders and tidy the slashes they leave
+    if (url.includes('?}')) {
+      url = url.replace(/\{[^}]+\?\}/g, '').replace(/\/{2,}/g, '/')
+      if (url.length > 1 && url.endsWith('/'))
+        url = url.slice(0, -1)
     }
 
     const queryString = new URLSearchParams(query).toString()
@@ -778,7 +847,7 @@ export const RouterUtils = {
   /**
    * JSON response
    */
-  json: (data: any, status: number = 200): Response => {
+  json: (data: unknown, status: number = 200): Response => {
     return new Response(JSON.stringify(data), {
       status,
       headers: { 'Content-Type': 'application/json' },