@stacksjs/bun-router 0.0.4 → 0.0.6

package/dist/types.d.ts

@@ -0,0 +1,1776 @@
+import type { Server } from 'bun';
+import type { Router } from './router/router';
+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';
+export type { QueryPreservationConfig } from './utils/query-preservation';
+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>;
+    /**
+     * Query parameters from the URL
+     */
+    query: Record<string, string | string[]>;
+    /**
+     * Parsed JSON body (if Content-Type is application/json)
+     */
+    jsonBody?: Record<string, unknown>;
+    /**
+     * 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 data (if session middleware is used)
+     */
+    session?: 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;
+    };
+}
+/**
+ * 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>;
+    /**
+     * 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}` | `${number},${number}` | `${number},${number}min` | `${number},${number}m` | `${number},${number}sec` | `${number},${number}s` | `${number},${number}hour` | `${number},${number}h`;
+/**
+ * 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' | 'alpha' | 'alphanumeric' | 'uuid' | 'slug' | RegExp | 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;
+/**
+ * Extract parameters from route path
+ */
+export type ExtractRouteParams<T extends string> = T extends `${string}{${infer Param}}${infer Rest}` ? {
+    [K in Param]: string;
+} & ExtractRouteParams<Rest> : 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 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 502 | 503 | 504;
+/**
+ * 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 = '/' | '/health' | '/api' | '/api/v1' | '/api/v1/users' | '/api/v1/users/{id}' | '/api/v1/users/{userId}/posts' | '/api/v1/users/{userId}/posts/{postId}' | '/admin' | '/admin/{section}' | '/auth/login' | '/auth/logout' | '/auth/register' | '/auth/forgot-password' | '/uploads/{filename}' | '/assets/{path}';
+/**
+ * RESTful resource route patterns
+ */
+export type ResourceRoutePatterns<T extends string> = `/${T}` | `/${T}/{id}` | `/${T}/create` | `/${T}/{id}/edit` | `/${T}/{id}/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;
+    parameter: string;
+    required?: boolean;
+    as?: string;
+    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 {
+    data: any;
+    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 {
+    wantsJson: () => boolean;
+    wantsHtml: () => boolean;
+    wantsXml: () => boolean;
+    expectsJson: () => boolean;
+    isAjax: () => boolean;
+    isPjax: () => boolean;
+    isMobile: () => boolean;
+    isBot: () => boolean;
+    isSecure: () => boolean;
+    ip: () => string;
+    ips: () => string[];
+    userAgent: () => string;
+    referer: () => string | null;
+    bearerToken: () => string | null;
+    basicAuth: () => {
+        username: string;
+        password: string;
+    } | null;
+    hasHeader: (name: string) => boolean;
+    header: (name: string, defaultValue?: string) => string | null;
+    allHeaders: () => Record<string, string>;
+    input: <T = InputValue>(key: string, defaultValue?: T) => T;
+    all: () => RequestInput;
+    only: (keys: string[]) => RequestInput;
+    except: (keys: string[]) => RequestInput;
+    has: (key: string) => boolean;
+    hasAny: (keys: string[]) => boolean;
+    missing: (key: string) => boolean;
+    filled: (key: string) => boolean;
+    getQuery: <T = InputValue>(key?: string, defaultValue?: T) => T;
+    param: <T = InputValue>(key: string, defaultValue?: T) => T;
+    cookie: (name: string, defaultValue?: string) => string | null;
+    cookies: () => Record<string, string>;
+    file: (name: string) => FileInfo | null;
+    hasFile: (name: string) => boolean;
+    path: () => string;
+    fullUrl: () => string;
+    root: () => string;
+    is: (pattern: string) => boolean;
+    route: () => string | null;
+    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;
+}