blaizejs 0.5.2 → 0.5.3

package/dist/index.d.ts

@@ -8,1697 +8,1671 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
 
 /**
- * Error type definitions and interfaces for the BlaizeJS framework
- *
- * This module contains all the type definitions used for error handling
- * across the BlaizeJS framework, including server-side errors, client-side
- * errors, and HTTP response formats.
+ * Represents an uploaded file in a multipart/form-data request
  */
+interface UploadedFile {
+    /** Original filename provided by the client (may be undefined) */
+    readonly filename: string | undefined;
+    /** Form field name this file was uploaded under */
+    readonly fieldname: string;
+    /** MIME type of the uploaded file */
+    readonly mimetype: string;
+    /** Size of the file in bytes */
+    readonly size: number;
+    /** Stream containing the file data (always available) */
+    readonly stream: Readable;
+    /** Buffer containing file data (only available with 'memory' strategy) */
+    readonly buffer?: Buffer;
+    /** Path to temporary file (only available with 'temp' strategy) */
+    readonly tempPath?: string;
+    /** SHA-256 hash of file content (if computed) */
+    readonly hash?: string;
+}
 /**
- * Structure of error responses sent over HTTP
- *
- * This interface defines the JSON format used for all error responses
- * from BlaizeJS servers. It matches the structure returned by BlaizeError.toJSON()
- *
- * @example
- * ```json
- * {
- *   "type": "VALIDATION_ERROR",
- *   "title": "Request validation failed",
- *   "status": 400,
- *   "correlationId": "req_abc123",
- *   "timestamp": "2024-01-15T10:30:00.000Z",
- *   "details": {
- *     "fields": ["email", "password"]
- *   }
- * }
- * ```
+ * Complete multipart/form-data parsed content
  */
-interface BlaizeErrorResponse {
-    /** Error type from the ErrorType enum */
-    type: ErrorType;
-    /** Human-readable error message */
-    title: string;
-    /** HTTP status code */
-    status: number;
-    /** Correlation ID for request tracing */
-    correlationId: string;
-    /** ISO timestamp when error occurred */
-    timestamp: string;
-    /** Optional error-specific details */
-    details?: unknown;
+interface MultipartData {
+    /** Form fields (non-file inputs) */
+    readonly fields: Record<string, string | string[]>;
+    /** Uploaded files */
+    readonly files: Record<string, UploadedFile | UploadedFile[]>;
 }
 /**
- * Context information for network-related errors
- *
- * Used by client-side error classes to provide additional context
- * about network failures, timeouts, and connection issues.
+ * Options for parsing multipart/form-data
  */
-interface NetworkErrorContext {
-    /** The URL that failed */
-    url: string;
-    /** HTTP method being attempted */
-    method: string;
-    /** Correlation ID for tracing */
-    correlationId: string;
-    /** Timeout value if applicable */
-    timeout?: number;
-    /** The original error that caused the network failure */
-    originalError: Error;
-    /** Additional network-specific details */
-    networkDetails?: {
-        /** Whether this was a connection timeout */
-        isTimeout?: boolean;
-        /** Whether this was a DNS resolution failure */
-        isDnsFailure?: boolean;
-        /** Whether this was a connection refused error */
-        isConnectionRefused?: boolean;
-        /** HTTP status code if received before failure */
-        statusCode?: number;
-    };
+interface ParseOptions {
+    /** Maximum size for individual files in bytes (default: 10MB) */
+    readonly maxFileSize?: number;
+    /** Maximum number of files per request (default: 10) */
+    readonly maxFiles?: number;
+    /** Maximum size for form fields in bytes (default: 1MB) */
+    readonly maxFieldSize?: number;
+    /** Allowed MIME types (empty array = allow all) */
+    readonly allowedMimeTypes?: readonly string[];
+    /** Allowed file extensions (empty array = allow all) */
+    readonly allowedExtensions?: readonly string[];
+    /** Processing strategy for file data */
+    readonly strategy: 'memory' | 'stream' | 'temp';
+    /** Directory for temporary files (strategy: 'temp' only) */
+    readonly tempDir?: string;
+    /** Whether to compute SHA-256 hash of files */
+    readonly computeHash?: boolean;
 }
 /**
- * Context information for request timeout errors
- *
- * Specialized context for timeout-specific errors with timing information.
+ * Result of parsing multipart data with metadata
  */
-interface TimeoutErrorContext {
-    /** The URL that timed out */
-    url: string;
-    /** HTTP method being attempted */
-    method: string;
-    /** Correlation ID for tracing */
-    correlationId: string;
-    /** Configured timeout value in milliseconds */
-    timeoutMs: number;
-    /** Actual duration before timeout in milliseconds */
-    elapsedMs: number;
-    /** Type of timeout (request, connection, etc.) */
-    timeoutType: 'request' | 'connection' | 'response' | 'idle';
+interface ParseResult {
+    /** Parsed multipart data */
+    readonly data: MultipartData;
+    /** Parsing metadata */
+    readonly metadata: {
+        /** Total time spent parsing (milliseconds) */
+        readonly parseTime: number;
+        /** Total size of all uploaded content */
+        readonly totalSize: number;
+        /** Number of files processed */
+        readonly fileCount: number;
+        /** Number of fields processed */
+        readonly fieldCount: number;
+    };
 }
 /**
- * Context information for response parsing errors
- *
- * Used when the client receives a response but cannot parse it properly.
+ * Error information for multipart parsing failures
  */
-interface ParseErrorContext {
-    /** The URL that returned unparseable content */
-    url: string;
-    /** HTTP method used */
-    method: string;
-    /** Correlation ID for tracing */
-    correlationId: string;
-    /** HTTP status code received */
-    statusCode: number;
-    /** Content-Type header if available */
-    contentType?: string;
-    /** Expected response format */
-    expectedFormat: 'json' | 'text' | 'binary';
-    /** Sample of the actual response content (truncated for safety) */
-    responseSample?: string;
-    /** The original parsing error */
-    originalError: Error;
+interface MultipartError {
+    /** Error type/code */
+    readonly type: 'boundary_missing' | 'size_exceeded' | 'file_limit_exceeded' | 'mime_type_forbidden' | 'extension_forbidden' | 'parse_error' | 'stream_error' | 'temp_file_error';
+    /** Human-readable error message */
+    readonly message: string;
+    /** Additional context (field name, file name, etc.) */
+    readonly context?: Record<string, unknown>;
+    /** Original error if available */
+    readonly cause?: Error;
 }
 /**
- * Validation error field details
- *
- * Structure for field-level validation errors with multiple error messages
- * per field.
+ * Configuration for file upload validation
  */
-interface ValidationFieldError {
-    /** Field name or path (e.g., "email", "user.profile.name") */
-    field: string;
-    /** Array of error messages for this field */
-    messages: string[];
-    /** The invalid value that caused the error */
-    rejectedValue?: unknown;
-    /** Expected type or format */
-    expectedType?: string;
-}
-interface ServiceNotAvailableDetails {
-    /** Service that's unavailable */
-    service?: string;
-    /** Seconds to wait before retry */
-    retryAfter?: number;
-    /** Why service is unavailable */
-    reason?: 'maintenance' | 'overload' | 'circuit_breaker' | 'dependency_down';
-    /** Additional context */
-    [key: string]: unknown;
+interface ValidationConfig {
+    /** File size constraints */
+    readonly size?: {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    /** File count constraints */
+    readonly count?: {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    /** MIME type constraints */
+    readonly mimeTypes?: {
+        readonly allowed?: readonly string[];
+        readonly forbidden?: readonly string[];
+    };
+    /** File extension constraints */
+    readonly extensions?: {
+        readonly allowed?: readonly string[];
+        readonly forbidden?: readonly string[];
+    };
+    /** Custom validation function */
+    readonly custom?: (file: UploadedFile) => Promise<boolean> | boolean;
 }
 /**
- * Validation error details structure
- *
- * Used by ValidationError to provide structured information about
- * what fields failed validation and why.
+ * File processing configuration
  */
-interface ValidationErrorDetails {
-    /** Array of field-level errors */
-    fields: ValidationFieldError[];
-    /** Total number of validation errors */
-    errorCount: number;
-    /** The section that failed validation */
-    section: 'params' | 'query' | 'body' | 'response';
-    /** Schema name if available */
-    schemaName?: string;
+interface ProcessingConfig {
+    /** Whether to process files concurrently */
+    readonly concurrent?: boolean;
+    /** Maximum concurrent processing operations */
+    readonly maxConcurrency?: number;
+    /** Processing timeout in milliseconds */
+    readonly timeout?: number;
+    /** Whether to preserve original files during processing */
+    readonly preserveOriginal?: boolean;
 }
 /**
- * All available error types in the BlaizeJS framework
- *
- * This enum provides both compile-time type safety and runtime values
- * for error type identification across server and client packages.
- *
- * @example Type-safe error handling:
- * ```typescript
- * function handleError(errorType: ErrorType) {
- *   switch (errorType) {
- *     case ErrorType.VALIDATION_ERROR:
- *       // Handle validation error
- *       break;
- *     case ErrorType.NOT_FOUND:
- *       // Handle not found error
- *       break;
- *     // TypeScript ensures all cases are covered
- *   }
- * }
- * ```
+ * Upload progress information (for future streaming uploads)
  */
-declare enum ErrorType {
-    /** Request validation failed (400) */
-    VALIDATION_ERROR = "VALIDATION_ERROR",
-    /** Resource not found (404) */
-    NOT_FOUND = "NOT_FOUND",
-    /** Authentication required (401) */
-    UNAUTHORIZED = "UNAUTHORIZED",
-    /** Access forbidden (403) */
-    FORBIDDEN = "FORBIDDEN",
-    /** SSE Not Acceptable (406) */
-    SSE_NOT_ACCEPTABLE = "SSE_NOT_ACCEPTABLE",
-    /** Resource conflict (409) */
-    CONFLICT = "CONFLICT",
-    /** Rate limit exceeded (429) */
-    RATE_LIMITED = "RATE_LIMITED",
-    /** Internal server error (500) */
-    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
-    /** File/Request Too Large (413) */
-    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
-    /** Wrong Content Type (415) */
-    UNSUPPORTED_MEDIA_TYPE = "UNSUPPORTED_MEDIA_TYPE",
-    /** Upload Timeout (408) */
-    UPLOAD_TIMEOUT = "UPLOAD_TIMEOUT",
-    /** Valid Format Invalid Semantics (422) */
-    UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
-    /** Network connectivity failure (0) */
-    NETWORK_ERROR = "NETWORK_ERROR",
-    /** Request or response timeout (0) */
-    TIMEOUT_ERROR = "TIMEOUT_ERROR",
-    /** Response parsing failure (0) */
-    PARSE_ERROR = "PARSE_ERROR",
-    /** Generic HTTP error (varies) */
-    HTTP_ERROR = "HTTP_ERROR",
-    /** SSE connection failed (502) */
-    SSE_CONNECTION_ERROR = "SSE_CONNECTION_ERROR",
-    /** SSE buffer overflow (503) */
-    SSE_BUFFER_OVERFLOW = "SSE_BUFFER_OVERFLOW",
-    /** SSE stream closed (410) */
-    SSE_STREAM_CLOSED = "SSE_STREAM_CLOSED",
-    /** Service temporarily unavailable (503) */
-    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
-}
-/**
- * Error severity levels for logging and monitoring
- *
- * Provides a way to categorize errors by their impact and urgency.
- */
-declare enum ErrorSeverity {
-    /** Low impact, often user errors */
-    LOW = "low",
-    /** Medium impact, application errors */
-    MEDIUM = "medium",
-    /** High impact, system errors */
-    HIGH = "high",
-    /** Critical impact, service disruption */
-    CRITICAL = "critical"
+interface UploadProgress {
+    /** Bytes uploaded so far */
+    readonly bytesUploaded: number;
+    /** Total bytes to upload */
+    readonly totalBytes: number;
+    /** Upload percentage (0-100) */
+    readonly percentage: number;
+    /** Upload speed in bytes per second */
+    readonly speed: number;
+    /** Estimated time remaining in milliseconds */
+    readonly eta: number;
 }
 /**
- * Abstract base class for all BlaizeJS errors
- *
- * This class provides the foundation for all error types in the BlaizeJS framework.
- * It extends JavaScript's built-in Error class and adds framework-specific properties
- * for consistent error handling across server and client.
- *
- * @example
- * ```typescript
- * import { ErrorType } from './types';
- *
- * class NotFoundError extends BlaizeError<{ resourceId: string }> {
- *   constructor(message = 'Resource not found', details?: { resourceId: string }) {
- *     super(ErrorType.NOT_FOUND, message, 404, getCurrentCorrelationId(), details);
- *   }
- * }
- * ```
- *
- * @template TDetails - Type for error-specific details object
+ * Internal state for multipart parser state machine
  */
-declare abstract class BlaizeError<TDetails = unknown> extends Error {
-    /**
-     * Error type identifier from the ErrorType enum
-     * Used for programmatic error handling and client-side error routing
-     */
-    readonly type: ErrorType;
-    /**
-     * Human-readable error title/message
-     * Should be descriptive enough for debugging but safe for end users
-     */
-    readonly title: string;
-    /**
-     * HTTP status code associated with this error
-     * Used by the error boundary to set appropriate response status
-     */
-    readonly status: number;
-    /**
-     * Correlation ID for request tracing
-     * Links this error to the specific request that generated it
-     */
-    readonly correlationId: string;
-    /**
-     * Timestamp when the error occurred
-     * Useful for debugging and log correlation
-     */
-    readonly timestamp: Date;
-    /**
-     * Additional error-specific details
-     * Type-safe error context that varies by error type
-     */
-    readonly details?: TDetails | undefined;
+interface ParserState {
+    boundary: Buffer;
+    options: Required<ParseOptions>;
+    fields: Map<string, string[]>;
+    files: Map<string, UploadedFile[]>;
+    buffer: Buffer;
+    stage: 'boundary' | 'headers' | 'content';
+    currentHeaders: string;
+    currentField: string | null;
+    currentFilename: string | undefined;
+    currentMimetype: string;
+    currentContentLength: number;
+    fileCount: number;
+    fieldCount: number;
+    currentBufferChunks: Buffer[];
+    currentStream: Readable | null;
+    currentTempPath: string | null;
+    currentWriteStream: WriteStream | null;
+    streamController: ReadableStreamDefaultController<Uint8Array> | null;
+    cleanupTasks: Array<() => Promise<void>>;
     /**
-     * Creates a new BlaizeError instance
-     *
-     * @param type - Error type from the ErrorType enum
-     * @param title - Human-readable error message
-     * @param status - HTTP status code
-     * @param correlationId - Request correlation ID for tracing
-     * @param details - Optional error-specific details
+     * Whether we've found at least one valid boundary marker
      */
-    protected constructor(type: ErrorType, title: string, status: number, correlationId: string, details?: TDetails | undefined);
+    hasFoundValidBoundary: boolean;
     /**
-     * Serializes the error to a plain object suitable for HTTP responses
-     *
-     * @returns Object representation of the error
+     * Whether we've successfully processed at least one complete part (field or file)
      */
-    toJSON(): {
-        type: ErrorType;
-        title: string;
-        status: number;
-        correlationId: string;
-        timestamp: string;
-    } | {
-        details: TDetails & ({} | null);
-        type: ErrorType;
-        title: string;
-        status: number;
-        correlationId: string;
-        timestamp: string;
-    };
+    hasProcessedAnyPart: boolean;
     /**
-     * Returns a string representation of the error
-     * Includes correlation ID for easier debugging
+     * Whether parsing has reached the end boundary
      */
-    toString(): string;
+    isFinished: boolean;
 }
+
 /**
- * Interface for payload too large error details
+ * Unified request type supporting both HTTP/1.1 and HTTP/2
  */
-interface PayloadTooLargeErrorDetails {
-    fileCount?: number;
-    maxFiles?: number;
-    filename?: string;
-    field?: string;
-    contentType?: string;
-    currentSize?: number;
-    maxSize?: number;
-}
+type UnifiedRequest = IncomingMessage | Http2ServerRequest;
 /**
- * Interface for unsupported media type error details
+ * Unified response type supporting both HTTP/1.1 and HTTP/2
  */
-interface UnsupportedMediaTypeErrorDetails {
-    receivedMimeType?: string;
-    allowedMimeTypes?: string[];
-    filename?: string;
+type UnifiedResponse = ServerResponse | Http2ServerResponse;
+/**
+ * Request parameters extracted from URL path
+ */
+interface RequestParams {
+    [key: string]: string;
 }
 /**
- * Interface for authentication error details
+ * Query parameters from URL
  */
-interface UnauthorizedErrorDetails {
-    /** Reason for authentication failure */
-    reason?: 'missing_token' | 'invalid_token' | 'expired_token' | 'malformed_token' | 'insufficient_scope' | string;
-    /** Authentication scheme (Bearer, Basic, etc.) */
-    authScheme?: string;
-    /** Authentication realm */
-    realm?: string;
-    /** Detailed error description */
-    error_description?: string;
-    /** Required scopes or permissions */
-    requiredScopes?: string[];
-    /** Login URL for interactive authentication */
-    loginUrl?: string;
-    /** Additional context */
-    [key: string]: unknown;
+interface QueryParams {
+    [key: string]: string | string[] | undefined;
 }
 /**
- * Interface for authorization/permission error details
+ * Options for streaming responses
  */
-interface ForbiddenErrorDetails {
-    /** Required permission or role */
-    requiredPermission?: string;
-    /** User's current permissions */
-    userPermissions?: string[];
-    /** Resource being accessed */
-    resource?: string;
-    /** Action being attempted */
-    action?: string;
-    /** Reason for access denial */
-    reason?: 'insufficient_permissions' | 'account_suspended' | 'resource_locked' | 'origin_not_allowed' | string;
-    /** Additional context */
-    [key: string]: unknown;
+interface StreamOptions {
+    contentType?: string;
+    status?: number;
+    headers?: Record<string, string>;
 }
 /**
- * Interface for resource conflict error details
+ * State container for storing request-scoped data
+ * Allows for proper typing with generics
  */
-interface ConflictErrorDetails {
-    /** Type of conflict */
-    conflictType?: 'duplicate_key' | 'version_mismatch' | 'concurrent_modification' | 'business_rule' | string;
-    /** Field that caused the conflict */
-    field?: string;
-    /** Existing value that conflicts */
-    existingValue?: unknown;
-    /** Provided value that conflicts */
-    providedValue?: unknown;
-    /** Resource that has the conflicting value */
-    conflictingResource?: string;
-    /** Current version/etag of the resource */
-    currentVersion?: string;
-    /** Expected version/etag */
-    expectedVersion?: string;
-    /** Suggested resolution */
-    resolution?: string;
-    /** Additional context */
+interface State {
     [key: string]: unknown;
 }
 /**
- * Interface for rate limiting error details
+ * Services container for storing injectable services/dependencies
+ * Allows middleware to contribute services that are accessible throughout the request lifecycle
  */
-interface RateLimitErrorDetails {
-    /** Maximum requests allowed in the time window */
-    limit?: number;
-    /** Remaining requests in current window */
-    remaining?: number;
-    /** When the rate limit resets */
-    resetTime?: Date;
-    /** Seconds until the rate limit resets */
-    retryAfter?: number;
-    /** Time window for the rate limit */
-    window?: string;
-    /** Identifier used for rate limiting (IP, user ID, etc.) */
-    identifier?: string;
-    /** Type of rate limit hit */
-    limitType?: 'global' | 'per_user' | 'per_ip' | 'per_endpoint' | string;
-    /** Additional context */
+interface Services {
     [key: string]: unknown;
 }
-/**
- * Interface for internal server error details
- */
-interface InternalServerErrorDetails {
-    /** Original error message (for debugging) */
-    originalError?: string;
-    /** Stack trace (for debugging) */
-    stackTrace?: string;
-    /** Component where the error occurred */
-    component?: string;
-    /** Operation being performed */
-    operation?: string;
-    /** Internal error code */
-    internalErrorCode?: string;
-    /** When the error occurred */
-    timestamp?: Date;
-    /** Whether this error should be retryable */
-    retryable?: boolean;
-    /** Additional debugging context */
-    [key: string]: unknown;
+interface ContextResponse<S extends State = State> {
+    raw: UnifiedResponse;
+    sent: boolean;
+    statusCode: number;
+    status: (code: number) => ContextResponse<S>;
+    header: (name: string, value: string) => ContextResponse<S>;
+    headers: (headers: Record<string, string>) => ContextResponse<S>;
+    type: (contentType: string) => ContextResponse<S>;
+    json: (body: unknown, status?: number) => void;
+    text: (body: string, status?: number) => void;
+    html: (body: string, status?: number) => void;
+    redirect: (url: string, status?: number) => void;
+    stream: (readable: NodeJS.ReadableStream, options?: StreamOptions) => void;
+}
+interface ContextRequest<TBody = unknown> {
+    raw: UnifiedRequest;
+    method: string;
+    path: string;
+    url: URL | null;
+    query: QueryParams;
+    params: RequestParams;
+    protocol: string;
+    isHttp2: boolean;
+    body?: TBody;
+    /**
+     * Uploaded files from multipart/form-data requests
+     * Available when Content-Type is multipart/form-data
+     */
+    files?: Record<string, UploadedFile | UploadedFile[]>;
+    /**
+     * Complete multipart data (files + fields)
+     * Available when Content-Type is multipart/form-data
+     */
+    multipart?: MultipartData;
+    header: (name: string) => string | undefined;
+    headers: (names?: string[]) => Record<string, string | undefined>;
 }
 /**
- * Interface for NotFound error details
- * Provides context about the missing resource
+ * Context object representing a request/response cycle
+ * @template S - Type of the state object
+ * @template Svc - Type of the services object
+ * @template TBody - Type of the request body
+ * @template TQuery - Type of the query parameters
  */
-interface NotFoundErrorDetails {
-    /** Type of resource that was not found */
-    resourceType?: string;
-    /** ID or identifier of the resource */
-    resourceId?: string;
-    /** Collection or table where the resource was searched */
-    collection?: string;
-    /** Search criteria that was used */
-    query?: Record<string, unknown>;
-    /** Search criteria that was used (for backward compatibility) */
-    searchCriteria?: Record<string, unknown>;
-    /** The path that was attempted */
-    path?: string;
-    /** HTTP method used (for API endpoints) */
-    method?: string;
-    /** The path that was attempted (for backward compatibility) */
-    attemptedPath?: string;
-    /** Parent resource information for nested resources */
-    parentResource?: {
-        type: string;
-        id: string;
+interface Context<S extends State = State, Svc extends Services = Services, TBody = unknown, TQuery = QueryParams> {
+    /**
+     * Request information
+     */
+    request: Omit<ContextRequest, 'body' | 'query'> & {
+        body: TBody;
+        query: TQuery;
     };
-    /** Helpful suggestion for the user */
-    suggestion?: string;
-    /** Additional context */
-    [key: string]: unknown;
+    /**
+     * Response handling
+     */
+    response: ContextResponse<S>;
+    /**
+     * Request-scoped state for storing data during the request lifecycle
+     */
+    state: S;
+    /**
+     * Services container for accessing injected services/dependencies
+     * Populated by middleware that contribute services
+     */
+    services: Svc;
 }
+interface BodyLimits {
+    /** Maximum JSON body size in bytes (default: 512KB) */
+    json: number;
+    /** Maximum form data size in bytes (default: 1MB) */
+    form: number;
+    /** Maximum text body size in bytes (default: 5MB) */
+    text: number;
+    /** Maximum raw/binary body size in bytes (default: 10MB) */
+    raw: number;
+    /** Multipart/form-data limits */
+    multipart: MultipartLimits;
+}
+type MultipartLimits = {
+    maxFileSize?: number;
+    maxTotalSize?: number;
+    maxFiles?: number;
+    maxFieldSize?: number;
+};
 /**
- * Interface for body parsing errors stored in context state
+ * Options for creating a context
  */
-interface BodyParseError {
+interface ContextOptions {
+    /**
+     * Whether to parse the request body
+     */
+    parseBody?: boolean;
     /**
-     * Type of parsing error that occurred
+     * Initial state to include in the context
+     *
      */
-    readonly type: 'json_parse_error' | 'form_parse_error' | 'multipart_parse_error' | 'body_read_error';
+    initialState?: State;
     /**
-     * Human-readable error message
+     * Initial services to include in the context
+     *
      */
-    readonly message: string;
+    initialServices?: Services;
     /**
-     * Original error object or details
+     * Limits for various body types to prevent abuse
      */
-    readonly error: unknown;
+    bodyLimits: BodyLimits;
 }
 /**
- * Type guard to check if an object is a BodyParseError
+ * Function to get the current context from AsyncLocalStorage
  */
-declare function isBodyParseError(error: unknown): error is BodyParseError;
+type GetContextFn = <S extends State = State, Svc extends Services = Services>() => Context<S, Svc> | undefined;
 /**
- * Context information for error transformation
+ * Factory function for creating a new context
  */
-interface ErrorTransformContext {
-    url: string;
-    method: string;
-    correlationId: string;
-    timeoutMs?: number;
-    elapsedMs?: number;
-    statusCode?: number;
-    contentType?: string;
-    responseSample?: string;
-    [key: string]: unknown;
-}
+type CreateContextFn = (req: UnifiedRequest, res: UnifiedResponse, options?: ContextOptions) => Promise<Context>;
 /**
- * SSE-specific error detail interfaces for BlaizeJS framework
+ * Type representing unknown function
  *
- * These interfaces define the structure of details for SSE errors.
- * The actual error classes are implemented in blaize-core.
+ * This is a generic function type that can accept any number of arguments
+ * and return any type of value. It is used for type inference in various
+ * contexts where the specific function signature is not known or not
+ * important.
  */
+type UnknownFunction = (...args: unknown[]) => unknown;
+
 /**
- * Details for SSE connection errors
+ * Function to pass control to the next middleware
  */
-interface SSEConnectionErrorDetails {
-    /** Client identifier if available */
-    clientId?: string;
-    /** Connection attempt number */
-    attemptNumber?: number;
-    /** Maximum retry attempts configured */
-    maxRetries?: number;
-    /** The underlying error that caused connection failure */
-    cause?: string;
-    /** Suggested resolution */
-    suggestion?: string;
-}
+type NextFunction = () => Promise<void> | void;
 /**
- * Details for SSE buffer overflow errors
+ * Middleware function signature
  */
-interface SSEBufferOverflowErrorDetails {
-    /** Client identifier */
-    clientId?: string;
-    /** Current buffer size when overflow occurred */
-    currentSize: number;
-    /** Maximum buffer size configured */
-    maxSize: number;
-    /** Number of events dropped */
-    eventsDropped?: number;
-    /** Buffer strategy that was applied */
-    strategy: 'drop-oldest' | 'drop-newest' | 'close';
-    /** Event that triggered the overflow */
-    triggeringEvent?: string;
+type MiddlewareFunction = (ctx: Context, next: NextFunction) => Promise<void> | void;
+/**
+ * Named middleware options
+ */
+interface MiddlewareOptions {
+    /** Name of the middleware for debugging and logging */
+    name?: string;
+    /** The middleware handler function */
+    handler: MiddlewareFunction;
+    /** Skip function to conditionally bypass middleware */
+    skip?: ((ctx: Context<any, any>) => boolean) | undefined;
+    /** Enable debugging for this middleware */
+    debug?: boolean;
 }
 /**
- * Details for SSE stream closed errors
+ * Middleware type with generic parameters for type-safe state and service contributions
+ * @template TState - Type of state this middleware contributes to the context
+ * @template TServices - Type of services this middleware contributes to the context
  */
-interface SSEStreamClosedErrorDetails {
-    /** Client identifier */
-    clientId?: string;
-    /** When the stream was closed */
-    closedAt?: string;
-    /** Reason for closure */
-    closeReason?: 'client-disconnect' | 'server-close' | 'timeout' | 'error' | 'buffer-overflow';
-    /** Whether reconnection is possible */
-    canReconnect?: boolean;
-    /** Suggested retry interval in milliseconds */
-    retryAfter?: number;
+interface Middleware<TState = {}, TServices = {}> {
+    name: string;
+    execute: MiddlewareFunction;
+    skip?: ((ctx: Context) => boolean) | undefined;
+    debug?: boolean | undefined;
+    _services?: TServices;
 }
+
 /**
- * Context for SSE connection errors
+ * Helper type to extract TypeScript type from Zod schema
  */
-interface SSEConnectionErrorContext {
-    /** The SSE endpoint URL */
-    url: string;
-    /** Correlation ID for tracing */
-    correlationId: string;
-    /** Connection state when error occurred */
-    state: 'connecting' | 'connected' | 'disconnected' | 'closed';
-    /** Number of reconnection attempts made */
-    reconnectAttempts?: number;
-    /** The original error if available */
-    originalError?: Error;
-    /** Additional SSE-specific details */
-    sseDetails?: {
-        /** Whether credentials were included */
-        withCredentials?: boolean;
-        /** Last received event ID */
-        lastEventId?: string;
-        /** EventSource ready state */
-        readyState?: number;
-    };
-}
+type Infer<T> = T extends z.ZodType ? z.output<T> : unknown;
 /**
- * Context for SSE stream errors (server-sent errors)
+ * HTTP methods supported by the router
  */
-interface SSEStreamErrorContext {
-    /** The SSE endpoint URL */
-    url: string;
-    /** Correlation ID from server or client */
-    correlationId: string;
-    /** Error message from server */
-    message: string;
-    /** Error code if provided */
-    code?: string;
-    /** Error name/type from server */
-    name?: string;
-    /** Raw error data from server */
-    rawData?: any;
-}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
 /**
- * Context for SSE heartbeat timeout errors
+ * Schema for route validation with generic type parameters
  */
-interface SSEHeartbeatErrorContext {
-    /** The SSE endpoint URL */
-    url: string;
-    /** Correlation ID for tracing */
-    correlationId: string;
-    /** Configured heartbeat timeout in ms */
-    heartbeatTimeout: number;
-    /** Time since last event in ms */
-    timeSinceLastEvent?: number;
-    /** Last event ID received */
-    lastEventId?: string;
+interface RouteSchema<P extends z.ZodType = z.ZodType<any>, // URL parameters schema
+Q extends z.ZodType = z.ZodType<any>, // Query parameters schema
+B extends z.ZodType = z.ZodType<any>, // Body schema
+R extends z.ZodType = z.ZodType<any>, // Response schema
+ED extends z.ZodType = z.ZodType<any>> {
+    /** Parameter schema for validation */
+    params?: P;
+    /** Query schema for validation */
+    query?: Q;
+    /** Body schema for validation */
+    body?: B;
+    /** Response schema for validation */
+    response?: R;
+    /** Error Response Details schema for validation */
+    errorResponseDetails?: ED;
 }
-
 /**
- * Represents an uploaded file in a multipart/form-data request
+ * Route handler function with strongly typed params and response
  */
-interface UploadedFile {
-    /** Original filename provided by the client (may be undefined) */
-    readonly filename: string | undefined;
-    /** Form field name this file was uploaded under */
-    readonly fieldname: string;
-    /** MIME type of the uploaded file */
-    readonly mimetype: string;
-    /** Size of the file in bytes */
-    readonly size: number;
-    /** Stream containing the file data (always available) */
-    readonly stream: Readable;
-    /** Buffer containing file data (only available with 'memory' strategy) */
-    readonly buffer?: Buffer;
-    /** Path to temporary file (only available with 'temp' strategy) */
-    readonly tempPath?: string;
-    /** SHA-256 hash of file content (if computed) */
-    readonly hash?: string;
+type RouteHandler<TParams = Record<string, string>, TQuery = Record<string, string | string[] | undefined>, TBody = unknown, TResponse = unknown, TState extends State = State, // NEW in v0.4.0
+TServices extends Services = Services> = (ctx: Context<TState, TServices, TBody, TQuery>, params: TParams) => Promise<TResponse> | TResponse;
+/**
+ * Options for a route method with schema-based type inference
+ */
+interface RouteMethodOptions<P extends z.ZodType = z.ZodType<any>, Q extends z.ZodType = z.ZodType<any>, B extends z.ZodType = z.ZodType<any>, R extends z.ZodType = z.ZodType<any>, ED extends z.ZodType = z.ZodType<any>> {
+    /** Schema for request/response validation */
+    schema?: RouteSchema<P, Q, B, R, ED>;
+    /** Handler function for the route */
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, R extends z.ZodType ? Infer<R> : unknown>;
+    /** Middleware to apply to this route */
+    middleware?: Middleware[];
+    /** Route-specific options */
+    options?: Record<string, unknown>;
 }
 /**
- * Complete multipart/form-data parsed content
+ * Route definition mapping HTTP methods to handlers
  */
-interface MultipartData {
-    /** Form fields (non-file inputs) */
-    readonly fields: Record<string, string | string[]>;
-    /** Uploaded files */
-    readonly files: Record<string, UploadedFile | UploadedFile[]>;
+interface RouteDefinition {
+    GET?: RouteMethodOptions<any, any, never, any, any>;
+    POST?: RouteMethodOptions<any, any, any, any, any>;
+    PUT?: RouteMethodOptions<any, any, any, any, any>;
+    DELETE?: RouteMethodOptions<any, any, never, any, any>;
+    PATCH?: RouteMethodOptions<any, any, any, any, any>;
+    HEAD?: RouteMethodOptions<any, any, never, any, any>;
+    OPTIONS?: RouteMethodOptions<any, any, never, any, any>;
 }
 /**
- * Options for parsing multipart/form-data
+ * Route object with path
  */
-interface ParseOptions {
-    /** Maximum size for individual files in bytes (default: 10MB) */
-    readonly maxFileSize?: number;
-    /** Maximum number of files per request (default: 10) */
-    readonly maxFiles?: number;
-    /** Maximum size for form fields in bytes (default: 1MB) */
-    readonly maxFieldSize?: number;
-    /** Allowed MIME types (empty array = allow all) */
-    readonly allowedMimeTypes?: readonly string[];
-    /** Allowed file extensions (empty array = allow all) */
-    readonly allowedExtensions?: readonly string[];
-    /** Processing strategy for file data */
-    readonly strategy: 'memory' | 'stream' | 'temp';
-    /** Directory for temporary files (strategy: 'temp' only) */
-    readonly tempDir?: string;
-    /** Whether to compute SHA-256 hash of files */
-    readonly computeHash?: boolean;
+interface Route extends RouteDefinition {
+    /** Path of the route */
+    path: string;
 }
 /**
- * Result of parsing multipart data with metadata
+ * Options for route creation
  */
-interface ParseResult {
-    /** Parsed multipart data */
-    readonly data: MultipartData;
-    /** Parsing metadata */
-    readonly metadata: {
-        /** Total time spent parsing (milliseconds) */
-        readonly parseTime: number;
-        /** Total size of all uploaded content */
-        readonly totalSize: number;
-        /** Number of files processed */
-        readonly fileCount: number;
-        /** Number of fields processed */
-        readonly fieldCount: number;
-    };
+interface RouteOptions {
+    /** Base path for the route */
+    basePath?: string;
 }
 /**
- * Error information for multipart parsing failures
+ * Result type for handling success and error responses
  */
-interface MultipartError {
-    /** Error type/code */
-    readonly type: 'boundary_missing' | 'size_exceeded' | 'file_limit_exceeded' | 'mime_type_forbidden' | 'extension_forbidden' | 'parse_error' | 'stream_error' | 'temp_file_error';
-    /** Human-readable error message */
-    readonly message: string;
-    /** Additional context (field name, file name, etc.) */
-    readonly context?: Record<string, unknown>;
-    /** Original error if available */
-    readonly cause?: Error;
+type Result<T, E = {
+    error: string;
+    message: string;
+    details?: unknown;
+}> = {
+    success: true;
+    data: T;
+    status?: number;
+} | {
+    success: false;
+    error: E;
+    status?: number;
+};
+/**
+ * Router options
+ */
+interface RouterOptions {
+    /** Directory containing route files */
+    routesDir: string;
+    /** Base path for all routes */
+    basePath?: string;
+    /** Watch for file changes in development */
+    watchMode?: boolean;
 }
 /**
- * Configuration for file upload validation
+ * Router interface
  */
-interface ValidationConfig {
-    /** File size constraints */
-    readonly size?: {
-        readonly min?: number;
-        readonly max?: number;
-    };
-    /** File count constraints */
-    readonly count?: {
-        readonly min?: number;
-        readonly max?: number;
-    };
-    /** MIME type constraints */
-    readonly mimeTypes?: {
-        readonly allowed?: readonly string[];
-        readonly forbidden?: readonly string[];
-    };
-    /** File extension constraints */
-    readonly extensions?: {
-        readonly allowed?: readonly string[];
-        readonly forbidden?: readonly string[];
+interface Router {
+    /** Handle an incoming request */
+    handleRequest: (ctx: Context) => Promise<void>;
+    /** Get all registered routes */
+    getRoutes: () => Route[];
+    /** Add a route programmatically */
+    addRoute: (route: Route) => void;
+    /** Add multiple routes programmatically with batch processing */
+    addRoutes: (routes: Route[]) => {
+        added: Route[];
+        removed: string[];
+        changed: Route[];
     };
-    /** Custom validation function */
-    readonly custom?: (file: UploadedFile) => Promise<boolean> | boolean;
+    /** Add a route directory for plugins */
+    addRouteDirectory(directory: string, options?: {
+        prefix?: string;
+    }): Promise<void>;
+    /** Get route conflicts */
+    getRouteConflicts(): Array<{
+        path: string;
+        sources: string[];
+    }>;
+    /** Close watchers and cleanup resources */
+    close?: () => Promise<void>;
 }
 /**
- * File processing configuration
+ * Route match result
  */
-interface ProcessingConfig {
-    /** Whether to process files concurrently */
-    readonly concurrent?: boolean;
-    /** Maximum concurrent processing operations */
-    readonly maxConcurrency?: number;
-    /** Processing timeout in milliseconds */
-    readonly timeout?: number;
-    /** Whether to preserve original files during processing */
-    readonly preserveOriginal?: boolean;
+interface RouteMatch {
+    /** The matched route handler (null if method not allowed) */
+    route: RouteMethodOptions | null;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Flag indicating if the path exists but method isn't allowed */
+    methodNotAllowed?: boolean;
+    /** List of allowed methods for this path (when method not allowed) */
+    allowedMethods?: HttpMethod[];
 }
 /**
- * Upload progress information (for future streaming uploads)
+ * Route matcher interface
  */
-interface UploadProgress {
-    /** Bytes uploaded so far */
-    readonly bytesUploaded: number;
-    /** Total bytes to upload */
-    readonly totalBytes: number;
-    /** Upload percentage (0-100) */
-    readonly percentage: number;
-    /** Upload speed in bytes per second */
-    readonly speed: number;
-    /** Estimated time remaining in milliseconds */
-    readonly eta: number;
+interface Matcher {
+    /** Add a route to the matcher */
+    add: (path: string, method: HttpMethod, route: RouteMethodOptions) => void;
+    /** Match a URL path to a route */
+    match: (path: string, method: HttpMethod) => RouteMatch | null;
+    /** Get all registered routes */
+    getRoutes: () => {
+        path: string;
+        method: HttpMethod;
+    }[];
+    /** Find routes matching a specific path */
+    findRoutes: (path: string) => {
+        path: string;
+        method: HttpMethod;
+        params: Record<string, string>;
+    }[];
+    /** Remove a route from the matcher (optional for compatibility) */
+    remove: (path: string) => void;
+    /** Clear all routes from the matcher (optional for compatibility) */
+    clear: () => void;
 }
-/**
- * Internal state for multipart parser state machine
- */
-interface ParserState {
-    boundary: Buffer;
-    options: Required<ParseOptions>;
-    fields: Map<string, string[]>;
-    files: Map<string, UploadedFile[]>;
-    buffer: Buffer;
-    stage: 'boundary' | 'headers' | 'content';
-    currentHeaders: string;
-    currentField: string | null;
-    currentFilename: string | undefined;
-    currentMimetype: string;
-    currentContentLength: number;
-    fileCount: number;
-    fieldCount: number;
-    currentBufferChunks: Buffer[];
-    currentStream: Readable | null;
-    currentTempPath: string | null;
-    currentWriteStream: WriteStream | null;
-    streamController: ReadableStreamDefaultController<Uint8Array> | null;
-    cleanupTasks: Array<() => Promise<void>>;
-    /**
-     * Whether we've found at least one valid boundary marker
-     */
-    hasFoundValidBoundary: boolean;
-    /**
-     * Whether we've successfully processed at least one complete part (field or file)
-     */
-    hasProcessedAnyPart: boolean;
-    /**
-     * Whether parsing has reached the end boundary
-     */
-    isFinished: boolean;
+interface ParsedRoute {
+    filePath: string;
+    routePath: string;
+    params: string[];
 }
-
-/**
- * Unified request type supporting both HTTP/1.1 and HTTP/2
- */
-type UnifiedRequest = IncomingMessage | Http2ServerRequest;
-/**
- * Unified response type supporting both HTTP/1.1 and HTTP/2
- */
-type UnifiedResponse = ServerResponse | Http2ServerResponse;
 /**
- * Request parameters extracted from URL path
+ * Node in the radix tree for efficient route matching
  */
-interface RequestParams {
-    [key: string]: string;
+interface RouteNode {
+    segment: string;
+    paramName: string | null;
+    isWildcard: boolean;
+    children: RouteNode[];
+    handlers: Partial<Record<HttpMethod, RouteMethodOptions>>;
+    pattern: RegExp | null;
 }
-/**
- * Query parameters from URL
- */
-interface QueryParams {
-    [key: string]: string | string[] | undefined;
+interface RouteEntry {
+    /** The route path pattern */
+    path: string;
+    /** The HTTP method */
+    method: HttpMethod;
+    /** The compiled regex pattern */
+    pattern: RegExp;
+    /** The parameter names in order */
+    paramNames: string[];
+    /** The route handler options */
+    routeOptions: RouteMethodOptions;
 }
-/**
- * Options for streaming responses
- */
-interface StreamOptions {
-    contentType?: string;
-    status?: number;
-    headers?: Record<string, string>;
+interface ErrorHandlerOptions {
+    /** Show detailed errors in response */
+    detailed?: boolean;
+    /** Log errors to console */
+    log?: boolean;
 }
-/**
- * State container for storing request-scoped data
- * Allows for proper typing with generics
- */
-interface State {
-    [key: string]: unknown;
-    /**
-     * Body parsing error information
-     * Set when body parsing fails during request processing
-     */
-    _bodyError?: BodyParseError;
+interface ProcessResponseOptions {
+    /** Status code to use if not specified */
+    defaultStatus?: number;
 }
 /**
- * Services container for storing injectable services/dependencies
- * Allows middleware to contribute services that are accessible throughout the request lifecycle
+ * Standard error response structure
  */
-interface Services {
-    [key: string]: unknown;
+interface StandardErrorResponse {
+    error: string;
+    message: string;
 }
-interface ContextResponse<S extends State = State> {
-    raw: UnifiedResponse;
-    sent: boolean;
-    statusCode: number;
-    status: (code: number) => ContextResponse<S>;
-    header: (name: string, value: string) => ContextResponse<S>;
-    headers: (headers: Record<string, string>) => ContextResponse<S>;
-    type: (contentType: string) => ContextResponse<S>;
-    json: (body: unknown, status?: number) => void;
-    text: (body: string, status?: number) => void;
-    html: (body: string, status?: number) => void;
-    redirect: (url: string, status?: number) => void;
-    stream: (readable: NodeJS.ReadableStream, options?: StreamOptions) => void;
+interface FileCache {
+    routes: Route[];
+    timestamp: number;
+    hash: string;
 }
-interface ContextRequest<TBody = unknown> {
-    raw: UnifiedRequest;
-    method: string;
-    path: string;
-    url: URL | null;
-    query: QueryParams;
-    params: RequestParams;
-    protocol: string;
-    isHttp2: boolean;
-    body?: TBody;
-    /**
-     * Uploaded files from multipart/form-data requests
-     * Available when Content-Type is multipart/form-data
-     */
-    files?: Record<string, UploadedFile | UploadedFile[]>;
-    /**
-     * Complete multipart data (files + fields)
-     * Available when Content-Type is multipart/form-data
-     */
-    multipart?: MultipartData;
-    header: (name: string) => string | undefined;
-    headers: (names?: string[]) => Record<string, string | undefined>;
+interface ReloadMetrics {
+    fileChanges: number;
+    totalReloadTime: number;
+    averageReloadTime: number;
+    slowReloads: Array<{
+        file: string;
+        time: number;
+    }>;
 }
-/**
- * Context object representing a request/response cycle
- * @template S - Type of the state object
- * @template Svc - Type of the services object
- * @template TBody - Type of the request body
- * @template TQuery - Type of the query parameters
- */
-interface Context<S extends State = State, Svc extends Services = Services, TBody = unknown, TQuery = QueryParams> {
-    /**
-     * Request information
-     */
-    request: Omit<ContextRequest, 'body' | 'query'> & {
-        body: TBody;
-        query: TQuery;
-    };
-    /**
-     * Response handling
-     */
-    response: ContextResponse<S>;
-    /**
-     * Request-scoped state for storing data during the request lifecycle
-     */
-    state: S;
-    /**
-     * Services container for accessing injected services/dependencies
-     * Populated by middleware that contribute services
-     */
-    services: Svc;
+interface WatchOptions {
+    debounceMs?: number;
+    /** Directories to ignore */
+    ignore?: string[];
+    /** Callback for new routes */
+    onRouteAdded?: (filePath: string, routes: Route[]) => void;
+    /** Callback for changed routes */
+    onRouteChanged?: (filePath: string, routes: Route[]) => void;
+    /** Callback for removed routes */
+    onRouteRemoved?: (filePath: string, routes: Route[]) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
 }
-interface BodyLimits {
-    /** Maximum JSON body size in bytes (default: 512KB) */
-    json: number;
-    /** Maximum form data size in bytes (default: 1MB) */
-    form: number;
-    /** Maximum text body size in bytes (default: 5MB) */
-    text: number;
-    /** Maximum raw/binary body size in bytes (default: 10MB) */
-    raw: number;
-    /** Multipart/form-data limits */
-    multipart: MultipartLimits;
+interface RouteRegistry {
+    routesByPath: Map<string, Route>;
+    routesByFile: Map<string, Set<string>>;
+    pathToFile: Map<string, string>;
+}
+interface FindRouteFilesOptions {
+    /** Directories to ignore */
+    ignore?: string[] | undefined;
 }
-type MultipartLimits = {
-    maxFileSize?: number;
-    maxTotalSize?: number;
-    maxFiles?: number;
-    maxFieldSize?: number;
-};
 /**
- * Options for creating a context
+ * GET route creator with state and services support
+ * Now returns a higher-order function to handle generics properly
  */
-interface ContextOptions {
-    /**
-     * Whether to parse the request body
-     */
-    parseBody?: boolean;
-    /**
-     * Initial state to include in the context
-     *
-     */
-    initialState?: State;
-    /**
-     * Initial services to include in the context
-     *
-     */
-    initialServices?: Services;
-    /**
-     * Limits for various body types to prevent abuse
-     */
-    bodyLimits: BodyLimits;
-}
-/**
- * Function to get the current context from AsyncLocalStorage
- */
-type GetContextFn = <S extends State = State, Svc extends Services = Services>() => Context<S, Svc> | undefined;
+type CreateGetRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // GET never has body
+    [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    GET: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 /**
- * Factory function for creating a new context
+ * POST route creator with state and services support
  */
-type CreateContextFn = (req: UnifiedRequest, res: UnifiedResponse, options?: ContextOptions) => Promise<Context>;
+type CreatePostRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, B = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        body?: B extends never ? never : B;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    POST: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, B extends never ? never : B extends z.ZodType ? B : never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 /**
- * Type representing unknown function
- *
- * This is a generic function type that can accept any number of arguments
- * and return any type of value. It is used for type inference in various
- * contexts where the specific function signature is not known or not
- * important.
+ * PUT route creator with state and services support
  */
-type UnknownFunction = (...args: unknown[]) => unknown;
-
+type CreatePutRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, B = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        body?: B extends never ? never : B;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    PUT: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, B extends never ? never : B extends z.ZodType ? B : never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 /**
- * Function to pass control to the next middleware
+ * DELETE route creator with state and services support
  */
-type NextFunction = () => Promise<void> | void;
+type CreateDeleteRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // DELETE never has body
+    [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    DELETE: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 /**
- * Middleware function signature
+ * PATCH route creator with state and services support
  */
-type MiddlewareFunction = (ctx: Context, next: NextFunction) => Promise<void> | void;
+type CreatePatchRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, B = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        body?: B extends never ? never : B;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    PATCH: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, B extends never ? never : B extends z.ZodType ? B : never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 /**
- * Named middleware options
+ * HEAD route creator with state and services support
  */
-interface MiddlewareOptions {
-    /** Name of the middleware for debugging and logging */
-    name?: string;
-    /** The middleware handler function */
-    handler: MiddlewareFunction;
-    /** Skip function to conditionally bypass middleware */
-    skip?: ((ctx: Context<any, any>) => boolean) | undefined;
-    /** Enable debugging for this middleware */
-    debug?: boolean;
-}
+type CreateHeadRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // HEAD never has body
+    [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    HEAD: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 /**
- * Middleware type with generic parameters for type-safe state and service contributions
- * @template TState - Type of state this middleware contributes to the context
- * @template TServices - Type of services this middleware contributes to the context
+ * OPTIONS route creator with state and services support
  */
-interface Middleware<TState = {}, TServices = {}> {
-    name: string;
-    execute: MiddlewareFunction;
-    skip?: ((ctx: Context) => boolean) | undefined;
-    debug?: boolean | undefined;
-    _services?: TServices;
-}
+type CreateOptionsRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        response?: R extends never ? never : R;
+    };
+    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // OPTIONS never has body
+    [
+        R
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    OPTIONS: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
+    path: string;
+};
 
 /**
- * Helper type to extract TypeScript type from Zod schema
+ * Compose multiple middleware functions into a single middleware function
  */
-type Infer<T> = T extends z.ZodType ? z.output<T> : unknown;
+declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
+
 /**
- * HTTP methods supported by the router
+ * CORS Types for BlaizeJS Framework
+ *
+ * Comprehensive type definitions for W3C-compliant CORS middleware
+ * with support for string, regex, and async function origin validation.
+ *
+ * @module @blaizejs/types/cors
  */
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
 /**
- * Schema for route validation with generic type parameters
+ * Origin configuration type supporting multiple validation methods
+ *
+ * @example
+ * ```typescript
+ * // String origin (exact match)
+ * const origin: CorsOrigin = 'https://example.com';
+ *
+ * // RegExp pattern
+ * const origin: CorsOrigin = /^https:\/\/.*\.example\.com$/;
+ *
+ * // Dynamic validation function
+ * const origin: CorsOrigin = async (origin, ctx) => {
+ *   return await checkOriginAllowed(origin, ctx?.state.user);
+ * };
+ *
+ * // Array of mixed types
+ * const origin: CorsOrigin = [
+ *   'https://localhost:3000',
+ *   /^https:\/\/.*\.example\.com$/,
+ *   (origin) => origin.endsWith('.trusted.com')
+ * ];
+ * ```
  */
-interface RouteSchema<P extends z.ZodType = z.ZodType<any>, // URL parameters schema
-Q extends z.ZodType = z.ZodType<any>, // Query parameters schema
-B extends z.ZodType = z.ZodType<any>, // Body schema
-R extends z.ZodType = z.ZodType<any>, // Response schema
-ED extends z.ZodType = z.ZodType<any>> {
-    /** Parameter schema for validation */
-    params?: P;
-    /** Query schema for validation */
-    query?: Q;
-    /** Body schema for validation */
-    body?: B;
-    /** Response schema for validation */
-    response?: R;
-    /** Error Response Details schema for validation */
-    errorResponseDetails?: ED;
-}
+type CorsOrigin = string | RegExp | ((origin: string, ctx?: Context<any, any>) => boolean | Promise<boolean>) | Array<string | RegExp | ((origin: string, ctx?: Context<any, any>) => boolean | Promise<boolean>)>;
 /**
- * Route handler function with strongly typed params and response
+ * HTTP methods that can be allowed in CORS
+ * Based on W3C CORS specification
  */
-type RouteHandler<TParams = Record<string, string>, TQuery = Record<string, string | string[] | undefined>, TBody = unknown, TResponse = unknown, TState extends State = State, // NEW in v0.4.0
-TServices extends Services = Services> = (ctx: Context<TState, TServices, TBody, TQuery>, params: TParams) => Promise<TResponse> | TResponse;
+type CorsHttpMethod = HttpMethod | 'CONNECT' | 'TRACE';
 /**
- * Options for a route method with schema-based type inference
+ * Main CORS configuration options
+ *
+ * @example
+ * ```typescript
+ * const corsOptions: CorsOptions = {
+ *   origin: 'https://example.com',
+ *   methods: ['GET', 'POST'],
+ *   credentials: true,
+ *   maxAge: 86400
+ * };
+ * ```
  */
-interface RouteMethodOptions<P extends z.ZodType = z.ZodType<any>, Q extends z.ZodType = z.ZodType<any>, B extends z.ZodType = z.ZodType<any>, R extends z.ZodType = z.ZodType<any>, ED extends z.ZodType = z.ZodType<any>> {
-    /** Schema for request/response validation */
-    schema?: RouteSchema<P, Q, B, R, ED>;
-    /** Handler function for the route */
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, R extends z.ZodType ? Infer<R> : unknown>;
-    /** Middleware to apply to this route */
-    middleware?: Middleware[];
-    /** Route-specific options */
-    options?: Record<string, unknown>;
+interface CorsOptions {
+    /**
+     * Configures the Access-Control-Allow-Origin header
+     *
+     * Possible values:
+     * - `true`: Allow all origins (sets to '*' unless credentials is true, then reflects origin)
+     * - `false`: Disable CORS (no headers set)
+     * - `string`: Specific origin to allow
+     * - `RegExp`: Pattern to match origins
+     * - `function`: Custom validation logic
+     * - `array`: Multiple origin configurations
+     *
+     * @default false
+     */
+    origin?: boolean | CorsOrigin;
+    /**
+     * Configures the Access-Control-Allow-Methods header
+     *
+     * @default ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+     * @example ['GET', 'POST']
+     */
+    methods?: CorsHttpMethod[] | string;
+    /**
+     * Configures the Access-Control-Allow-Headers header
+     *
+     * Pass an array of allowed headers or a comma-delimited string.
+     *
+     * @default Request's Access-Control-Request-Headers header value
+     * @example ['Content-Type', 'Authorization']
+     */
+    allowedHeaders?: string[] | string;
+    /**
+     * Configures the Access-Control-Expose-Headers header
+     *
+     * Headers that the browser is allowed to access.
+     *
+     * @default []
+     * @example ['Content-Range', 'X-Content-Range']
+     */
+    exposedHeaders?: string[] | string;
+    /**
+     * Configures the Access-Control-Allow-Credentials header
+     *
+     * Set to true to allow credentials (cookies, authorization headers, TLS client certificates).
+     * Note: Cannot be used with origin: '*' for security reasons.
+     *
+     * @default false
+     */
+    credentials?: boolean;
+    /**
+     * Configures the Access-Control-Max-Age header in seconds
+     *
+     * Indicates how long browsers can cache preflight response.
+     * Set to -1 to disable caching.
+     *
+     * @default undefined (browser decides)
+     * @example 86400 // 24 hours
+     */
+    maxAge?: number;
+    /**
+     * Whether to pass the CORS preflight response to the next handler
+     *
+     * When false, the preflight response is sent immediately.
+     * When true, control passes to the next middleware/handler.
+     *
+     * @default false
+     */
+    preflightContinue?: boolean;
+    /**
+     * HTTP status code for successful OPTIONS requests
+     *
+     * Some legacy browsers require 200, while 204 is more correct.
+     *
+     * @default 204
+     */
+    optionsSuccessStatus?: number;
 }
 /**
- * Route definition mapping HTTP methods to handlers
+ * Internal CORS validation result
+ * Used by middleware implementation
  */
-interface RouteDefinition {
-    GET?: RouteMethodOptions<any, any, never, any, any>;
-    POST?: RouteMethodOptions<any, any, any, any, any>;
-    PUT?: RouteMethodOptions<any, any, any, any, any>;
-    DELETE?: RouteMethodOptions<any, any, never, any, any>;
-    PATCH?: RouteMethodOptions<any, any, any, any, any>;
-    HEAD?: RouteMethodOptions<any, any, never, any, any>;
-    OPTIONS?: RouteMethodOptions<any, any, never, any, any>;
+interface CorsValidationResult {
+    /**
+     * Whether the origin is allowed
+     */
+    allowed: boolean;
+    /**
+     * The origin value to set in the header
+     * Can be '*', specific origin, or 'null'
+     */
+    origin?: string;
+    /**
+     * Whether to add Vary: Origin header
+     */
+    vary?: boolean;
 }
 /**
- * Route object with path
+ * CORS preflight request information
+ * Extracted from OPTIONS request headers
  */
-interface Route extends RouteDefinition {
-    /** Path of the route */
-    path: string;
+interface CorsPreflightInfo {
+    /**
+     * The origin making the request
+     */
+    origin?: string;
+    /**
+     * The method that will be used in the actual request
+     * From Access-Control-Request-Method header
+     */
+    requestedMethod?: string;
+    /**
+     * The headers that will be sent in the actual request
+     * From Access-Control-Request-Headers header
+     */
+    requestedHeaders?: string[];
 }
 /**
- * Options for route creation
+ * Cache entry for origin validation results
+ * Used for performance optimization
  */
-interface RouteOptions {
-    /** Base path for the route */
-    basePath?: string;
+interface CorsOriginCacheEntry {
+    /**
+     * Whether the origin is allowed
+     */
+    allowed: boolean;
+    /**
+     * When this cache entry expires (timestamp)
+     */
+    expiresAt: number;
+    /**
+     * Optional user identifier for cache key
+     */
+    userId?: string;
 }
 /**
- * Result type for handling success and error responses
+ * Configuration for CORS origin validation cache
  */
-type Result<T, E = {
-    error: string;
-    message: string;
-    details?: unknown;
-}> = {
-    success: true;
-    data: T;
-    status?: number;
-} | {
-    success: false;
-    error: E;
-    status?: number;
-};
+interface CorsOriginCacheConfig {
+    /**
+     * Time-to-live for cache entries in milliseconds
+     * @default 60000 (1 minute)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of entries in the cache
+     * @default 1000
+     */
+    maxSize?: number;
+    /**
+     * Whether to include user ID in cache key
+     * @default true
+     */
+    includeUserId?: boolean;
+}
 /**
- * Router options
+ * Statistics for CORS middleware performance monitoring
  */
-interface RouterOptions {
-    /** Directory containing route files */
-    routesDir: string;
-    /** Base path for all routes */
-    basePath?: string;
-    /** Watch for file changes in development */
-    watchMode?: boolean;
+interface CorsStats {
+    /**
+     * Total number of CORS requests processed
+     */
+    totalRequests: number;
+    /**
+     * Number of preflight requests handled
+     */
+    preflightRequests: number;
+    /**
+     * Number of allowed origins
+     */
+    allowedOrigins: number;
+    /**
+     * Number of denied origins
+     */
+    deniedOrigins: number;
+    /**
+     * Cache hit rate for origin validation
+     */
+    cacheHitRate: number;
+    /**
+     * Average origin validation time in milliseconds
+     */
+    avgValidationTime: number;
 }
 /**
- * Router interface
+ * Cache entry type
  */
-interface Router {
-    /** Handle an incoming request */
-    handleRequest: (ctx: Context) => Promise<void>;
-    /** Get all registered routes */
-    getRoutes: () => Route[];
-    /** Add a route programmatically */
-    addRoute: (route: Route) => void;
-    /** Add multiple routes programmatically with batch processing */
-    addRoutes: (routes: Route[]) => {
-        added: Route[];
-        removed: string[];
-        changed: Route[];
-    };
-    /** Add a route directory for plugins */
-    addRouteDirectory(directory: string, options?: {
-        prefix?: string;
-    }): Promise<void>;
-    /** Get route conflicts */
-    getRouteConflicts(): Array<{
-        path: string;
-        sources: string[];
-    }>;
-    /** Close watchers and cleanup resources */
-    close?: () => Promise<void>;
+interface CacheEntry {
+    allowed: boolean;
+    expiresAt: number;
+    lastAccessed: number;
 }
 /**
- * Route match result
+ * Cache configuration
  */
-interface RouteMatch {
-    /** The matched route handler (null if method not allowed) */
-    route: RouteMethodOptions | null;
-    /** Extracted route parameters */
-    params: Record<string, string>;
-    /** Flag indicating if the path exists but method isn't allowed */
-    methodNotAllowed?: boolean;
-    /** List of allowed methods for this path (when method not allowed) */
-    allowedMethods?: HttpMethod[];
+interface CacheConfig {
+    ttl: number;
+    maxSize: number;
 }
+
 /**
- * Route matcher interface
- */
-interface Matcher {
-    /** Add a route to the matcher */
-    add: (path: string, method: HttpMethod, route: RouteMethodOptions) => void;
-    /** Match a URL path to a route */
-    match: (path: string, method: HttpMethod) => RouteMatch | null;
-    /** Get all registered routes */
-    getRoutes: () => {
-        path: string;
-        method: HttpMethod;
-    }[];
-    /** Find routes matching a specific path */
-    findRoutes: (path: string) => {
-        path: string;
-        method: HttpMethod;
-        params: Record<string, string>;
-    }[];
-    /** Remove a route from the matcher (optional for compatibility) */
-    remove: (path: string) => void;
-    /** Clear all routes from the matcher (optional for compatibility) */
-    clear: () => void;
-}
-interface ParsedRoute {
-    filePath: string;
-    routePath: string;
-    params: string[];
-}
-/**
- * Node in the radix tree for efficient route matching
- */
-interface RouteNode {
-    segment: string;
-    paramName: string | null;
-    isWildcard: boolean;
-    children: RouteNode[];
-    handlers: Partial<Record<HttpMethod, RouteMethodOptions>>;
-    pattern: RegExp | null;
-}
-interface RouteEntry {
-    /** The route path pattern */
-    path: string;
-    /** The HTTP method */
-    method: HttpMethod;
-    /** The compiled regex pattern */
-    pattern: RegExp;
-    /** The parameter names in order */
-    paramNames: string[];
-    /** The route handler options */
-    routeOptions: RouteMethodOptions;
-}
-interface ErrorHandlerOptions {
-    /** Show detailed errors in response */
-    detailed?: boolean;
-    /** Log errors to console */
-    log?: boolean;
-}
-interface ProcessResponseOptions {
-    /** Status code to use if not specified */
-    defaultStatus?: number;
-}
-/**
- * Standard error response structure
+ * Create CORS middleware with the specified options
+ *
+ * @param userOptions - CORS configuration options or boolean
+ * @returns Middleware function that handles CORS
+ *
+ * @example
+ * ```typescript
+ * import { cors } from '@blaize-core/middleware/cors';
+ *
+ * // Development mode - allow all origins
+ * server.use(cors(true));
+ *
+ * // Production - specific origin
+ * server.use(cors({
+ *   origin: 'https://app.example.com',
+ *   credentials: true,
+ *   maxAge: 86400
+ * }));
+ *
+ * // Multiple origins with regex
+ * server.use(cors({
+ *   origin: [
+ *     'https://app.example.com',
+ *     /^https:\/\/.*\.example\.com$/
+ *   ]
+ * }));
+ *
+ * // Dynamic origin validation
+ * server.use(cors({
+ *   origin: async (origin, ctx) => {
+ *     return await checkOriginAllowed(origin, ctx.state.user);
+ *   }
+ * }));
+ * ```
  */
-interface StandardErrorResponse {
-    error: string;
-    message: string;
-}
-interface FileCache {
-    routes: Route[];
-    timestamp: number;
-    hash: string;
-}
-interface ReloadMetrics {
-    fileChanges: number;
-    totalReloadTime: number;
-    averageReloadTime: number;
-    slowReloads: Array<{
-        file: string;
-        time: number;
-    }>;
-}
-interface WatchOptions {
-    debounceMs?: number;
-    /** Directories to ignore */
-    ignore?: string[];
-    /** Callback for new routes */
-    onRouteAdded?: (filePath: string, routes: Route[]) => void;
-    /** Callback for changed routes */
-    onRouteChanged?: (filePath: string, routes: Route[]) => void;
-    /** Callback for removed routes */
-    onRouteRemoved?: (filePath: string, routes: Route[]) => void;
-    /** Callback for errors */
-    onError?: (error: Error) => void;
-}
-interface RouteRegistry {
-    routesByPath: Map<string, Route>;
-    routesByFile: Map<string, Set<string>>;
-    pathToFile: Map<string, string>;
-}
-interface FindRouteFilesOptions {
-    /** Directories to ignore */
-    ignore?: string[] | undefined;
-}
+declare function cors(userOptions?: CorsOptions | boolean): Middleware;
+
 /**
- * GET route creator with state and services support
- * Now returns a higher-order function to handle generics properly
+ * Create a middleware
  */
-type CreateGetRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        response?: R extends never ? never : R;
-    };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // GET never has body
-    [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    GET: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
+declare function create$2<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
 /**
- * POST route creator with state and services support
+ * Create a middleware that only contributes state (no services)
+ * Convenience helper for state-only middleware
+ *
+ * @template T - Type of state to contribute
+ * @param handler - Middleware function that adds state
+ * @returns Middleware that contributes state only
+ *
  */
-type CreatePostRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, B = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        body?: B extends never ? never : B;
-        response?: R extends never ? never : R;
-    };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    POST: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, B extends never ? never : B extends z.ZodType ? B : never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
+declare function stateMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<T, {}>;
 /**
- * PUT route creator with state and services support
+ * Create a middleware that only contributes services (no state)
+ * Convenience helper for service-only middleware
+ *
+ * @template T - Type of services to contribute
+ * @param handler - Middleware function that adds services
+ * @returns Middleware that contributes services only
+ *
  */
-type CreatePutRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, B = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        body?: B extends never ? never : B;
-        response?: R extends never ? never : R;
-    };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    PUT: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, B extends never ? never : B extends z.ZodType ? B : never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
+declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
+
 /**
- * DELETE route creator with state and services support
+ * Error type definitions and interfaces for the BlaizeJS framework
+ *
+ * This module contains all the type definitions used for error handling
+ * across the BlaizeJS framework, including server-side errors, client-side
+ * errors, and HTTP response formats.
  */
-type CreateDeleteRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        response?: R extends never ? never : R;
-    };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // DELETE never has body
-    [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    DELETE: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
 /**
- * PATCH route creator with state and services support
+ * Structure of error responses sent over HTTP
+ *
+ * This interface defines the JSON format used for all error responses
+ * from BlaizeJS servers. It matches the structure returned by BlaizeError.toJSON()
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VALIDATION_ERROR",
+ *   "title": "Request validation failed",
+ *   "status": 400,
+ *   "correlationId": "req_abc123",
+ *   "timestamp": "2024-01-15T10:30:00.000Z",
+ *   "details": {
+ *     "fields": ["email", "password"]
+ *   }
+ * }
+ * ```
  */
-type CreatePatchRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, B = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        body?: B extends never ? never : B;
-        response?: R extends never ? never : R;
-    };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, B extends z.ZodType ? Infer<B> : unknown, [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    PATCH: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, B extends never ? never : B extends z.ZodType ? B : never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
+interface BlaizeErrorResponse {
+    /** Error type from the ErrorType enum */
+    type: ErrorType;
+    /** Human-readable error message */
+    title: string;
+    /** HTTP status code */
+    status: number;
+    /** Correlation ID for request tracing */
+    correlationId: string;
+    /** ISO timestamp when error occurred */
+    timestamp: string;
+    /** Optional error-specific details */
+    details?: unknown;
+}
 /**
- * HEAD route creator with state and services support
+ * Context information for network-related errors
+ *
+ * Used by client-side error classes to provide additional context
+ * about network failures, timeouts, and connection issues.
  */
-type CreateHeadRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        response?: R extends never ? never : R;
+interface NetworkErrorContext {
+    /** The URL that failed */
+    url: string;
+    /** HTTP method being attempted */
+    method: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Timeout value if applicable */
+    timeout?: number;
+    /** The original error that caused the network failure */
+    originalError: Error;
+    /** Additional network-specific details */
+    networkDetails?: {
+        /** Whether this was a connection timeout */
+        isTimeout?: boolean;
+        /** Whether this was a DNS resolution failure */
+        isDnsFailure?: boolean;
+        /** Whether this was a connection refused error */
+        isConnectionRefused?: boolean;
+        /** HTTP status code if received before failure */
+        statusCode?: number;
     };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // HEAD never has body
-    [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    HEAD: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
+}
 /**
- * OPTIONS route creator with state and services support
+ * Context information for request timeout errors
+ *
+ * Specialized context for timeout-specific errors with timing information.
  */
-type CreateOptionsRoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, R = never>(config: {
-    schema?: {
-        params?: P extends never ? never : P;
-        query?: Q extends never ? never : Q;
-        response?: R extends never ? never : R;
-    };
-    handler: RouteHandler<P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, never, // OPTIONS never has body
-    [
-        R
-    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
-    middleware?: Middleware[];
-    options?: Record<string, unknown>;
-}) => {
-    OPTIONS: RouteMethodOptions<P extends never ? never : P extends z.ZodType ? P : never, Q extends never ? never : Q extends z.ZodType ? Q : never, never, R extends never ? never : R extends z.ZodType ? R : never>;
-    path: string;
-};
-
+interface TimeoutErrorContext {
+    /** The URL that timed out */
+    url: string;
+    /** HTTP method being attempted */
+    method: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Configured timeout value in milliseconds */
+    timeoutMs: number;
+    /** Actual duration before timeout in milliseconds */
+    elapsedMs: number;
+    /** Type of timeout (request, connection, etc.) */
+    timeoutType: 'request' | 'connection' | 'response' | 'idle';
+}
 /**
- * Compose multiple middleware functions into a single middleware function
+ * Context information for response parsing errors
+ *
+ * Used when the client receives a response but cannot parse it properly.
  */
-declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
-
+interface ParseErrorContext {
+    /** The URL that returned unparseable content */
+    url: string;
+    /** HTTP method used */
+    method: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** HTTP status code received */
+    statusCode: number;
+    /** Content-Type header if available */
+    contentType?: string;
+    /** Expected response format */
+    expectedFormat: 'json' | 'text' | 'binary';
+    /** Sample of the actual response content (truncated for safety) */
+    responseSample?: string;
+    /** The original parsing error */
+    originalError: Error;
+}
 /**
- * CORS Types for BlaizeJS Framework
- *
- * Comprehensive type definitions for W3C-compliant CORS middleware
- * with support for string, regex, and async function origin validation.
+ * Validation error field details
  *
- * @module @blaizejs/types/cors
+ * Structure for field-level validation errors with multiple error messages
+ * per field.
  */
-
+interface ValidationFieldError {
+    /** Field name or path (e.g., "email", "user.profile.name") */
+    field: string;
+    /** Array of error messages for this field */
+    messages: string[];
+    /** The invalid value that caused the error */
+    rejectedValue?: unknown;
+    /** Expected type or format */
+    expectedType?: string;
+}
+interface ServiceNotAvailableDetails {
+    /** Service that's unavailable */
+    service?: string;
+    /** Seconds to wait before retry */
+    retryAfter?: number;
+    /** Why service is unavailable */
+    reason?: 'maintenance' | 'overload' | 'circuit_breaker' | 'dependency_down';
+    /** Additional context */
+    [key: string]: unknown;
+}
 /**
- * Origin configuration type supporting multiple validation methods
- *
- * @example
- * ```typescript
- * // String origin (exact match)
- * const origin: CorsOrigin = 'https://example.com';
+ * Validation error details structure
  *
- * // RegExp pattern
- * const origin: CorsOrigin = /^https:\/\/.*\.example\.com$/;
+ * Used by ValidationError to provide structured information about
+ * what fields failed validation and why.
+ */
+interface ValidationErrorDetails {
+    /** Array of field-level errors */
+    fields: ValidationFieldError[];
+    /** Total number of validation errors */
+    errorCount: number;
+    /** The section that failed validation */
+    section: 'params' | 'query' | 'body' | 'response';
+    /** Schema name if available */
+    schemaName?: string;
+}
+/**
+ * All available error types in the BlaizeJS framework
  *
- * // Dynamic validation function
- * const origin: CorsOrigin = async (origin, ctx) => {
- *   return await checkOriginAllowed(origin, ctx?.state.user);
- * };
+ * This enum provides both compile-time type safety and runtime values
+ * for error type identification across server and client packages.
  *
- * // Array of mixed types
- * const origin: CorsOrigin = [
- *   'https://localhost:3000',
- *   /^https:\/\/.*\.example\.com$/,
- *   (origin) => origin.endsWith('.trusted.com')
- * ];
+ * @example Type-safe error handling:
+ * ```typescript
+ * function handleError(errorType: ErrorType) {
+ *   switch (errorType) {
+ *     case ErrorType.VALIDATION_ERROR:
+ *       // Handle validation error
+ *       break;
+ *     case ErrorType.NOT_FOUND:
+ *       // Handle not found error
+ *       break;
+ *     // TypeScript ensures all cases are covered
+ *   }
+ * }
  * ```
  */
-type CorsOrigin = string | RegExp | ((origin: string, ctx?: Context<any, any>) => boolean | Promise<boolean>) | Array<string | RegExp | ((origin: string, ctx?: Context<any, any>) => boolean | Promise<boolean>)>;
+declare enum ErrorType {
+    /** Request validation failed (400) */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Resource not found (404) */
+    NOT_FOUND = "NOT_FOUND",
+    /** Authentication required (401) */
+    UNAUTHORIZED = "UNAUTHORIZED",
+    /** Access forbidden (403) */
+    FORBIDDEN = "FORBIDDEN",
+    /** SSE Not Acceptable (406) */
+    SSE_NOT_ACCEPTABLE = "SSE_NOT_ACCEPTABLE",
+    /** Resource conflict (409) */
+    CONFLICT = "CONFLICT",
+    /** Rate limit exceeded (429) */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Internal server error (500) */
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
+    /** File/Request Too Large (413) */
+    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
+    /** Wrong Content Type (415) */
+    UNSUPPORTED_MEDIA_TYPE = "UNSUPPORTED_MEDIA_TYPE",
+    /** Upload Timeout (408) */
+    UPLOAD_TIMEOUT = "UPLOAD_TIMEOUT",
+    /** Valid Format Invalid Semantics (422) */
+    UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
+    /** Network connectivity failure (0) */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Request or response timeout (0) */
+    TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    /** Response parsing failure (0) */
+    PARSE_ERROR = "PARSE_ERROR",
+    /** Generic HTTP error (varies) */
+    HTTP_ERROR = "HTTP_ERROR",
+    /** SSE connection failed (502) */
+    SSE_CONNECTION_ERROR = "SSE_CONNECTION_ERROR",
+    /** SSE buffer overflow (503) */
+    SSE_BUFFER_OVERFLOW = "SSE_BUFFER_OVERFLOW",
+    /** SSE stream closed (410) */
+    SSE_STREAM_CLOSED = "SSE_STREAM_CLOSED",
+    /** Service temporarily unavailable (503) */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+}
 /**
- * HTTP methods that can be allowed in CORS
- * Based on W3C CORS specification
+ * Error severity levels for logging and monitoring
+ *
+ * Provides a way to categorize errors by their impact and urgency.
  */
-type CorsHttpMethod = HttpMethod | 'CONNECT' | 'TRACE';
+declare enum ErrorSeverity {
+    /** Low impact, often user errors */
+    LOW = "low",
+    /** Medium impact, application errors */
+    MEDIUM = "medium",
+    /** High impact, system errors */
+    HIGH = "high",
+    /** Critical impact, service disruption */
+    CRITICAL = "critical"
+}
 /**
- * Main CORS configuration options
+ * Abstract base class for all BlaizeJS errors
+ *
+ * This class provides the foundation for all error types in the BlaizeJS framework.
+ * It extends JavaScript's built-in Error class and adds framework-specific properties
+ * for consistent error handling across server and client.
  *
  * @example
  * ```typescript
- * const corsOptions: CorsOptions = {
- *   origin: 'https://example.com',
- *   methods: ['GET', 'POST'],
- *   credentials: true,
- *   maxAge: 86400
- * };
+ * import { ErrorType } from './types';
+ *
+ * class NotFoundError extends BlaizeError<{ resourceId: string }> {
+ *   constructor(message = 'Resource not found', details?: { resourceId: string }) {
+ *     super(ErrorType.NOT_FOUND, message, 404, getCurrentCorrelationId(), details);
+ *   }
+ * }
  * ```
+ *
+ * @template TDetails - Type for error-specific details object
  */
-interface CorsOptions {
+declare abstract class BlaizeError<TDetails = unknown> extends Error {
     /**
-     * Configures the Access-Control-Allow-Origin header
-     *
-     * Possible values:
-     * - `true`: Allow all origins (sets to '*' unless credentials is true, then reflects origin)
-     * - `false`: Disable CORS (no headers set)
-     * - `string`: Specific origin to allow
-     * - `RegExp`: Pattern to match origins
-     * - `function`: Custom validation logic
-     * - `array`: Multiple origin configurations
-     *
-     * @default false
+     * Error type identifier from the ErrorType enum
+     * Used for programmatic error handling and client-side error routing
      */
-    origin?: boolean | CorsOrigin;
+    readonly type: ErrorType;
     /**
-     * Configures the Access-Control-Allow-Methods header
-     *
-     * @default ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
-     * @example ['GET', 'POST']
+     * Human-readable error title/message
+     * Should be descriptive enough for debugging but safe for end users
      */
-    methods?: CorsHttpMethod[] | string;
+    readonly title: string;
     /**
-     * Configures the Access-Control-Allow-Headers header
-     *
-     * Pass an array of allowed headers or a comma-delimited string.
-     *
-     * @default Request's Access-Control-Request-Headers header value
-     * @example ['Content-Type', 'Authorization']
+     * HTTP status code associated with this error
+     * Used by the error boundary to set appropriate response status
      */
-    allowedHeaders?: string[] | string;
+    readonly status: number;
     /**
-     * Configures the Access-Control-Expose-Headers header
-     *
-     * Headers that the browser is allowed to access.
-     *
-     * @default []
-     * @example ['Content-Range', 'X-Content-Range']
+     * Correlation ID for request tracing
+     * Links this error to the specific request that generated it
      */
-    exposedHeaders?: string[] | string;
+    readonly correlationId: string;
     /**
-     * Configures the Access-Control-Allow-Credentials header
-     *
-     * Set to true to allow credentials (cookies, authorization headers, TLS client certificates).
-     * Note: Cannot be used with origin: '*' for security reasons.
-     *
-     * @default false
+     * Timestamp when the error occurred
+     * Useful for debugging and log correlation
      */
-    credentials?: boolean;
+    readonly timestamp: Date;
     /**
-     * Configures the Access-Control-Max-Age header in seconds
-     *
-     * Indicates how long browsers can cache preflight response.
-     * Set to -1 to disable caching.
-     *
-     * @default undefined (browser decides)
-     * @example 86400 // 24 hours
+     * Additional error-specific details
+     * Type-safe error context that varies by error type
      */
-    maxAge?: number;
+    readonly details?: TDetails | undefined;
     /**
-     * Whether to pass the CORS preflight response to the next handler
-     *
-     * When false, the preflight response is sent immediately.
-     * When true, control passes to the next middleware/handler.
+     * Creates a new BlaizeError instance
      *
-     * @default false
+     * @param type - Error type from the ErrorType enum
+     * @param title - Human-readable error message
+     * @param status - HTTP status code
+     * @param correlationId - Request correlation ID for tracing
+     * @param details - Optional error-specific details
      */
-    preflightContinue?: boolean;
+    protected constructor(type: ErrorType, title: string, status: number, correlationId: string, details?: TDetails | undefined);
     /**
-     * HTTP status code for successful OPTIONS requests
-     *
-     * Some legacy browsers require 200, while 204 is more correct.
+     * Serializes the error to a plain object suitable for HTTP responses
      *
-     * @default 204
+     * @returns Object representation of the error
      */
-    optionsSuccessStatus?: number;
+    toJSON(): {
+        type: ErrorType;
+        title: string;
+        status: number;
+        correlationId: string;
+        timestamp: string;
+    } | {
+        details: TDetails & ({} | null);
+        type: ErrorType;
+        title: string;
+        status: number;
+        correlationId: string;
+        timestamp: string;
+    };
+    /**
+     * Returns a string representation of the error
+     * Includes correlation ID for easier debugging
+     */
+    toString(): string;
 }
 /**
- * Internal CORS validation result
- * Used by middleware implementation
+ * Interface for payload too large error details
  */
-interface CorsValidationResult {
-    /**
-     * Whether the origin is allowed
-     */
-    allowed: boolean;
-    /**
-     * The origin value to set in the header
-     * Can be '*', specific origin, or 'null'
-     */
-    origin?: string;
-    /**
-     * Whether to add Vary: Origin header
-     */
-    vary?: boolean;
+interface PayloadTooLargeErrorDetails {
+    fileCount?: number;
+    maxFiles?: number;
+    filename?: string;
+    field?: string;
+    contentType?: string;
+    currentSize?: number;
+    maxSize?: number;
 }
 /**
- * CORS preflight request information
- * Extracted from OPTIONS request headers
+ * Interface for unsupported media type error details
  */
-interface CorsPreflightInfo {
-    /**
-     * The origin making the request
-     */
-    origin?: string;
-    /**
-     * The method that will be used in the actual request
-     * From Access-Control-Request-Method header
-     */
-    requestedMethod?: string;
-    /**
-     * The headers that will be sent in the actual request
-     * From Access-Control-Request-Headers header
-     */
-    requestedHeaders?: string[];
+interface UnsupportedMediaTypeErrorDetails {
+    receivedMimeType?: string;
+    allowedMimeTypes?: string[];
+    filename?: string;
+}
+/**
+ * Interface for authentication error details
+ */
+interface UnauthorizedErrorDetails {
+    /** Reason for authentication failure */
+    reason?: 'missing_token' | 'invalid_token' | 'expired_token' | 'malformed_token' | 'insufficient_scope' | string;
+    /** Authentication scheme (Bearer, Basic, etc.) */
+    authScheme?: string;
+    /** Authentication realm */
+    realm?: string;
+    /** Detailed error description */
+    error_description?: string;
+    /** Required scopes or permissions */
+    requiredScopes?: string[];
+    /** Login URL for interactive authentication */
+    loginUrl?: string;
+    /** Additional context */
+    [key: string]: unknown;
+}
+/**
+ * Interface for authorization/permission error details
+ */
+interface ForbiddenErrorDetails {
+    /** Required permission or role */
+    requiredPermission?: string;
+    /** User's current permissions */
+    userPermissions?: string[];
+    /** Resource being accessed */
+    resource?: string;
+    /** Action being attempted */
+    action?: string;
+    /** Reason for access denial */
+    reason?: 'insufficient_permissions' | 'account_suspended' | 'resource_locked' | 'origin_not_allowed' | string;
+    /** Additional context */
+    [key: string]: unknown;
+}
+/**
+ * Interface for resource conflict error details
+ */
+interface ConflictErrorDetails {
+    /** Type of conflict */
+    conflictType?: 'duplicate_key' | 'version_mismatch' | 'concurrent_modification' | 'business_rule' | string;
+    /** Field that caused the conflict */
+    field?: string;
+    /** Existing value that conflicts */
+    existingValue?: unknown;
+    /** Provided value that conflicts */
+    providedValue?: unknown;
+    /** Resource that has the conflicting value */
+    conflictingResource?: string;
+    /** Current version/etag of the resource */
+    currentVersion?: string;
+    /** Expected version/etag */
+    expectedVersion?: string;
+    /** Suggested resolution */
+    resolution?: string;
+    /** Additional context */
+    [key: string]: unknown;
+}
+/**
+ * Interface for rate limiting error details
+ */
+interface RateLimitErrorDetails {
+    /** Maximum requests allowed in the time window */
+    limit?: number;
+    /** Remaining requests in current window */
+    remaining?: number;
+    /** When the rate limit resets */
+    resetTime?: Date;
+    /** Seconds until the rate limit resets */
+    retryAfter?: number;
+    /** Time window for the rate limit */
+    window?: string;
+    /** Identifier used for rate limiting (IP, user ID, etc.) */
+    identifier?: string;
+    /** Type of rate limit hit */
+    limitType?: 'global' | 'per_user' | 'per_ip' | 'per_endpoint' | string;
+    /** Additional context */
+    [key: string]: unknown;
+}
+/**
+ * Interface for internal server error details
+ */
+interface InternalServerErrorDetails {
+    /** Original error message (for debugging) */
+    originalError?: string;
+    /** Stack trace (for debugging) */
+    stackTrace?: string;
+    /** Component where the error occurred */
+    component?: string;
+    /** Operation being performed */
+    operation?: string;
+    /** Internal error code */
+    internalErrorCode?: string;
+    /** When the error occurred */
+    timestamp?: Date;
+    /** Whether this error should be retryable */
+    retryable?: boolean;
+    /** Additional debugging context */
+    [key: string]: unknown;
 }
 /**
- * Cache entry for origin validation results
- * Used for performance optimization
+ * Interface for NotFound error details
+ * Provides context about the missing resource
  */
-interface CorsOriginCacheEntry {
-    /**
-     * Whether the origin is allowed
-     */
-    allowed: boolean;
-    /**
-     * When this cache entry expires (timestamp)
-     */
-    expiresAt: number;
-    /**
-     * Optional user identifier for cache key
-     */
-    userId?: string;
+interface NotFoundErrorDetails {
+    /** Type of resource that was not found */
+    resourceType?: string;
+    /** ID or identifier of the resource */
+    resourceId?: string;
+    /** Collection or table where the resource was searched */
+    collection?: string;
+    /** Search criteria that was used */
+    query?: Record<string, unknown>;
+    /** Search criteria that was used (for backward compatibility) */
+    searchCriteria?: Record<string, unknown>;
+    /** The path that was attempted */
+    path?: string;
+    /** HTTP method used (for API endpoints) */
+    method?: string;
+    /** The path that was attempted (for backward compatibility) */
+    attemptedPath?: string;
+    /** Parent resource information for nested resources */
+    parentResource?: {
+        type: string;
+        id: string;
+    };
+    /** Helpful suggestion for the user */
+    suggestion?: string;
+    /** Additional context */
+    [key: string]: unknown;
 }
 /**
- * Configuration for CORS origin validation cache
+ * Context information for error transformation
  */
-interface CorsOriginCacheConfig {
-    /**
-     * Time-to-live for cache entries in milliseconds
-     * @default 60000 (1 minute)
-     */
-    ttl?: number;
-    /**
-     * Maximum number of entries in the cache
-     * @default 1000
-     */
-    maxSize?: number;
-    /**
-     * Whether to include user ID in cache key
-     * @default true
-     */
-    includeUserId?: boolean;
+interface ErrorTransformContext {
+    url: string;
+    method: string;
+    correlationId: string;
+    timeoutMs?: number;
+    elapsedMs?: number;
+    statusCode?: number;
+    contentType?: string;
+    responseSample?: string;
+    [key: string]: unknown;
 }
 /**
- * Statistics for CORS middleware performance monitoring
+ * SSE-specific error detail interfaces for BlaizeJS framework
+ *
+ * These interfaces define the structure of details for SSE errors.
+ * The actual error classes are implemented in blaize-core.
  */
-interface CorsStats {
-    /**
-     * Total number of CORS requests processed
-     */
-    totalRequests: number;
-    /**
-     * Number of preflight requests handled
-     */
-    preflightRequests: number;
-    /**
-     * Number of allowed origins
-     */
-    allowedOrigins: number;
-    /**
-     * Number of denied origins
-     */
-    deniedOrigins: number;
-    /**
-     * Cache hit rate for origin validation
-     */
-    cacheHitRate: number;
-    /**
-     * Average origin validation time in milliseconds
-     */
-    avgValidationTime: number;
-}
 /**
- * Cache entry type
+ * Details for SSE connection errors
  */
-interface CacheEntry {
-    allowed: boolean;
-    expiresAt: number;
-    lastAccessed: number;
+interface SSEConnectionErrorDetails {
+    /** Client identifier if available */
+    clientId?: string;
+    /** Connection attempt number */
+    attemptNumber?: number;
+    /** Maximum retry attempts configured */
+    maxRetries?: number;
+    /** The underlying error that caused connection failure */
+    cause?: string;
+    /** Suggested resolution */
+    suggestion?: string;
 }
 /**
- * Cache configuration
+ * Details for SSE buffer overflow errors
  */
-interface CacheConfig {
-    ttl: number;
+interface SSEBufferOverflowErrorDetails {
+    /** Client identifier */
+    clientId?: string;
+    /** Current buffer size when overflow occurred */
+    currentSize: number;
+    /** Maximum buffer size configured */
     maxSize: number;
+    /** Number of events dropped */
+    eventsDropped?: number;
+    /** Buffer strategy that was applied */
+    strategy: 'drop-oldest' | 'drop-newest' | 'close';
+    /** Event that triggered the overflow */
+    triggeringEvent?: string;
 }
-
 /**
- * Create CORS middleware with the specified options
- *
- * @param userOptions - CORS configuration options or boolean
- * @returns Middleware function that handles CORS
- *
- * @example
- * ```typescript
- * import { cors } from '@blaize-core/middleware/cors';
- *
- * // Development mode - allow all origins
- * server.use(cors(true));
- *
- * // Production - specific origin
- * server.use(cors({
- *   origin: 'https://app.example.com',
- *   credentials: true,
- *   maxAge: 86400
- * }));
- *
- * // Multiple origins with regex
- * server.use(cors({
- *   origin: [
- *     'https://app.example.com',
- *     /^https:\/\/.*\.example\.com$/
- *   ]
- * }));
- *
- * // Dynamic origin validation
- * server.use(cors({
- *   origin: async (origin, ctx) => {
- *     return await checkOriginAllowed(origin, ctx.state.user);
- *   }
- * }));
- * ```
+ * Details for SSE stream closed errors
  */
-declare function cors(userOptions?: CorsOptions | boolean): Middleware;
-
+interface SSEStreamClosedErrorDetails {
+    /** Client identifier */
+    clientId?: string;
+    /** When the stream was closed */
+    closedAt?: string;
+    /** Reason for closure */
+    closeReason?: 'client-disconnect' | 'server-close' | 'timeout' | 'error' | 'buffer-overflow';
+    /** Whether reconnection is possible */
+    canReconnect?: boolean;
+    /** Suggested retry interval in milliseconds */
+    retryAfter?: number;
+}
 /**
- * Create a middleware
+ * Context for SSE connection errors
  */
-declare function create$2<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
+interface SSEConnectionErrorContext {
+    /** The SSE endpoint URL */
+    url: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Connection state when error occurred */
+    state: 'connecting' | 'connected' | 'disconnected' | 'closed';
+    /** Number of reconnection attempts made */
+    reconnectAttempts?: number;
+    /** The original error if available */
+    originalError?: Error;
+    /** Additional SSE-specific details */
+    sseDetails?: {
+        /** Whether credentials were included */
+        withCredentials?: boolean;
+        /** Last received event ID */
+        lastEventId?: string;
+        /** EventSource ready state */
+        readyState?: number;
+    };
+}
 /**
- * Create a middleware that only contributes state (no services)
- * Convenience helper for state-only middleware
- *
- * @template T - Type of state to contribute
- * @param handler - Middleware function that adds state
- * @returns Middleware that contributes state only
- *
+ * Context for SSE stream errors (server-sent errors)
  */
-declare function stateMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<T, {}>;
+interface SSEStreamErrorContext {
+    /** The SSE endpoint URL */
+    url: string;
+    /** Correlation ID from server or client */
+    correlationId: string;
+    /** Error message from server */
+    message: string;
+    /** Error code if provided */
+    code?: string;
+    /** Error name/type from server */
+    name?: string;
+    /** Raw error data from server */
+    rawData?: any;
+}
 /**
- * Create a middleware that only contributes services (no state)
- * Convenience helper for service-only middleware
- *
- * @template T - Type of services to contribute
- * @param handler - Middleware function that adds services
- * @returns Middleware that contributes services only
- *
+ * Context for SSE heartbeat timeout errors
  */
-declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
+interface SSEHeartbeatErrorContext {
+    /** The SSE endpoint URL */
+    url: string;
+    /** Correlation ID for tracing */
+    correlationId: string;
+    /** Configured heartbeat timeout in ms */
+    heartbeatTimeout: number;
+    /** Time since last event in ms */
+    timeSinceLastEvent?: number;
+    /** Last event ID received */
+    lastEventId?: string;
+}
 
 /**
  * Represents a single Server-Sent Event
@@ -3430,4 +3404,4 @@ declare const Blaize: {
     VERSION: string;
 };
 
-export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyLimits, type BodyParseError, type BufferedEvent, type BuildRoutesRegistry, type BuildSSEArgs, type CacheConfig, type CacheEntry, type ClientConfig, type CloseEvent, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type ConnectionEntry, type ConnectionRegistry, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, type CorsHttpMethod, type CorsOptions, type CorsOrigin, type CorsOriginCacheConfig, type CorsOriginCacheEntry, type CorsPreflightInfo, type CorsStats, type CorsValidationResult, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateEnhancedClient, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type CreateSSEMethod, type CreateSSERoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type EventHandlers, type ExtractMethod, type ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type ExtractSSEEvents, type ExtractSSEParams, type ExtractSSEQuery, type ExtractSSERoutes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type HasSSEMethod, type Http2Options, type HttpMethod, type Infer, type InferContext, type InternalRequestArgs, InternalServerError, type InternalServerErrorDetails, type Matcher, type MergeServices, type MergeStates, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type MultipartData, type MultipartError, type MultipartLimits, type NetworkErrorContext, type NextFunction, NotFoundError, type NotFoundErrorDetails, type ParseErrorContext, type ParseOptions, type ParseResult, type ParsedRoute, type ParserState, PayloadTooLargeError, type PayloadTooLargeErrorDetails, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type ProcessingConfig, type QueryParams, RateLimitError, type RateLimitErrorDetails, type ReconnectStrategy, type RegistryResult, type ReloadMetrics, type RequestHandler, type RequestOptions, type RequestParams, RequestTimeoutError, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteRegistry, type RouteSchema, type Router, RouterAPI, type RouterOptions, type SSEBufferOverflowErrorDetails, type SSEBufferStrategy, type SSEClient, type SSEClientMetrics, type SSEClientOptions, type SSEConnectionErrorContext, type SSEConnectionErrorDetails, type SSEConnectionFactory, type SSEConnectionState, type SSEEvent, type SSEEventHandler, type SSEEventListener, type SSEHeartbeatErrorContext, type SSEMetrics, type SSEOptions, type SSERouteHandler, type SSERouteSchema, type SSESerializedEvent, type SSEStream, type SSEStreamClosedErrorDetails, type SSEStreamErrorContext, type SSEStreamExtended, type SSEStreamManager, type SafeComposeMiddlewareServices, type SafeComposeMiddlewareStates, type SafeComposePluginServices, type SafeComposePluginStates, type SafeExtractMiddlewareServices, type SafeExtractMiddlewareState, type SafeExtractPluginServices, type SafeExtractPluginState, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type ServiceNotAvailableDetails, ServiceNotAvailableError, type Services, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamMetrics, type StreamOptions, type TimeoutErrorContext, type TypedSSEStream, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnionToIntersection, type UnknownFunction, type UnknownServer, UnprocessableEntityError, UnsupportedMediaTypeError, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, asMiddlewareArray, asPluginArray, buildUrl, compilePathPattern, compose, cors, createDeleteRoute, createGetRoute, createHeadRoute, createMatcher, create$2 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, extractParams, getCorrelationId, inferContext, isBodyParseError, isMiddleware, isPlugin, paramsToQuery };
+export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyLimits, type BufferedEvent, type BuildRoutesRegistry, type BuildSSEArgs, type CacheConfig, type CacheEntry, type ClientConfig, type CloseEvent, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type ConnectionEntry, type ConnectionRegistry, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, type CorsHttpMethod, type CorsOptions, type CorsOrigin, type CorsOriginCacheConfig, type CorsOriginCacheEntry, type CorsPreflightInfo, type CorsStats, type CorsValidationResult, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateEnhancedClient, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type CreateSSEMethod, type CreateSSERoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type EventHandlers, type ExtractMethod, type ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type ExtractSSEEvents, type ExtractSSEParams, type ExtractSSEQuery, type ExtractSSERoutes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type HasSSEMethod, type Http2Options, type HttpMethod, type Infer, type InferContext, type InternalRequestArgs, InternalServerError, type InternalServerErrorDetails, type Matcher, type MergeServices, type MergeStates, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type MultipartData, type MultipartError, type MultipartLimits, type NetworkErrorContext, type NextFunction, NotFoundError, type NotFoundErrorDetails, type ParseErrorContext, type ParseOptions, type ParseResult, type ParsedRoute, type ParserState, PayloadTooLargeError, type PayloadTooLargeErrorDetails, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type ProcessingConfig, type QueryParams, RateLimitError, type RateLimitErrorDetails, type ReconnectStrategy, type RegistryResult, type ReloadMetrics, type RequestHandler, type RequestOptions, type RequestParams, RequestTimeoutError, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteRegistry, type RouteSchema, type Router, RouterAPI, type RouterOptions, type SSEBufferOverflowErrorDetails, type SSEBufferStrategy, type SSEClient, type SSEClientMetrics, type SSEClientOptions, type SSEConnectionErrorContext, type SSEConnectionErrorDetails, type SSEConnectionFactory, type SSEConnectionState, type SSEEvent, type SSEEventHandler, type SSEEventListener, type SSEHeartbeatErrorContext, type SSEMetrics, type SSEOptions, type SSERouteHandler, type SSERouteSchema, type SSESerializedEvent, type SSEStream, type SSEStreamClosedErrorDetails, type SSEStreamErrorContext, type SSEStreamExtended, type SSEStreamManager, type SafeComposeMiddlewareServices, type SafeComposeMiddlewareStates, type SafeComposePluginServices, type SafeComposePluginStates, type SafeExtractMiddlewareServices, type SafeExtractMiddlewareState, type SafeExtractPluginServices, type SafeExtractPluginState, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type ServiceNotAvailableDetails, ServiceNotAvailableError, type Services, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamMetrics, type StreamOptions, type TimeoutErrorContext, type TypedSSEStream, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnionToIntersection, type UnknownFunction, type UnknownServer, UnprocessableEntityError, UnsupportedMediaTypeError, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, asMiddlewareArray, asPluginArray, buildUrl, compilePathPattern, compose, cors, createDeleteRoute, createGetRoute, createHeadRoute, createMatcher, create$2 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, extractParams, getCorrelationId, inferContext, isMiddleware, isPlugin, paramsToQuery };