@stacksjs/bun-router 0.0.15 → 0.0.17

package/src/types/route-inference.ts

@@ -4,16 +4,29 @@
  * Advanced TypeScript utilities for inferring route parameter types from URL patterns
  */
 
-// Base types for route parameter extraction
-export type ExtractRouteParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}`
-  ? { [K in Param]: string } & ExtractRouteParams<`/${Rest}`>
-  : T extends `${infer _Start}:${infer Param}?${infer Rest}`
-    ? { [K in Param]?: string } & ExtractRouteParams<Rest>
-    : T extends `${infer _Start}:${infer Param}`
-      ? { [K in Param]: string }
-      : T extends `${infer _Start}*${infer Rest}`
-        ? { '*': string } & ExtractRouteParams<Rest>
-        : Record<string, never>
+/** Strip an inline constraint from a brace parameter: `id:[0-9]+` → `id` */
+type StripInlineConstraint<T extends string> = T extends `${infer Name}:${string}` ? Name : T
+
+// Base types for route parameter extraction.
+//
+// The router's canonical parameter syntax is `{param}` (with `{param?}` for
+// optional and `{param:regex}` for constrained parameters) — that form is
+// handled first. The legacy Express-style `:param` clauses are kept for
+// backward compatibility with code written against the colon syntax.
+export type ExtractRouteParams<T extends string> =
+  T extends `${string}{${infer Param}}${infer Rest}`
+    ? (Param extends `${infer Inner}?`
+        ? { [K in StripInlineConstraint<Inner>]?: string }
+        : { [K in StripInlineConstraint<Param>]: string }) & ExtractRouteParams<Rest>
+    : T extends `${infer _Start}:${infer Param}/${infer Rest}`
+      ? { [K in Param]: string } & ExtractRouteParams<`/${Rest}`>
+      : T extends `${infer _Start}:${infer Param}?${infer Rest}`
+        ? { [K in Param]?: string } & ExtractRouteParams<Rest>
+        : T extends `${infer _Start}:${infer Param}`
+          ? { [K in Param]: string }
+          : T extends `${infer _Start}*${infer Rest}`
+            ? { '*': string } & ExtractRouteParams<Rest>
+            : Record<string, never>
 
 // Advanced parameter extraction with type constraints
 export type ExtractTypedParams<T extends string> = T extends `${infer _Start}:${infer Param}<${infer Type}>${infer Rest}`
@@ -214,11 +227,13 @@ export interface RouteGroup<TPrefix extends string = '', TContext = object> {
   routes: TypedRoute<any, any, any, TContext>[]
 }
 
-// Middleware type (forward declaration - will be defined in middleware types)
+// Middleware type (forward declaration — the canonical definition lives in
+// middleware-types.ts; this one mirrors its narrow defaults so the two
+// can't drift apart silently)
 export interface TypedMiddleware<
-  TRequest = any,
-  TResponse = any,
-  TNext = any,
+  TRequest = Request,
+  TResponse = Response,
+  TNext = () => Promise<TResponse>,
   _TContext = Record<string, never>,
 > {
   (request: TRequest, next: TNext): Promise<TResponse> | TResponse

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Server } from 'bun'
 import type { Router } from './router/router'
+import type { SessionManager } from './session/index'
 import type { QueryPreservationConfig } from './utils/query-preservation'
 import type {
   AuthContext,
@@ -807,6 +808,12 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
    * Parsed JSON body (if Content-Type is application/json)
    */
   jsonBody?: Record<string, unknown>
+  /**
+   * Raw unparsed request body cache, populated on first `rawBody()` read (or up
+   * front by a framework body parser). Kept so webhook signature checks get the
+   * exact bytes the client sent.
+   */
+  _rawBody?: string
   /**
    * Form body data (if Content-Type is multipart/form-data or application/x-www-form-urlencoded)
    */
@@ -816,9 +823,11 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
    */
   files?: UploadedFile[]
   /**
-   * Session data (if session middleware is used)
+   * Session for the current request. The built-in session middleware
+   * attaches a `SessionManager` (with `get`/`set`/`flash`/… methods);
+   * testing utilities may attach plain `SessionData`.
    */
-  session?: SessionData
+  session?: SessionManager | SessionData
   /**
    * User data (if authentication middleware is used)
    */
@@ -1057,6 +1066,13 @@ export interface Route {
   pattern?: {
     exec: (url: URL) => PatternMatchResult | null
   }
+  /**
+   * Set to `false` (via `router.withoutNativeDispatch()`) to keep this
+   * route on the fetch-handler matcher even when the server runs with
+   * `nativeRoutes: true` — e.g. when it must respect registration-order
+   * precedence against an overlapping pattern.
+   */
+  nativeDispatch?: boolean
 }
 
 /**
@@ -1102,6 +1118,22 @@ export interface ServerOptions<T extends WebSocketData = WebSocketData> extends
    * These bypass the fetch handler entirely for zero-allocation serving (~15% faster).
    */
   static?: Record<string, Response>
+  /**
+   * Opt-in: register compatible routes with `Bun.serve`'s native router
+   * (`routes`), skipping the fetch handler's URL parsing and route
+   * matching for them. Compatible means: standard HTTP method, no
+   * domain scoping, no `where()`/inline constraints, no optional
+   * params, and `{param}`s spanning whole segments. Everything else —
+   * incompatible routes, 404/405 handling, HEAD fallback, the generic
+   * OPTIONS preflight — still flows through the fetch handler with
+   * identical semantics.
+   *
+   * Caveat: Bun matches by specificity (exact > param > wildcard).
+   * Apps that rely on registration order between same-shape overlapping
+   * patterns should leave this off. Routes registered after `serve()`
+   * only join the native table after `reload()`.
+   */
+  nativeRoutes?: boolean
   /**
    * Development mode options for Bun's dev server.
    * When true, enables HMR and development features.
@@ -1273,12 +1305,33 @@ export type MiddlewareWithParams<T extends string = string> =
 export type RouteParam<T extends string> = T extends `{${infer P}}` ? P : never
 
 /**
- * Extract parameters from route path
+ * Strip an inline constraint from a parameter token:
+ * `id:[0-9]+` → `id`, `slug` → `slug`
+ */
+export type ExtractParamName<T extends string> =
+  T extends `${infer Name}:${string}` ? Name : T
+
+/**
+ * Extract parameters from a route path into a narrowly-typed object.
+ *
+ * Handles the full parameter grammar:
+ * - `{id}` → `{ id: string }`
+ * - `{id?}` (optional) → `{ id?: string }`
+ * - `{id:[0-9]+}` (inline constraint) → `{ id: string }`
+ * - trailing `*` wildcard → `{ wildcard: string }`
+ *
+ * @example
+ * type P = ExtractRouteParams<'/users/{userId}/posts/{slug?}'>
+ * //   ^? { userId: string } & { slug?: string }
  */
 export type ExtractRouteParams<T extends string> =
   T extends `${string}{${infer Param}}${infer Rest}`
-    ? { [K in Param]: string } & ExtractRouteParams<Rest>
-    : object
+    ? (Param extends `${infer Inner}?`
+        ? { [K in ExtractParamName<Inner>]?: string }
+        : { [K in ExtractParamName<Param>]: string }) & ExtractRouteParams<Rest>
+    : T extends `${string}*${string}`
+      ? { wildcard: string }
+      : object
 
 /**
  * Route method constraints
@@ -1735,8 +1788,8 @@ export interface StreamingOptions {
 /**
  * SSE (Server-Sent Events) data structure
  */
-export interface SSEData {
-  data: any
+export interface SSEData<T = unknown> {
+  data: T
   event?: string
   id?: string
   retry?: number
@@ -1933,6 +1986,9 @@ export interface RequestMacroMethods {
   bearerToken: () => string | null
   basicAuth: () => { username: string, password: string } | null
 
+  /** Raw unparsed request body as a string (cached). Needed for webhook signature verification (Stripe/GitHub/Slack), where a re-serialized jsonBody won't match the HMAC. */
+  rawBody: () => Promise<string>
+
   // Headers
   hasHeader: (name: string) => boolean
   header: (name: string, defaultValue?: string) => string | null

package/src/url.ts

@@ -100,8 +100,13 @@ export function url(
     }
   }
 
-  // Strip any unfilled optional placeholders (e.g. `/posts/{slug?}` → `/posts/`)
-  resolved = resolved.replace(/\/\{[^}]+\?\}/g, '')
+  // Strip any unfilled optional placeholders and tidy the slashes they
+  // leave behind (`/posts/{slug?}` → `/posts`, `/a/{v?}/b` → `/a/b`)
+  if (resolved.includes('?}')) {
+    resolved = resolved.replace(/\{[^}]+\?\}/g, '').replace(/\/{2,}/g, '/')
+    if (resolved.length > 1 && resolved.endsWith('/'))
+      resolved = resolved.slice(0, -1)
+  }
 
   // Throw on unfilled required placeholders so the caller sees the bug.
   const missing = resolved.match(/\{([^}?]+)\}/g)

package/src/utils.ts

@@ -83,6 +83,83 @@ export function createPathRegex(pattern: string): RegExp {
   return new RegExp(`^${regexPattern}$`)
 }
 
+/**
+ * Per-pattern matching data. A route's pattern never changes, so the
+ * segment split, param-name extraction, and optional-param count are derived
+ * once and cached — turning `matchPath` from "regex + split on every request"
+ * into a tight array walk. Only the incoming `path` is processed per call.
+ */
+interface CompiledSegment {
+  isParam: boolean
+  paramName: string
+  isOptional: boolean
+  literal: string
+}
+
+interface CompiledPattern {
+  isWildcard: boolean
+  wildcardBase: string
+  segments: CompiledSegment[]
+  optionalCount: number
+}
+
+const PARAM_SEGMENT_RE = /\{([^}:]+)(?::[^}]+)?(\?)?\}/
+const OPTIONAL_SEGMENT_RE = /\{[^}]+\?\}/
+
+const compiledPatternCache = new Map<string, CompiledPattern>()
+// Cached compiled constraint regexes; `null` marks an invalid pattern so we
+// don't re-attempt construction on every request.
+const constraintRegexCache = new Map<string, RegExp | null>()
+
+function compilePattern(pattern: string): CompiledPattern {
+  const cached = compiledPatternCache.get(pattern)
+  if (cached)
+    return cached
+
+  const isWildcard = pattern.endsWith('/*')
+  const normalizedPattern = normalizePath(pattern)
+  let optionalCount = 0
+  const segments: CompiledSegment[] = normalizedPattern
+    .split('/')
+    .filter(Boolean)
+    .map((seg) => {
+      const isOptional = OPTIONAL_SEGMENT_RE.test(seg)
+      if (isOptional)
+        optionalCount++
+      const paramMatch = seg.match(PARAM_SEGMENT_RE)
+      return {
+        isParam: !!paramMatch,
+        paramName: paramMatch ? paramMatch[1].replace('?', '') : '',
+        isOptional,
+        literal: seg,
+      }
+    })
+
+  const compiled: CompiledPattern = {
+    isWildcard,
+    wildcardBase: isWildcard ? pattern.slice(0, -2) : '',
+    segments,
+    optionalCount,
+  }
+  compiledPatternCache.set(pattern, compiled)
+  return compiled
+}
+
+function getConstraintRegex(constraint: string): RegExp | null {
+  const cached = constraintRegexCache.get(constraint)
+  if (cached !== undefined)
+    return cached
+  let regex: RegExp | null
+  try {
+    regex = new RegExp(`^${constraint}$`)
+  }
+  catch {
+    regex = null
+  }
+  constraintRegexCache.set(constraint, regex)
+  return regex
+}
+
 /**
  * Matches a path against a pattern and extracts parameters
  * @param pattern The path pattern (e.g., '/users/{id}')
@@ -97,71 +174,59 @@ export function matchPath(
   params: Record<string, string>,
   constraints?: Record<string, string>,
 ): boolean {
-  // Both paths should be normalized
-  const normalizedPattern = normalizePath(pattern)
-  const normalizedPath = normalizePath(path)
+  const compiled = compilePattern(pattern)
 
-  // Special case for wildcard patterns
-  if (pattern.endsWith('/*')) {
-    const basePattern = pattern.slice(0, -2)
-    if (path.startsWith(basePattern)) {
-      return true
-    }
+  // Special case for wildcard patterns. Matches the original semantics:
+  // a prefix hit short-circuits to true, otherwise we fall through to the
+  // per-segment match below.
+  if (compiled.isWildcard && path.startsWith(compiled.wildcardBase)) {
+    return true
   }
 
-  // Handle patterns with parameters
-  const patternSegments = normalizedPattern.split('/').filter(Boolean)
-  const pathSegments = normalizedPath.split('/').filter(Boolean)
+  const patternSegments = compiled.segments
+  const pathSegments = normalizePath(path).split('/').filter(Boolean)
 
   // Quick check - if segments don't match (accounting for optional params) then no match
   // For mandatory parameters, the pattern and path must have same number of segments
-  const optionalParamCount = (normalizedPattern.match(/\{[^}]+\?\}/g) || []).length
-
-  if (pathSegments.length < patternSegments.length - optionalParamCount
+  if (pathSegments.length < patternSegments.length - compiled.optionalCount
     || pathSegments.length > patternSegments.length) {
     return false
   }
 
   // Match each segment
   for (let i = 0; i < patternSegments.length; i++) {
-    const patternSegment = patternSegments[i]
+    const seg = patternSegments[i]
     const pathSegment = pathSegments[i]
 
     // If we've run out of path segments and this is not an optional parameter
     if (pathSegment === undefined) {
-      if (patternSegment.match(/\{[^}]+\?\}/)) {
+      if (seg.isOptional) {
         // This is an optional parameter and we have no path segment for it
         continue
       }
-      else {
-        // Required parameter or static segment with no matching path segment
-        return false
-      }
+      // Required parameter or static segment with no matching path segment
+      return false
     }
 
-    // Check if this segment is a parameter
-    const paramMatch = patternSegment.match(/\{([^}:]+)(?::[^}]+)?(\?)?\}/)
-    if (paramMatch) {
-      // This is a parameter segment, extract param name
-      const paramName = paramMatch[1].replace('?', '')
+    if (seg.isParam) {
       // Store the parameter value
-      params[paramName] = pathSegment
+      params[seg.paramName] = pathSegment
 
       // Check constraints if they exist
-      if (constraints && constraints[paramName]) {
-        try {
-          const regex = new RegExp(`^${constraints[paramName]}$`)
+      if (constraints && constraints[seg.paramName]) {
+        const regex = getConstraintRegex(constraints[seg.paramName])
+        if (regex) {
           if (!regex.test(pathSegment)) {
             return false
           }
         }
-        catch {
+        else {
           // If regex is invalid, treat as no constraint
-          console.warn(`Invalid constraint regex for parameter ${paramName}: ${constraints[paramName]}`)
+          console.warn(`Invalid constraint regex for parameter ${seg.paramName}: ${constraints[seg.paramName]}`)
         }
       }
     }
-    else if (patternSegment !== pathSegment) {
+    else if (seg.literal !== pathSegment) {
       // Static segment doesn't match
       return false
     }
@@ -254,7 +319,7 @@ export async function resolveViewPath(
  * @param template The HTML template string
  * @param data The data to inject into the template
  */
-export function processHtmlTemplate(template: string, data: Record<string, any>): string {
+export function processHtmlTemplate(template: string, data: Record<string, unknown>): string {
   // Process general variables {{ varName }}
   let result = template.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
     const trimmedKey = key.trim()
@@ -274,7 +339,7 @@ export function processHtmlTemplate(template: string, data: Record<string, any>)
 /**
  * Process conditional statements in templates
  */
-function processConditionals(template: string, data: Record<string, any>): string {
+function processConditionals(template: string, data: Record<string, unknown>): string {
   // Match {{#if condition}} content {{/if}} or {{#if condition}} content {{else}} alternative {{/if}}
   return template.replace(
     /\{\{#if ([^}]+)\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g,
@@ -290,7 +355,7 @@ function processConditionals(template: string, data: Record<string, any>): strin
 /**
  * Process loop statements in templates
  */
-function processLoops(template: string, data: Record<string, any>): string {
+function processLoops(template: string, data: Record<string, unknown>): string {
   // Match {{#each items}} content {{/each}}
   return template.replace(
     /\{\{#each ([^}]+)\}\}([\s\S]*?)\{\{\/each\}\}/g,
@@ -320,8 +385,11 @@ function processLoops(template: string, data: Record<string, any>): string {
  * @param obj The object to extract value from
  * @param path The path to the value (e.g., 'user.profile.name')
  */
-function getNestedValue(obj: Record<string, any>, path: string): any {
-  return path.split('.').reduce((prev, curr) => {
-    return prev && prev[curr] !== undefined ? prev[curr] : undefined
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce<unknown>((prev, curr) => {
+    if (prev && typeof prev === 'object' && curr in prev) {
+      return (prev as Record<string, unknown>)[curr]
+    }
+    return undefined
   }, obj)
 }

package/src/validation/validator.ts

@@ -7,6 +7,12 @@
 import type { EnhancedRequest, NextFunction } from '../types'
 import { ValidationException } from '../errors/exceptions'
 
+// Hoisted email check. Pragmatic RFC 5322 approximation: requires one `@`,
+// a non-empty local part without surrounding/consecutive dots, and a domain
+// with at least one label dot and a 2+ char TLD. The previous regex
+// accepted addresses like `a@.com` and consecutive dots.
+const EMAIL_REGEX = /^[A-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?(?:\.[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?)*\.[A-Z]{2,}$/i
+
 export interface ValidationRule {
   name: string
   validate: (value: any, parameters: string[], field: string, data: Record<string, any>) => Promise<boolean> | boolean
@@ -74,10 +80,7 @@ export const BuiltInRules: Record<string, ValidationRule> = {
 
   email: {
     name: 'email',
-    validate: (value) => {
-      const emailRegex = /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/
-      return typeof value === 'string' && emailRegex.test(value)
-    },
+    validate: value => typeof value === 'string' && EMAIL_REGEX.test(value),
     message: 'The :field field must be a valid email address.',
   },
 

package/src/websocket/clustering.ts

@@ -539,8 +539,13 @@ export class WebSocketCluster {
         break
 
       case 'stats':
-        // Handle stats updates from other workers
+        // Handle stats updates from other workers. Bounded: with worker
+        // churn the per-worker entries would otherwise accumulate forever.
         if (message.data && message.workerId) {
+          const workerIds = Object.keys(this.stats.workerStats)
+          if (workerIds.length >= 1000 && !(message.workerId in this.stats.workerStats)) {
+            delete this.stats.workerStats[workerIds[0]]
+          }
           this.stats.workerStats[message.workerId] = message.data
         }
         break
@@ -623,6 +628,8 @@ export class WebSocketCluster {
         timestamp: now,
       })
     }, this.config.heartbeatInterval)
+    // The heartbeat must not keep the process alive on shutdown
+    this.heartbeatTimer.unref?.()
   }
 
   /**