@stacksjs/bun-router 0.0.17 → 0.0.18

package/src/types.ts

@@ -1,2123 +0,0 @@
-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,
-  AuthenticatedUser,
-  BoundModels,
-  CacheAdapter,
-  CacheStats,
-  CookieToDelete,
-  CookieToSet,
-  ErrorMetadata,
-  FallbackError,
-  FileInfo,
-  FlashMessages,
-  FormBody,
-  InputValidationSchemas,
-  InputValue,
-  JsonBodyData,
-  JwtHeader,
-  JwtPayload,
-  MetricEntry,
-  MiddlewareParams,
-  OAuth2Flows,
-  OAuth2Profile,
-  RequestContext,
-  RequestInput,
-  RouteMetadata,
-  SanitizationOptions,
-  SanitizationRule,
-  SessionData,
-  SessionSerializer,
-  SessionStore,
-  SSEConnection,
-  StaticResponseBody,
-  TemplateHelper,
-  TemplateHelpers,
-  TraceAttributes,
-  TraceSpan,
-  TypedServerWebSocket,
-  User,
-  ValidatedBody,
-  ValidatedData,
-  ValidationSchema,
-  WebSocketData,
-} from './types/core'
-
-// Re-export query preservation types
-export type { QueryPreservationConfig } from './utils/query-preservation'
-
-// Re-export core types
-export type {
-  AuthContext,
-  AuthenticatedUser,
-  BoundModels,
-  CacheAdapter,
-  CacheStats,
-  CookieToDelete,
-  CookieToSet,
-  ErrorMetadata,
-  FallbackError,
-  FileInfo,
-  FlashMessages,
-  FormBody,
-  InputValidationSchemas,
-  InputValue,
-  JsonBodyData,
-  JwtHeader,
-  JwtPayload,
-  MetricEntry,
-  MiddlewareParams,
-  OAuth2Flows,
-  OAuth2Profile,
-  RequestContext,
-  RequestInput,
-  RouteMetadata,
-  SanitizationOptions,
-  SanitizationRule,
-  SessionData,
-  SessionSerializer,
-  SessionStore,
-  SSEConnection,
-  StaticResponseBody,
-  TemplateHelper,
-  TemplateHelpers,
-  TraceAttributes,
-  TraceSpan,
-  TypedServerWebSocket,
-  User,
-  ValidatedBody,
-  ValidatedData,
-  ValidationSchema,
-  WebSocketData,
-}
-
-export interface Contact {
-  name?: string
-  email?: string
-  url?: string
-}
-
-export interface SecurityScheme {
-  type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect'
-  scheme?: string
-  bearerFormat?: string
-  name?: string
-  in?: 'header' | 'query' | 'cookie'
-  flows?: OAuth2Flows
-}
-
-export interface DocsConfig {
-  output: string
-  groupBy: 'path' | 'method' | 'tag'
-  includeExamples: boolean
-  title: string
-  description: string
-  version: string
-  baseUrl: string
-  contact?: Contact
-  security?: Record<string, SecurityScheme>
-}
-
-export interface CorsConfig {
-  enabled?: boolean
-  origin?: string | string[]
-  methods?: string[]
-  allowedHeaders?: string[]
-  exposedHeaders?: string[]
-  credentials?: boolean
-  maxAge?: number
-  preflightContinue?: boolean
-  optionsSuccessStatus?: number
-  privateNetworkAccess?: boolean
-}
-
-export interface RateLimitConfig {
-  enabled?: boolean
-  max?: number
-  timeWindow?: number
-  message?: string
-  draftMode?: boolean
-  advanced?: {
-    tokensPerInterval?: number
-    interval?: number
-    burst?: number
-    skipFailedRequests?: boolean
-    keyGenerator?: (req: Request) => string
-    algorithm?: 'fixed-window' | 'sliding-window' | 'token-bucket'
-  }
-  stores?: {
-    type: 'memory' | 'redis'
-    redis?: {
-      url: string
-      prefix?: string
-    }
-  }
-}
-
-export interface CompressionConfig {
-  enabled: boolean
-  level: number
-  threshold: number
-}
-
-export interface StaticConfig {
-  enabled: boolean
-  dir: string
-  maxAge: number
-}
-
-export interface CacheConfig {
-  enabled: boolean
-  type: CacheType
-  ttl: number
-  max?: number
-  redis?: {
-    url: string
-    prefix: string
-    maxRetries: number
-    connectTimeout: number
-    cluster?: {
-      nodes: string[]
-      options?: {
-        scaleReads: 'master' | 'slave' | 'all'
-        maxRedirections: number
-      }
-    }
-  }
-  customAdapter?: CacheAdapter<unknown>
-  routeCache?: {
-    enabled: boolean
-    ttl: number
-    methods: string[]
-    excludePaths: string[]
-    varyByHeaders: string[]
-    varyByQuery: string[]
-    maxSize?: number
-    purgeConditions?: {
-      maxAge: number
-      maxItems: number
-      lowMemory: boolean
-    }
-  }
-  strategies?: {
-    [key: string]: {
-      type: CacheStrategy
-      ttl: number
-      staleWhileRevalidateTtl?: number
-    }
-  }
-}
-
-export interface PerformanceConfig {
-  cache: CacheConfig
-  prefetch: {
-    enabled: boolean
-    paths: string[]
-    maxConcurrent: number
-    preloadPatterns?: string[]
-    warmupStrategy?: 'gradual' | 'aggressive'
-    prefetchHeaders?: Record<string, string>
-  }
-  optimization: {
-    minify: boolean
-    compress: boolean
-    treeshake: boolean
-    lazyLoad: boolean
-    chunkSize: number
-    imageOptimization?: {
-      enabled: boolean
-      quality: number
-      formats: ('webp' | 'avif' | 'jpeg' | 'png')[]
-      maxWidth: number
-      responsive: boolean
-    }
-    fontOptimization?: {
-      enabled: boolean
-      inlineSize: number
-      preload: boolean
-      formats: ('woff2' | 'woff')[]
-    }
-    cssOptimization?: {
-      minify: boolean
-      purge: boolean
-      splitChunks: boolean
-      criticalPath: boolean
-    }
-  }
-  monitoring?: {
-    enabled?: boolean
-    sampleRate?: number
-    metrics?: {
-      responseTime?: boolean
-      memoryUsage?: boolean
-      cpuUsage?: boolean
-      errorRate?: boolean
-      requestRate?: boolean
-      cacheStats?: boolean
-    }
-    tracing?: {
-      enabled?: boolean
-      sampleRate?: number
-      serviceName?: string
-      serviceVersion?: string
-      environment?: string
-      jaegerEndpoint?: string
-      zipkinEndpoint?: string
-    }
-    storage?: {
-      type?: CacheType
-      maxEntries?: number
-      filePath?: string
-      customHandler?: (metrics: MetricEntry[]) => Promise<void>
-    }
-    alerting?: {
-      enabled?: boolean
-      thresholds?: {
-        responseTime?: number
-        errorRate?: number
-        memoryUsage?: number
-      }
-      webhookUrl?: string
-      slackWebhook?: string
-      emailConfig?: {
-        smtp?: {
-          host?: string
-          port?: number
-          secure?: boolean
-          auth?: {
-            user?: string
-            pass?: string
-          }
-        }
-        to?: string[]
-        from?: string
-        cache: boolean
-        queue: boolean
-      }
-    }
-    profiling?: {
-      enabled: boolean
-      sampleRate: number
-      includeHeapSnapshot: boolean
-      gcStats: boolean
-    }
-    logging: {
-      level: 'debug' | 'info' | 'warn' | 'error'
-      format: 'json' | 'pretty'
-      destination: 'console' | 'file'
-      rotation?: {
-        size: string
-        interval: string
-        maxFiles: number
-      }
-    }
-  }
-}
-
-export interface LoadBalancerConfig {
-  enabled: boolean
-  strategy: 'round-robin' | 'least-connections' | 'ip-hash' | 'weighted-round-robin' | 'fastest-response'
-  healthCheck: {
-    enabled: boolean
-    interval: number
-    timeout: number
-    unhealthyThreshold: number
-    healthyThreshold: number
-    path: string
-    expectedStatus?: number
-    expectedBody?: string
-    headers?: Record<string, string>
-  }
-  sticky: {
-    enabled: boolean
-    cookieName: string
-    ttl: number
-    secret?: string
-    path?: string
-    domain?: string
-  }
-  retries: {
-    attempts: number
-    timeout: number
-    codes: number[]
-    backoff?: {
-      type: 'fixed' | 'exponential' | 'fibonacci'
-      initialDelay: number
-      maxDelay: number
-      factor: number
-    }
-  }
-  nodes?: {
-    [key: string]: {
-      url: string
-      weight?: number
-      backup?: boolean
-      maxFails?: number
-      failTimeout?: number
-    }
-  }
-}
-
-export interface SecurityConfig {
-  schemes: Record<string, SecurityScheme>
-  rateLimit: RateLimitConfig & {
-    advanced?: {
-      tokensPerInterval: number
-      interval: number
-      burst?: number
-      skipFailedRequests?: boolean
-      keyGenerator?: (req: Request) => string
-    }
-    stores?: {
-      type: 'memory' | 'redis'
-      redis?: {
-        url: string
-        prefix: string
-      }
-    }
-  }
-  cors: CorsConfig & {
-    preflightContinue?: boolean
-    optionsSuccessStatus?: number
-    privateNetworkAccess?: boolean
-    exposedHeaders?: string[]
-  }
-  csrf: {
-    enabled: boolean
-    secret: string
-    cookie: {
-      name: string
-      options: {
-        httpOnly: boolean
-        secure: boolean
-        sameSite: 'strict' | 'lax' | 'none'
-      }
-    }
-    ignoreMethods?: string[]
-    ignorePaths?: string[]
-    tokenLength?: number
-  }
-  helmet: {
-    enabled: boolean
-    contentSecurityPolicy: boolean | {
-      directives: Record<string, string[]>
-      reportOnly?: boolean
-      reportUri?: string
-      upgradeInsecureRequests?: boolean
-      blockAllMixedContent?: boolean
-    }
-    crossOriginEmbedderPolicy?: boolean | {
-      policy?: 'require-corp' | 'credentialless'
-    }
-    crossOriginOpenerPolicy?: boolean | {
-      policy?: 'same-origin' | 'same-origin-allow-popups' | 'unsafe-none'
-    }
-    crossOriginResourcePolicy?: boolean | {
-      policy?: 'same-site' | 'same-origin' | 'cross-origin'
-    }
-    dnsPrefetchControl?: boolean | {
-      allow?: boolean
-    }
-    xssFilter: boolean | {
-      setOnOldIE?: boolean
-    }
-    noSniff: boolean
-    frameOptions: 'DENY' | 'SAMEORIGIN'
-    hidePoweredBy: boolean
-    hsts?: {
-      maxAge: number
-      includeSubDomains: boolean
-      preload: boolean
-    }
-    referrerPolicy?: string | {
-      policy?: string | string[]
-    }
-    expectCt?: {
-      enforce: boolean
-      maxAge: number
-      reportUri?: string
-    }
-    ieNoOpen?: boolean
-    originAgentCluster?: boolean
-    permittedCrossDomainPolicies?: boolean | {
-      permittedPolicies?: 'none' | 'master-only' | 'by-content-type' | 'all'
-    }
-  }
-  ddos?: {
-    enabled?: boolean
-    maxRequestsPerSecond?: number
-    maxRequestsPerMinute?: number
-    maxRequestsPerHour?: number
-    burstLimit?: number
-    windowSize?: number
-    blockDuration?: number
-    whitelistedIPs?: string[]
-    blacklistedIPs?: string[]
-    trustProxy?: boolean
-    skipSuccessfulRequests?: boolean
-    skipFailedRequests?: boolean
-    keyGenerator?: (req: Request) => string
-    store?: Extract<CacheType, 'memory' | 'redis'>
-    redis?: {
-      url: string
-      prefix?: string
-    }
-  }
-  inputValidation?: {
-    enabled?: boolean
-    sanitizeByDefault?: boolean
-    strictMode?: boolean
-    allowUnknownFields?: boolean
-    maxDepth?: number
-    schemas?: InputValidationSchemas
-  }
-  attackPrevention?: {
-    enabled?: boolean
-    sqlInjection?: boolean
-    xss?: boolean
-    pathTraversal?: boolean
-    commandInjection?: boolean
-    ldapInjection?: boolean
-    xxe?: boolean
-    customPatterns?: {
-      name: string
-      pattern: RegExp
-      action: 'block' | 'log' | 'sanitize'
-    }[]
-  }
-  requestFiltering?: {
-    enabled?: boolean
-    blockSuspiciousPatterns?: boolean
-    maxRequestsPerMinute?: number
-    blockUserAgents?: string[]
-    allowedMethods?: string[]
-    requireUserAgent?: boolean
-    maxBodySize?: number
-    maxUrlLength?: number
-    maxHeaderSize?: number
-    allowedContentTypes?: string[]
-  }
-  ipFiltering?: {
-    enabled?: boolean
-    whitelist?: string[]
-    blacklist?: string[]
-    blockPrivateIPs?: boolean
-    blockCloudProviders?: boolean
-    geoBlocking?: {
-      enabled?: boolean
-      allowedCountries?: string[]
-      blockedCountries?: string[]
-    }
-  }
-  responseSecurity?: {
-    enabled?: boolean
-    removeServerHeaders?: boolean
-    addSecurityHeaders?: boolean
-    sanitizeErrors?: boolean
-    preventInfoDisclosure?: boolean
-  }
-  auth: {
-    jwt: {
-      secret: string
-      expiresIn: string
-      algorithm: 'HS256' | 'HS384' | 'HS512' | 'RS256'
-      issuer?: string
-      audience?: string
-      refreshToken?: {
-        enabled: boolean
-        expiresIn: string
-        renewBeforeExpiry?: number
-      }
-      rotation?: {
-        enabled: boolean
-        interval: number
-        maxAge: number
-      }
-    }
-    session: {
-      enabled: boolean
-      secret: string
-      name: string
-      resave: boolean
-      rolling: boolean
-      saveUninitialized: boolean
-      cookie: {
-        maxAge: number
-        secure: boolean
-        httpOnly: boolean
-        sameSite: 'strict' | 'lax' | 'none'
-        domain?: string
-        path?: string
-      }
-      store?: {
-        type: CacheType
-        redis?: {
-          url: string
-          prefix: string
-          ttl?: number
-          scanCount?: number
-          serializer?: SessionSerializer
-        }
-        custom?: SessionStore
-      }
-    }
-    oauth2?: {
-      enabled: boolean
-      providers: {
-        [key: string]: {
-          clientId: string
-          clientSecret: string
-          callbackURL: string
-          scope: string[]
-          authorizationURL?: string
-          tokenURL?: string
-          profileURL?: string
-          validateProfile?: (profile: OAuth2Profile) => Promise<boolean>
-        }
-      }
-    }
-  }
-  encryption?: {
-    enabled: boolean
-    algorithm: string
-    key: string
-    iv?: string
-    encoding: 'hex' | 'base64'
-  }
-  sanitization?: {
-    enabled: boolean
-    rules: {
-      [key: string]: {
-        type: 'escape' | 'strip' | 'validate'
-        options?: SanitizationOptions
-      }
-    }
-  }
-}
-
-export interface ServerConfig {
-  port: number
-  hostname: string
-  development: boolean
-  cors: CorsConfig
-  rateLimit: RateLimitConfig
-  compression: CompressionConfig
-  static: StaticConfig
-  performance: PerformanceConfig
-  loadBalancer?: LoadBalancerConfig
-  security: SecurityConfig
-  cluster: {
-    enabled: boolean
-    workers: number | 'auto'
-    sticky: boolean
-    strategy?: 'rr' | 'lc'
-    maxMemory?: number
-    restartOnMemory?: boolean
-    ipcTimeout?: number
-  }
-  gracefulShutdown: {
-    enabled: boolean
-    timeout: number
-    signals: string[]
-    forceTimeout: number
-    preShutdown?: () => Promise<void>
-    drain?: {
-      enabled: boolean
-      timeout: number
-      waitForStreams: boolean
-    }
-  }
-  middleware: {
-    errorHandler?: (error: Error, req: Request) => Promise<Response>
-    notFound?: (req: Request) => Promise<Response>
-    timeout?: number
-    order?: string[]
-    global?: MiddlewareHandler[]
-  }
-  hooks: {
-    onStart?: () => Promise<void>
-    onStop?: () => Promise<void>
-    onRequest?: (req: Request) => Promise<Request | Response>
-    onResponse?: (res: Response) => Promise<Response>
-    onError?: (error: Error) => Promise<void>
-    onMetric?: (metric: { name: string, value: number, tags?: Record<string, string> }) => Promise<void>
-    onTrace?: (span: TraceSpan) => Promise<void>
-  }
-  experimental?: {
-    http3: boolean
-    webTransport: boolean
-    earlyHints: boolean
-    webSocket: {
-      enabled: boolean
-      compression?: boolean
-      maxPayload?: number
-    }
-  }
-}
-
-export interface ViewEngineConfig {
-  /**
-   * The path to view files
-   */
-  viewsPath: string
-  /**
-   * File extensions to look for when resolving views
-   */
-  extensions: string[]
-  /**
-   * Default layout to use for views
-   */
-  defaultLayout?: string
-  /**
-   * Whether to cache compiled templates
-   */
-  cache: boolean
-  /**
-   * Template engine to use
-   */
-  engine: TemplateEngine
-  /**
-   * Custom render function for template processing
-   */
-  customRenderer?: (template: string, data: Record<string, any>, options: ViewRenderOptions) => Promise<string>
-  /**
-   * HTML minification options
-   */
-  minify?: {
-    enabled: boolean
-    options?: {
-      removeComments?: boolean
-      collapseWhitespace?: boolean
-      conservativeCollapse?: boolean
-      minifyJS?: boolean
-      minifyCSS?: boolean
-    }
-  }
-  /**
-   * Template helpers
-   */
-  helpers?: TemplateHelpers
-}
-
-export interface ViewRenderOptions {
-  layout?: string
-  partials?: Record<string, string>
-  components?: Record<string, string>
-  helpers?: TemplateHelpers
-  sections?: Record<string, string>
-}
-
-export interface RouterConfig {
-  verbose: boolean
-  routesPath?: string
-  apiRoutesPath?: string
-  webRoutesPath?: string
-  apiPrefix?: string
-  webPrefix?: string
-  /**
-   * Base path for action handlers (default: 'actions')
-   * Used when resolving string-based handlers like 'UserAction.ts'
-   */
-  actionsPath?: string
-  /**
-   * Base path for controllers (default: 'controllers')
-   * Used when resolving Controller@method patterns
-   */
-  controllersPath?: string
-  defaultMiddleware?: {
-    api?: (string | MiddlewareHandler)[]
-    web?: (string | MiddlewareHandler)[]
-  }
-  /**
-   * View engine configuration
-   */
-  views?: ViewEngineConfig
-  docs?: DocsConfig
-  server?: ServerConfig
-  /**
-   * Query parameter preservation configuration
-   * Automatically preserves specified query parameters across navigation
-   * @example
-   * queryPreservation: {
-   *   preserve: ['siteId', 'theme', 'locale'],
-   *   exclude: ['_t', 'utm_source'],
-   *   routes: ['/dashboard/*', '/admin/*']
-   * }
-   */
-  queryPreservation?: QueryPreservationConfig
-}
-
-export type RouterOptions = Partial<RouterConfig>
-
-export interface RouteParams {
-  [key: string]: string
-}
-
-/**
- * Cookie map interface for working with cookies
- */
-export interface CookieMap {
-  get: (name: string) => string | undefined
-  set: (name: string, value: string, options?: CookieOptions) => void
-  delete: (name: string, options?: Pick<CookieOptions, 'path' | 'domain'>) => void
-  getAll: () => Record<string, string>
-}
-
-/**
- * Cookie options interface
- */
-export interface CookieOptions {
-  maxAge?: number
-  expires?: Date
-  httpOnly?: boolean
-  secure?: boolean
-  path?: string
-  domain?: string
-  sameSite?: 'strict' | 'lax' | 'none'
-}
-
-/**
- * Cookie accessor interface with utility methods
- */
-export interface CookieAccessor {
-  get: (name: string) => string | undefined
-  set: (name: string, value: string, options?: CookieOptions) => void
-  delete: (name: string, options?: CookieOptions) => void
-  getAll: () => Record<string, string>
-}
-
-export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip' | 'cookies' | 'route'> {
-  /**
-   * Route parameters extracted from the URL
-   */
-  params: Record<string, string>
-  /**
-   * Lookup a single route param. Equivalent to `request.params[name]` but
-   * with optional default-value handling, matching the Laravel-style
-   * `$request->route('name')` ergonomics.
-   */
-  getParam: <T = string>(name: string, defaultValue?: T) => T | undefined
-  /**
-   * Query parameters from the URL
-   */
-  query: Record<string, string | string[]>
-  /**
-   * 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)
-   */
-  formBody?: FormBody
-  /**
-   * Uploaded files (if Content-Type is multipart/form-data)
-   */
-  files?: UploadedFile[]
-  /**
-   * 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?: SessionManager | SessionData
-  /**
-   * User data (if authentication middleware is used)
-   */
-  user?: User
-  /**
-   * Additional context data that can be set by middleware
-   */
-  context?: RequestContext
-  /**
-   * Validated data from validation middleware
-   */
-  validated?: ValidatedData
-  /**
-   * Model binding data
-   */
-  models?: BoundModels
-  /**
-   * Model binding errors
-   */
-  modelErrors?: Record<string, string>
-  /**
-   * Authenticated user from auth middleware
-   */
-  auth?: AuthContext
-  /**
-   * Rate limiting information
-   */
-  rateLimitRemaining?: number
-  /**
-   * Request ID for tracing
-   */
-  requestId?: string
-  /**
-   * IP address of the client (string property, not function from RequestMacroMethods)
-   */
-  ip?: string
-  /**
-   * Cookies parsed from the request with utility methods
-   */
-  cookies?: CookieAccessor
-  /**
-   * Flash messages (temporary messages for the next request)
-   */
-  flash?: FlashMessages
-  /**
-   * CSRF token
-   */
-  csrfToken?: string
-  /**
-   * Request start time for performance monitoring
-   */
-  startTime?: number
-  /**
-   * Trace ID for distributed tracing
-   */
-  traceId?: string
-  /**
-   * Span ID for distributed tracing
-   */
-  spanId?: string
-  /**
-   * Security middleware additions
-   */
-  nonce?: string
-  validatedBody?: ValidatedBody
-  /**
-   * Internal cookies to set in response (used by cookie utilities)
-   */
-  _cookiesToSet?: CookieToSet[]
-  /**
-   * Internal cookies to delete in response (used by cookie utilities)
-   */
-  _cookiesToDelete?: CookieToDelete[]
-  /**
-   * SSE connection information
-   */
-  sse?: SSEConnection
-  /**
-   * The matched route object
-   */
-  route?: Route
-}
-
-export interface UploadedFile {
-  fieldName: string
-  originalName: string
-  filename: string
-  path: string
-  size: number
-  mimetype: string
-  buffer: ArrayBuffer
-}
-
-export type RouteHandler = (_req: EnhancedRequest) => Response | Promise<Response>
-
-/**
- * Interface for handling route actions.
- * All action handlers must implement this interface.
- */
-export interface ActionHandlerClass {
-  /**
-   * Handles an incoming HTTP request and returns a response.
-   * @param request The incoming HTTP request
-   * @returns A Promise that resolves to a Response object
-   */
-  handle: (request: EnhancedRequest) => Promise<Response>
-}
-
-/**
- * Action handler path with strict pattern validation
- */
-export type ActionPath = `Actions/${string}Action` | `actions/${string}Action` | `${string}Controller@${string}`
-
-/**
- * Strongly typed action handler with better type safety
- */
-export type ActionHandler<TPath extends string = string> =
-  | ActionPath
-  | TypedRouteHandler<TPath>
-  | RouteHandler
-  | (new () => ActionHandlerClass)
-  | Response
-
-/**
- * Controller method reference with strict typing
- */
-export type ControllerMethod<
-  TController extends string = string,
-  TMethod extends string = string,
-> = `${TController}@${TMethod}`
-
-/**
- * Action class constructor with typed handle method
- */
-export interface TypedActionHandlerClass<TPath extends string = string> {
-  handle: (request: EnhancedRequest & { params: ExtractRouteParams<TPath> }) => Promise<Response>
-}
-
-/**
- * Discriminated union for different action handler types
- */
-export type ActionHandlerVariant<TPath extends string = string> =
-  | { type: 'path', value: ActionPath }
-  | { type: 'function', value: TypedRouteHandler<TPath> }
-  | { type: 'class', value: new () => TypedActionHandlerClass<TPath> }
-  | { type: 'controller', value: ControllerMethod }
-
-export type NextFunction = () => Promise<Response | null> | Response | null
-export type MiddlewareHandler = (_req: EnhancedRequest, _next: NextFunction) => Promise<Response | null> | Response | null
-
-export interface Middleware {
-  handle: MiddlewareHandler
-}
-
-/**
- * Strict middleware configuration with narrow types
- */
-export interface StrictMiddlewareConfig {
-  name: BuiltInMiddleware
-  enabled: boolean
-  priority: number
-  timing: MiddlewareTiming
-  params?: Record<string, string | number | boolean>
-}
-
-/**
- * Conditional middleware with narrow type constraints
- */
-export interface ConditionalMiddleware<T extends BuiltInMiddleware = BuiltInMiddleware> {
-  name: T
-  condition: (req: EnhancedRequest) => boolean
-  handler: MiddlewareHandler
-  priority?: number
-}
-
-/**
- * Middleware group configuration with strict typing
- */
-export interface MiddlewareGroup {
-  name: string
-  middleware: (BuiltInMiddleware | MiddlewareWithParams<BuiltInMiddleware>)[]
-  priority: number
-  description?: string
-}
-
-/**
- * Throttle middleware parameters with narrow types
- */
-export interface ThrottleMiddlewareParams {
-  pattern: ThrottlePattern
-  name?: string
-  keyGenerator?: (req: EnhancedRequest) => string
-  skipIf?: (req: EnhancedRequest) => boolean
-}
-
-/**
- * CORS middleware configuration with strict options
- */
-export interface CorsMiddlewareConfig {
-  origin: string | string[] | boolean | ((_origin: string) => boolean)
-  methods: HTTPMethod[]
-  allowedHeaders: string[]
-  exposedHeaders?: string[]
-  credentials: boolean
-  maxAge: number
-  preflightContinue: boolean
-  optionsSuccessStatus: ResponseStatus
-}
-
-/**
- * Auth middleware configuration with narrow types
- */
-export interface AuthMiddlewareConfig {
-  type: 'jwt' | 'session' | 'apikey' | 'basic' | 'bearer'
-  required: boolean
-  realm?: string
-  validateUser?: (user: User) => boolean
-  onUnauthorized?: (req: EnhancedRequest) => Response
-}
-
-export interface RouteGroup {
-  prefix?: string
-  middleware?: (string | MiddlewareHandler)[]
-}
-
-export interface Route {
-  path: string
-  handler: ActionHandler
-  method: string
-  middleware: MiddlewareHandler[]
-  type?: 'api' | 'web'
-  name?: string
-  constraints?: Record<string, string> | ((_params: Record<string, string>) => boolean)[]
-  domain?: string
-  params?: Record<string, string>
-  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
-}
-
-/**
- * WebSocket handler configuration
- */
-export interface WebSocketConfig<T extends WebSocketData = WebSocketData> {
-  open?: (ws: TypedServerWebSocket<T>) => void | Promise<void>
-  message: (ws: TypedServerWebSocket<T>, message: string | Uint8Array | ArrayBuffer) => void | Promise<void>
-  close?: (ws: TypedServerWebSocket<T>, code: number, reason: string) => void | Promise<void>
-  ping?: (ws: TypedServerWebSocket<T>, data: Uint8Array) => void | Promise<void>
-  pong?: (ws: TypedServerWebSocket<T>, data: Uint8Array) => void | Promise<void>
-  drain?: (ws: TypedServerWebSocket<T>) => void | Promise<void>
-  error?: (ws: TypedServerWebSocket<T>, error: Error) => void | Promise<void>
-  maxPayloadLength?: number
-  backpressureLimit?: number
-  closeOnBackpressureLimit?: boolean
-  idleTimeout?: number
-  perMessageDeflate?: boolean | {
-    compress?: boolean | Compressor
-    decompress?: boolean | Compressor
-  }
-  sendPings?: boolean
-  publishToSelf?: boolean
-}
-
-export type Compressor =
-  | 'disable'
-  | 'shared'
-  | 'dedicated'
-  | '3KB'
-  | '4KB'
-  | '8KB'
-  | '16KB'
-  | '32KB'
-  | '64KB'
-  | '128KB'
-  | '256KB'
-
-export interface ServerOptions<T extends WebSocketData = WebSocketData> extends Partial<Omit<Server<T>, 'websocket' | 'development'>> {
-  websocket?: WebSocketConfig<T>
-  /**
-   * Pre-computed static responses served by Bun's native static dispatch.
-   * 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.
-   * When an object, allows fine-grained control over HMR and console streaming.
-   *
-   * @example
-   * // Stream browser console.log/console.error to terminal
-   * development: { console: true }
-   *
-   * // Enable HMR + console streaming
-   * development: { hmr: true, console: true }
-   */
-  development?: boolean | {
-    hmr?: boolean
-    console?: boolean
-  }
-}
-
-/**
- * Type definition for route configuration with strict typing.
- */
-export interface RouteDefinition<
-  TPath extends string = string,
-  TMethod extends HTTPMethod = HTTPMethod,
-  THandler extends ActionHandler = ActionHandler,
-> {
-  /**
-   * The path pattern for the route
-   */
-  path: TPath
-  /**
-   * The HTTP method for the route
-   */
-  method: TMethod
-  /**
-   * The action handler for the route - can be a string path, function, or class
-   */
-  handler: THandler
-  /**
-   * Optional array of middleware to be executed before the handler
-   */
-  middleware?: (BuiltInMiddleware | MiddlewareWithParams<BuiltInMiddleware> | MiddlewareHandler)[]
-  /**
-   * Optional route type to distinguish between API and web routes
-   */
-  type?: 'api' | 'web'
-  /**
-   * Optional route name for reverse routing
-   */
-  name?: string
-  /**
-   * Route parameter constraints
-   */
-  constraints?: {
-    [K in keyof ExtractRouteParams<TPath>]: RouteConstraint
-  }
-  /**
-   * Optional route metadata for documentation or other purposes
-   */
-  meta?: RouteMetadata
-  /**
-   * Cache configuration for this specific route
-   */
-  cache?: {
-    enabled: boolean
-    ttl: number
-    tags?: string[]
-    strategy?: CacheStrategy
-  }
-  /**
-   * Rate limiting configuration for this route
-   */
-  throttle?: ThrottlePattern | ThrottleMiddlewareParams
-}
-
-/**
- * HTTP Methods type - extremely narrow
- */
-export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'TRACE' | 'CONNECT'
-
-/**
- * Narrow throttle pattern types
- */
-export type ThrottlePattern =
-  | `${number}` // e.g., "60" (60 requests per 1 minute)
-  | `${number},${number}` // e.g., "60,1" (60 requests per 1 minute)
-  | `${number},${number}min` // e.g., "60,5min" (60 requests per 5 minutes)
-  | `${number},${number}m` // e.g., "60,5m" (60 requests per 5 minutes)
-  | `${number},${number}sec` // e.g., "100,30sec" (100 requests per 30 seconds)
-  | `${number},${number}s` // e.g., "100,30s" (100 requests per 30 seconds)
-  | `${number},${number}hour` // e.g., "1000,1hour" (1000 requests per 1 hour)
-  | `${number},${number}h` // e.g., "1000,1h" (1000 requests per 1 hour)
-
-/**
- * Cache strategy types - narrow and specific
- */
-export type CacheStrategy = 'stale-while-revalidate' | 'cache-first' | 'network-first'
-
-/**
- * Cache type narrow definition
- */
-export type CacheType = 'memory' | 'redis' | 'custom'
-
-/**
- * File extension types for views
- */
-export type ViewExtension = '.html' | '.stx' | '.hbs' | '.ejs' | '.pug' | '.mustache'
-
-/**
- * Template engine types
- */
-export type TemplateEngine = 'auto' | 'stx' | 'html' | 'handlebars' | 'ejs' | 'pug' | 'mustache' | 'custom'
-
-/**
- * Route parameter constraint patterns
- */
-export type RouteConstraint =
-  | 'number' // Only numbers
-  | 'alpha' // Only letters
-  | 'alphanumeric' // Letters and numbers
-  | 'uuid' // UUID format
-  | 'slug' // URL-friendly slug
-  | RegExp // Custom regex
-  | string // Custom pattern string
-
-/**
- * Middleware execution timing
- */
-export type MiddlewareTiming = 'before' | 'after' | 'around'
-
-/**
- * Security header types
- */
-export type SecurityHeader =
-  | 'Content-Security-Policy'
-  | 'X-Frame-Options'
-  | 'X-Content-Type-Options'
-  | 'Referrer-Policy'
-  | 'Permissions-Policy'
-  | 'Strict-Transport-Security'
-
-/**
- * Built-in middleware names - extremely narrow
- */
-export type BuiltInMiddleware =
-  | 'auth'
-  | 'cors'
-  | 'csrf'
-  | 'helmet'
-  | 'json'
-  | 'compress'
-  | 'static'
-  | 'session'
-  | 'rateLimiter'
-  | 'requestId'
-  | 'logger'
-  | 'throttle'
-
-/**
- * Middleware with parameters
- */
-export type MiddlewareWithParams<T extends string = string> =
-  | T
-  | `${T}:${string}`
-
-/**
- * Route path parameter types - narrow template literals
- */
-export type RouteParam<T extends string> = T extends `{${infer P}}` ? P : never
-
-/**
- * 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}`
-    ? (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
- */
-export type RouteMethodConstraint<M extends HTTPMethod = HTTPMethod> = M
-
-/**
- * File MIME types for uploads
- */
-export type AllowedMimeType =
-  | 'image/jpeg'
-  | 'image/png'
-  | 'image/gif'
-  | 'image/webp'
-  | 'image/svg+xml'
-  | 'application/pdf'
-  | 'application/json'
-  | 'text/plain'
-  | 'text/csv'
-  | 'application/octet-stream'
-
-/**
- * Response status codes - narrow and specific
- */
-export type ResponseStatus =
-  | 200 | 201 | 202 | 204 // Success
-  | 301 | 302 | 304 // Redirects
-  | 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 // Client errors
-  | 500 | 502 | 503 | 504 // Server errors
-
-/**
- * Content types - narrow
- */
-export type ContentType =
-  | 'application/json'
-  | 'application/xml'
-  | 'text/html'
-  | 'text/plain'
-  | 'text/csv'
-  | 'application/pdf'
-  | 'application/octet-stream'
-  | 'multipart/form-data'
-  | 'application/x-www-form-urlencoded'
-
-/**
- * Strongly typed route method signatures
- */
-export interface TypedRouteHandler<TPath extends string> {
-  (req: EnhancedRequest & { params: ExtractRouteParams<TPath> }): Response | Promise<Response>
-}
-
-/**
- * Strongly typed route definition for specific HTTP methods
- */
-export interface GetRoute<TPath extends string> extends RouteDefinition<TPath, 'GET'> {
-  method: 'GET'
-  handler: TypedRouteHandler<TPath> | ActionHandler
-}
-
-export interface PostRoute<TPath extends string> extends RouteDefinition<TPath, 'POST'> {
-  method: 'POST'
-  handler: TypedRouteHandler<TPath> | ActionHandler
-}
-
-export interface PutRoute<TPath extends string> extends RouteDefinition<TPath, 'PUT'> {
-  method: 'PUT'
-  handler: TypedRouteHandler<TPath> | ActionHandler
-}
-
-export interface DeleteRoute<TPath extends string> extends RouteDefinition<TPath, 'DELETE'> {
-  method: 'DELETE'
-  handler: TypedRouteHandler<TPath> | ActionHandler
-}
-
-export interface PatchRoute<TPath extends string> extends RouteDefinition<TPath, 'PATCH'> {
-  method: 'PATCH'
-  handler: TypedRouteHandler<TPath> | ActionHandler
-}
-
-/**
- * Union of all typed route definitions
- */
-export type TypedRouteDefinition<TPath extends string = string> =
-  | GetRoute<TPath>
-  | PostRoute<TPath>
-  | PutRoute<TPath>
-  | DeleteRoute<TPath>
-  | PatchRoute<TPath>
-
-/**
- * Route validation helpers
- */
-export interface RouteValidation<TPath extends string> {
-  path: TPath
-  params: ExtractRouteParams<TPath>
-  validate: (req: EnhancedRequest) => req is EnhancedRequest & { params: ExtractRouteParams<TPath> }
-}
-
-/**
- * Common route patterns with strict template literal types
- */
-export type CommonRoutePatterns =
-  | '/' // Root
-  | '/health' // Health check
-  | '/api' // API root
-  | '/api/v1' // Versioned API
-  | '/api/v1/users' // User collection
-  | '/api/v1/users/{id}' // User resource
-  | '/api/v1/users/{userId}/posts' // Nested resource
-  | '/api/v1/users/{userId}/posts/{postId}' // Nested resource item
-  | '/admin' // Admin panel
-  | '/admin/{section}' // Admin section
-  | '/auth/login' // Authentication
-  | '/auth/logout' // Logout
-  | '/auth/register' // Registration
-  | '/auth/forgot-password' // Password reset
-  | '/uploads/{filename}' // File uploads
-  | '/assets/{path}' // Static assets
-
-/**
- * RESTful resource route patterns
- */
-export type ResourceRoutePatterns<T extends string> =
-  | `/${T}` // Collection: GET /users
-  | `/${T}/{id}` // Item: GET /users/123
-  | `/${T}/create` // Create form: GET /users/create
-  | `/${T}/{id}/edit` // Edit form: GET /users/123/edit
-  | `/${T}/{id}/show` // Show item: GET /users/123/show
-
-/**
- * API versioning patterns
- */
-export type ApiVersionPattern<V extends string, Path extends string> = `/api/${V}${Path}`
-
-/**
- * Nested resource patterns
- */
-export type NestedResourcePattern<
-  Parent extends string,
-  Child extends string,
-  ParentId extends string = 'id',
-  ChildId extends string = 'id',
-> = `/${Parent}/{${ParentId}}/${Child}` | `/${Parent}/{${ParentId}}/${Child}/{${ChildId}}`
-
-/**
- * Route parameter patterns with constraints
- */
-export type IdPattern = '{id}'
-export type UuidPattern = '{uuid}'
-export type SlugPattern = '{slug}'
-export type NumberPattern = '{number}'
-
-/**
- * File path patterns
- */
-export type FilePathPattern = '{filepath}' | '{*filepath}' | '{path...}'
-
-/**
- * Discriminated union for cache configurations
- */
-export type CacheConfigVariant =
-  | { type: 'memory', maxSize: number, ttl: number }
-  | { type: 'redis', url: string, prefix: string, ttl: number, maxRetries: number }
-  | { type: 'custom', adapter: CacheConfig['customAdapter'], ttl: number }
-
-/**
- * Discriminated union for authentication configurations
- */
-export type AuthConfigVariant =
-  | { type: 'jwt', secret: string, expiresIn: string, algorithm: 'HS256' | 'HS384' | 'HS512' | 'RS256' }
-  | { type: 'session', secret: string, store: CacheType, maxAge: number }
-  | { type: 'apikey', keyName: string, location: 'header' | 'query' | 'cookie' }
-  | { type: 'basic', realm: string, users: Record<string, string> }
-  | { type: 'bearer', validate: (token: string) => Promise<boolean> }
-
-/**
- * Discriminated union for rate limiting configurations
- */
-export type RateLimitConfigVariant =
-  | { type: 'memory', maxAttempts: number, windowMs: number, keyGenerator?: (req: EnhancedRequest) => string }
-  | { type: 'redis', maxAttempts: number, windowMs: number, redisUrl: string, keyPrefix: string }
-  | { type: 'pattern', pattern: ThrottlePattern, name?: string }
-
-/**
- * Discriminated union for middleware configurations
- */
-export type MiddlewareConfigVariant =
-  | { type: 'throttle', config: RateLimitConfigVariant }
-  | { type: 'cors', config: CorsMiddlewareConfig }
-  | { type: 'auth', config: AuthConfigVariant }
-  | { type: 'cache', config: CacheConfigVariant }
-  | { type: 'custom', name: string, handler: MiddlewareHandler, params?: MiddlewareParams }
-
-/**
- * Discriminated union for route handlers
- */
-export type RouteHandlerVariant<TPath extends string = string> =
-  | { type: 'action', path: ActionPath }
-  | { type: 'function', handler: TypedRouteHandler<TPath> }
-  | { type: 'class', constructor: new () => TypedActionHandlerClass<TPath> }
-  | { type: 'controller', method: ControllerMethod }
-
-/**
- * Discriminated union for validation rules
- */
-export type ValidationRuleVariant =
-  | { type: 'required', message?: string }
-  | { type: 'string', minLength?: number, maxLength?: number, pattern?: RegExp }
-  | { type: 'number', min?: number, max?: number, integer?: boolean }
-  | { type: 'email', message?: string }
-  | { type: 'url', protocols?: string[] }
-  | { type: 'custom', validate: (value: unknown) => boolean | Promise<boolean>, message: string }
-
-/**
- * Streaming configuration types with extreme narrowing
- */
-export type StreamingFormat = 'json' | 'ndjson' | 'csv' | 'xml' | 'text' | 'binary'
-export type StreamingCompression = 'gzip' | 'deflate' | 'br' | 'none'
-export type StreamingMode = 'chunked' | 'buffered' | 'direct'
-
-/**
- * Server-Sent Events configuration
- */
-export interface SSEConfig {
-  retryInterval?: number
-  keepAlive?: number
-  compression?: StreamingCompression
-  maxConnections?: number
-  heartbeatInterval?: number
-  headers?: Record<string, string>
-  enableHeartbeat?: boolean
-  connectionTimeout?: number
-  retryDelay?: number
-}
-
-/**
- * SSE Event data structure with strict typing
- */
-export interface SSEEvent<T = unknown> {
-  data: T
-  event?: string
-  id?: string | number
-  retry?: number
-  comment?: string
-}
-
-/**
- * Stream generator function types
- */
-export type SSEGenerator<T = unknown> = () => AsyncGenerator<SSEEvent<T>, void, unknown>
-
-/**
- * Direct streaming configuration
- */
-export interface DirectStreamConfig {
-  headers?: Record<string, string>
-  status?: ResponseStatus
-  compression?: StreamingCompression
-  format?: StreamingFormat
-  bufferSize?: number
-  delimiter?: string
-  contentType?: ContentType
-  enableCompression?: boolean
-  compressionType?: StreamingCompression
-}
-
-/**
- * Buffered streaming configuration
- */
-export interface BufferedStreamConfig extends DirectStreamConfig {
-  highWaterMark?: number
-  maxBuffer?: number
-  flushInterval?: number
-  autoFlush?: boolean
-  contentType?: ContentType
-}
-
-/**
- * File streaming configuration with strict types
- */
-export interface FileStreamConfig {
-  headers?: Record<string, string>
-  status?: ResponseStatus
-  mimeType?: AllowedMimeType
-  disposition?: 'inline' | 'attachment'
-  filename?: string
-  maxAge?: number
-  etag?: boolean
-  lastModified?: boolean
-  compression?: StreamingCompression
-}
-
-/**
- * Range request configuration for file streaming
- */
-export interface RangeStreamConfig extends FileStreamConfig {
-  unit?: 'bytes'
-  maxRanges?: number
-  enableMultipart?: boolean
-}
-
-/**
- * Transform stream configuration
- */
-export interface TransformStreamConfig<TInput = any, TOutput = any> {
-  transform: (chunk: TInput) => TOutput | Promise<TOutput>
-  flush?: () => TOutput[] | Promise<TOutput[]>
-  objectMode?: boolean
-  highWaterMark?: number
-  format?: StreamingFormat
-  headers?: Record<string, string>
-}
-
-/**
- * Streaming response writer interfaces
- */
-export interface StreamWriter<T = any> {
-  write: (chunk: T) => void | Promise<void>
-  end: () => void | Promise<void>
-  close: () => void
-}
-
-export interface BufferedStreamWriterGeneric<T = any> extends StreamWriter<T> {
-  flush: () => void | Promise<void>
-  cork: () => void
-  uncork: () => void
-}
-
-/**
- * Model binding configuration with strict types
- */
-export interface ModelBinding<T = any> {
-  name: string
-  model: string // Model name
-  parameter: string // Parameter name
-  required?: boolean
-  as?: string // Alias for the bound model
-  resolver: ModelResolver<T>
-  cache?: {
-    enabled: boolean
-    ttl: number
-    key?: (params: Record<string, string>) => string
-  }
-  validation?: {
-    required?: boolean
-    validator?: (model: T) => boolean | Promise<boolean>
-  }
-  errorHandler?: (error: Error, params: Record<string, string>) => Response
-}
-
-/**
- * Model resolver function type
- */
-export type ModelResolver<T = any> = (
-  params: Record<string, string>,
-  req: EnhancedRequest
-) => T | Promise<T> | null
-
-/**
- * Model validator function type
- */
-export type ModelValidatorFn<T = any> = (
-  model: T,
-  params: Record<string, string>,
-  req?: EnhancedRequest
-) => Promise<{ valid: boolean, error?: string, status?: number }> | { valid: boolean, error?: string, status?: number }
-
-/**
- * Model transformer function type
- */
-export type ModelTransformerFn<T = any> = (
-  model: T,
-  params?: Record<string, string>,
-  req?: EnhancedRequest
-) => any | Promise<any>
-
-/**
- * Model registry interface
- */
-export interface ModelRegistry {
-  register: <T>(binding: ModelBinding<T>) => void
-  resolve: <T>(name: string, params: Record<string, string>, req: EnhancedRequest) => Promise<T | null>
-  has: (name: string) => boolean
-  clear: () => void
-  getAll: () => ModelBinding[]
-}
-
-/**
- * Model binding middleware configuration
- */
-export interface ModelBindingConfig {
-  parameterName: string
-  modelName: string
-  required?: boolean
-  cacheKey?: (params: Record<string, string>) => string
-}
-
-/**
- * Resource route configuration with model binding
- */
-export interface ResourceConfig {
-  controller: string
-  only?: ('index' | 'show' | 'create' | 'store' | 'edit' | 'update' | 'destroy')[]
-  except?: ('index' | 'show' | 'create' | 'store' | 'edit' | 'update' | 'destroy')[]
-  middleware?: (BuiltInMiddleware | MiddlewareWithParams<BuiltInMiddleware>)[]
-  bindings?: Record<string, string>
-  names?: Partial<Record<'index' | 'show' | 'create' | 'store' | 'edit' | 'update' | 'destroy', string>>
-}
-
-/**
- * Stream route handler with typed path parameters
- */
-export interface StreamRouteHandler<TPath extends string = string> {
-  (
-    req: EnhancedRequest & { params: ExtractRouteParams<TPath> },
-    writer: StreamWriter
-  ): Promise<void> | void
-}
-
-/**
- * SSE route handler with typed path parameters
- */
-export interface SSERouteHandler<TPath extends string = string> {
-  (
-    req: EnhancedRequest & { params: ExtractRouteParams<TPath> }
-  ): SSEGenerator | AsyncGenerator<SSEEvent, void, unknown>
-}
-
-/**
- * Route matching result
- */
-export interface MatchResult {
-  route: Route
-  params: Record<string, string>
-}
-
-/**
- * URL pattern match result
- */
-export interface PatternMatchResult {
-  pathname: {
-    groups: Record<string, string>
-  }
-}
-
-/**
- * Streaming response options
- */
-export interface StreamingOptions {
-  headers?: Record<string, string>
-  status?: number
-}
-
-/**
- * SSE (Server-Sent Events) data structure
- */
-export interface SSEData<T = unknown> {
-  data: T
-  event?: string
-  id?: string
-  retry?: number
-}
-
-/**
- * Direct streaming writer interface
- */
-export interface DirectStreamWriter {
-  write: (chunk: string | Uint8Array) => void
-  close: () => void
-}
-
-/**
- * Buffered streaming writer interface
- */
-export interface BufferedStreamWriter {
-  write: (chunk: string | Uint8Array) => void
-  flush: () => void
-  end: () => void
-}
-
-/**
- * Buffered streaming options
- */
-export interface BufferedStreamOptions {
-  highWaterMark?: number
-  asUint8Array?: boolean
-}
-
-/**
- * Async generator function type for streaming
- */
-export type StreamGenerator<T = unknown> = () => AsyncGenerator<T, void, unknown>
-
-/**
- * Direct stream handler function type
- */
-export type DirectStreamHandler = (_writer: DirectStreamWriter) => Promise<void>
-
-/**
- * Buffered stream handler function type
- */
-export type BufferedStreamHandler = (_writer: BufferedStreamWriter) => Promise<void>
-
-/**
- * Transform function type for stream transformation
- */
-export type TransformFunction<T = Uint8Array, R = string | Uint8Array> = (_chunk: T) => R | Promise<R>
-
-/**
- * Advanced Error Handling Types
- */
-export interface ErrorContext {
-  requestId?: string
-  userId?: string | number
-  traceId?: string
-  spanId?: string
-  route?: string
-  method?: string
-  url?: string
-  userAgent?: string
-  ip?: string
-  timestamp?: Date
-  metadata?: ErrorMetadata
-}
-
-export interface ErrorReportingConfig {
-  enabled: boolean
-  service: 'sentry' | 'bugsnag' | 'custom'
-  dsn?: string
-  apiKey?: string
-  environment?: string
-  release?: string
-  sampleRate?: number
-  beforeSend?: (error: Error, context: ErrorContext) => Error | null
-  filters?: {
-    ignoreErrors?: (string | RegExp)[]
-    ignoreCodes?: string[]
-    ignoreUrls?: (string | RegExp)[]
-    allowUrls?: (string | RegExp)[]
-  }
-  tags?: Record<string, string>
-  user?: {
-    id?: string
-    email?: string
-    username?: string
-  }
-  extra?: Record<string, unknown>
-  breadcrumbs?: {
-    enabled: boolean
-    maxBreadcrumbs: number
-  }
-  performance?: {
-    enabled: boolean
-    tracesSampleRate: number
-  }
-}
-
-export interface CircuitBreakerConfig {
-  name: string
-  failureThreshold: number
-  recoveryTimeout: number
-  timeout: number
-  monitoringPeriod: number
-  minimumRequests: number
-  errorThresholdPercentage: number
-  halfOpenMaxCalls: number
-  resetTimeout: number
-  onStateChange?: (state: 'CLOSED' | 'OPEN' | 'HALF_OPEN', name: string) => void
-  onFailure?: (error: Error, name: string) => void
-  onSuccess?: (name: string) => void
-  shouldTripOnError?: (error: Error) => boolean
-}
-
-export interface DegradationConfig {
-  enabled: boolean
-  fallbackStrategies: {
-    [serviceName: string]: {
-      type: 'cache' | 'static' | 'simplified' | 'redirect' | 'custom'
-      priority: number
-      timeout: number
-      retries: number
-      backoff: {
-        type: 'fixed' | 'exponential'
-        delay: number
-        maxDelay?: number
-      }
-      fallbackHandler?: (error: FallbackError, context: ErrorContext) => Promise<Response>
-      cacheConfig?: {
-        key: string
-        ttl: number
-        staleWhileRevalidate: boolean
-      }
-      staticResponse?: {
-        status: number
-        body: StaticResponseBody
-        headers?: Record<string, string>
-      }
-      redirectConfig?: {
-        url: string
-        permanent: boolean
-      }
-    }
-  }
-  healthChecks: {
-    [serviceName: string]: {
-      enabled: boolean
-      endpoint: string
-      interval: number
-      timeout: number
-      retries: number
-      expectedStatus: number[]
-      expectedBody?: string | RegExp
-      headers?: Record<string, string>
-      onHealthy?: () => void
-      onUnhealthy?: (error: Error) => void
-    }
-  }
-  monitoring: {
-    enabled: boolean
-    alertThresholds: {
-      errorRate: number
-      responseTime: number
-      availability: number
-    }
-  }
-}
-
-/**
- * Request/Response Enhancement Types
- */
-export interface RequestMacroMethods {
-  // Content type detection
-  wantsJson: () => boolean
-  wantsHtml: () => boolean
-  wantsXml: () => boolean
-  expectsJson: () => boolean
-
-  // Request information
-  isAjax: () => boolean
-  isPjax: () => boolean
-  isMobile: () => boolean
-  isBot: () => boolean
-  isSecure: () => boolean
-
-  // Client information
-  ip: () => string
-  ips: () => string[]
-  userAgent: () => string
-  referer: () => string | null
-
-  // Authentication
-  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
-  allHeaders: () => Record<string, string>
-
-  // Input handling
-  input: <T = InputValue>(key: string, defaultValue?: T) => T
-  all: () => RequestInput
-  only: (keys: string[]) => RequestInput
-  except: (keys: string[]) => RequestInput
-
-  // Validation checks
-  has: (key: string) => boolean
-  hasAny: (keys: string[]) => boolean
-  missing: (key: string) => boolean
-  filled: (key: string) => boolean
-
-  // Query and params
-  getQuery: <T = InputValue>(key?: string, defaultValue?: T) => T
-  param: <T = InputValue>(key: string, defaultValue?: T) => T
-
-  // Cookies
-  cookie: (name: string, defaultValue?: string) => string | null
-  cookies: () => Record<string, string>
-
-  // Files
-  /**
-   * Lookup a single uploaded file by form field name. Returns the
-   * matching `FileInfo` (structurally an `UploadedFile`) or `null` when
-   * no field with that name was uploaded. Populated by the multipart
-   * file-upload middleware alongside `files: UploadedFile[]`. Mirrors
-   * Laravel's `$request->file('avatar')`:
-   *
-   * ```ts
-   * const avatar = req.file('avatar')
-   * if (!avatar) return new Response('Missing avatar', { status: 400 })
-   * ```
-   */
-  file: (name: string) => FileInfo | null
-  hasFile: (name: string) => boolean
-
-  // URL utilities
-  path: () => string
-  fullUrl: () => string
-  root: () => string
-  is: (pattern: string) => boolean
-  route: () => string | null
-
-  // Utilities
-  fingerprint: () => string
-  signature: (secret: string) => string
-  merge: (data: RequestInput) => void
-  replace: (data: RequestInput) => void
-  age: () => number
-  isFromTrustedProxy: (trustedProxies?: string[]) => boolean
-  contentLength: () => number
-  contentType: () => string | null
-  isContentType: (type: string) => boolean
-}
-
-/**
- * Enhanced streaming generator types with extreme narrowing
- */
-export type StreamGeneratorSync<T = string | Uint8Array> = () => Generator<T, void, unknown>
-export type AsyncStreamGenerator<T = string | Uint8Array> = () => AsyncGenerator<T, void, unknown>
-export type StreamCallbackGenerator<T = string | Uint8Array> = StreamGenerator<T> | AsyncStreamGenerator<T>
-
-/**
- * SSE Event generator with strict typing
- */
-export type SSEEventGenerator<T = unknown> = () => Generator<SSEEvent<T>, void, unknown> | AsyncGenerator<SSEEvent<T>, void, unknown>
-
-/**
- * Extreme narrow types for Laravel-style methods with template literal patterns
- */
-export interface EnhancedLaravelStreamingMethods {
-  /**
-   * Laravel-style response()->stream() with extreme type narrowing
-   */
-  stream: <T extends string | Uint8Array = string>(
-    callback: StreamCallbackGenerator<T>,
-    status?: ResponseStatus,
-    headers?: Record<string, string>
-  ) => Response
-
-  /**
-   * Laravel-style response()->streamJson() with strict object key typing
-   */
-  streamJson: <T, K extends string = string>(
-    data: Record<K, Iterable<T> | AsyncIterable<T>>,
-    status?: ResponseStatus,
-    headers?: Record<string, string>
-  ) => Response
-
-  /**
-   * Laravel-style response()->eventStream() with strict SSE typing
-   */
-  eventStream: <T = unknown>(
-    callback: SSEEventGenerator<T>,
-    headers?: Record<string, string>
-  ) => Response
-
-  /**
-   * Laravel-style response()->streamDownload() with filename validation
-   */
-  streamDownload: <T extends string | Uint8Array = string>(
-    callback: StreamCallbackGenerator<T>,
-    filename: `${string}.${string}`, // Must have extension
-    headers?: Record<string, string>
-  ) => Response
-}
-
-/**
- * Enhanced model binding with strict key typing
- */
-export interface EnhancedLaravelModelBindingMethods {
-  /**
-   * Laravel-style Route::model() with key validation
-   */
-  model: <T, K extends string>(
-    key: K,
-    modelClass: string | ((_value: string) => Promise<T | null>),
-    callback?: (model: T | null) => Response | null
-  ) => Router & { [P in K]: T }
-
-  /**
-   * Scoped bindings with relationship validation
-   */
-  scopedBindings: <Parent extends string, Child extends string>(
-    bindings: Record<Child, Parent>
-  ) => MiddlewareHandler
-}