blaizejs 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -1,57 +1,670 @@
+import { z } from 'zod';
 import http, { IncomingMessage, ServerResponse } from 'node:http';
 import http2, { Http2ServerRequest, Http2ServerResponse } from 'node:http2';
+import { WriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { z } from 'zod';
 import { EventEmitter } from 'node:events';
 
 /**
- * Compose multiple middleware functions into a single middleware function
+ * 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.
  */
-declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
-
 /**
- * Create a middleware
+ * 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"]
+ *   }
+ * }
+ * ```
  */
-declare function create$2(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware;
-
+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;
+}
 /**
- * Create a plugin with the given name, version, and setup function
+ * Context information for network-related errors
+ *
+ * Used by client-side error classes to provide additional context
+ * about network failures, timeouts, and connection issues.
  */
-declare function create$1<T = any>(name: string, version: string, setup: (app: Server, options: T) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<T>): PluginFactory<T>;
-
+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;
+    };
+}
 /**
- * Create a GET route
+ * Context information for request timeout errors
+ *
+ * Specialized context for timeout-specific errors with timing information.
  */
-declare const createGetRoute: CreateGetRoute;
+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';
+}
 /**
- * Create a POST route
+ * Context information for response parsing errors
+ *
+ * Used when the client receives a response but cannot parse it properly.
  */
-declare const createPostRoute: CreatePostRoute;
+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;
+}
 /**
- * Create a PUT route
+ * Validation error field details
+ *
+ * Structure for field-level validation errors with multiple error messages
+ * per field.
  */
-declare const createPutRoute: CreatePutRoute;
+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;
+}
 /**
- * Create a DELETE route
+ * Validation error details structure
+ *
+ * Used by ValidationError to provide structured information about
+ * what fields failed validation and why.
  */
-declare const createDeleteRoute: CreateDeleteRoute;
+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;
+}
 /**
- * Create a PATCH route
+ * 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
+ *   }
+ * }
+ * ```
  */
-declare const createPatchRoute: CreatePatchRoute;
+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",
+    /** 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"
+}
 /**
- * Create a HEAD route (same signature as GET - no body)
+ * Error severity levels for logging and monitoring
+ *
+ * Provides a way to categorize errors by their impact and urgency.
  */
-declare const createHeadRoute: CreateHeadRoute;
+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"
+}
 /**
- * Create an OPTIONS route (same signature as GET - no body)
+ * 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
  */
-declare const createOptionsRoute: CreateOptionsRoute;
+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;
+    /**
+     * 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
+     */
+    protected constructor(type: ErrorType, title: string, status: number, correlationId: string, details?: TDetails | undefined);
+    /**
+     * Serializes the error to a plain object suitable for HTTP responses
+     *
+     * @returns Object representation of the error
+     */
+    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;
+}
+/**
+ * Interface for payload too large error details
+ */
+interface PayloadTooLargeErrorDetails {
+    fileCount?: number;
+    maxFiles?: number;
+    filename?: string;
+    field?: string;
+    contentType?: string;
+    currentSize?: number;
+    maxSize?: number;
+}
+/**
+ * Interface for unsupported media type error details
+ */
+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' | 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;
+}
+/**
+ * Interface for NotFound error details
+ * Provides context about the missing resource
+ */
+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;
+}
+/**
+ * Interface for body parsing errors stored in context state
+ */
+interface BodyParseError {
+    /**
+     * Type of parsing error that occurred
+     */
+    readonly type: 'json_parse_error' | 'form_parse_error' | 'multipart_parse_error' | 'body_read_error';
+    /**
+     * Human-readable error message
+     */
+    readonly message: string;
+    /**
+     * Original error object or details
+     */
+    readonly error: unknown;
+}
+/**
+ * Type guard to check if an object is a BodyParseError
+ */
+declare function isBodyParseError(error: unknown): error is BodyParseError;
+/**
+ * Context information for error transformation
+ */
+interface ErrorTransformContext {
+    url: string;
+    method: string;
+    correlationId: string;
+    timeoutMs?: number;
+    elapsedMs?: number;
+    statusCode?: number;
+    contentType?: string;
+    responseSample?: string;
+    [key: string]: unknown;
+}
 
 /**
- * Creates a BlaizeJS server instance
+ * Represents an uploaded file in a multipart/form-data request
  */
-declare function create(options?: ServerOptionsInput): Server;
+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;
+}
+/**
+ * Complete multipart/form-data parsed content
+ */
+interface MultipartData {
+    /** Form fields (non-file inputs) */
+    readonly fields: Record<string, string | string[]>;
+    /** Uploaded files */
+    readonly files: Record<string, UploadedFile | UploadedFile[]>;
+}
+/**
+ * Options for parsing multipart/form-data
+ */
+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;
+}
+/**
+ * Result of parsing multipart data with metadata
+ */
+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;
+    };
+}
+/**
+ * Error information for multipart parsing failures
+ */
+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;
+}
+/**
+ * Configuration for file upload validation
+ */
+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;
+}
+/**
+ * File processing configuration
+ */
+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;
+}
+/**
+ * Upload progress information (for future streaming uploads)
+ */
+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;
+}
+/**
+ * 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;
+}
 
 /**
  * Unified request type supporting both HTTP/1.1 and HTTP/2
@@ -87,6 +700,11 @@ interface StreamOptions {
  */
 interface State {
     [key: string]: unknown;
+    /**
+     * Body parsing error information
+     * Set when body parsing fails during request processing
+     */
+    _bodyError?: BodyParseError;
 }
 interface ContextResponse<S extends State = State> {
     raw: UnifiedResponse;
@@ -111,6 +729,16 @@ interface ContextRequest<TBody = unknown> {
     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>;
 }
@@ -134,6 +762,12 @@ interface Context<S extends State = State, TBody = unknown, TQuery = QueryParams
      */
     state: S;
 }
+type MultipartLimits = {
+    maxFileSize?: number;
+    maxTotalSize?: number;
+    maxFiles?: number;
+    maxFieldSize?: number;
+};
 /**
  * Options for creating a context
  */
@@ -146,6 +780,16 @@ interface ContextOptions {
      * Additional state to merge into the context
      */
     initialState?: State;
+    /**
+     * Limits for various body types to prevent abuse
+     */
+    bodyLimits?: {
+        json?: number;
+        form?: number;
+        text?: number;
+        multipart?: MultipartLimits;
+        raw?: number;
+    };
 }
 /**
  * Function to get the current context from AsyncLocalStorage
@@ -207,7 +851,11 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTION
 /**
  * Schema for route validation with generic type parameters
  */
-interface RouteSchema<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>> {
+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 */
@@ -216,6 +864,8 @@ interface RouteSchema<P extends z.ZodType = z.ZodType<any>, Q extends z.ZodType
     body?: B;
     /** Response schema for validation */
     response?: R;
+    /** Error Response Details schema for validation */
+    errorResponseDetails?: ED;
 }
 /**
  * Route handler function with strongly typed params and response
@@ -224,9 +874,9 @@ type RouteHandler<TParams = Record<string, string>, TQuery = Record<string, stri
 /**
  * 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>> {
+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>;
+    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 */
@@ -238,13 +888,13 @@ interface RouteMethodOptions<P extends z.ZodType = z.ZodType<any>, Q extends z.Z
  * Route definition mapping HTTP methods to handlers
  */
 interface RouteDefinition {
-    GET?: RouteMethodOptions<any, any, never, any>;
-    POST?: RouteMethodOptions<any, any, any, any>;
-    PUT?: RouteMethodOptions<any, any, any, any>;
-    DELETE?: RouteMethodOptions<any, any, never, any>;
-    PATCH?: RouteMethodOptions<any, any, any, any>;
-    HEAD?: RouteMethodOptions<any, any, never, any>;
-    OPTIONS?: RouteMethodOptions<any, any, never, any>;
+    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>;
 }
 /**
  * Route object with path
@@ -297,6 +947,12 @@ interface Router {
     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;
@@ -306,6 +962,8 @@ interface Router {
         path: string;
         sources: string[];
     }>;
+    /** Close watchers and cleanup resources */
+    close?: () => Promise<void>;
 }
 /**
  * Route match result
@@ -339,6 +997,10 @@ interface Matcher {
         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;
@@ -500,122 +1162,57 @@ type CreateOptionsRoute = <P extends z.ZodType = z.ZodType<any>, Q extends z.Zod
     OPTIONS: RouteMethodOptions<P, Q, never, R>;
     path: string;
 };
-
-type ExtractParams<T> = T extends RouteMethodOptions<infer P, any, any, any> ? P extends z.ZodType ? Infer<P> : Record<string, string> : never;
-type ExtractQuery<T> = T extends RouteMethodOptions<any, infer Q, any, any> ? Q extends z.ZodType ? Infer<Q> : Record<string, string | string[] | undefined> : never;
-type ExtractBody<T> = T extends RouteMethodOptions<any, any, infer B, any> ? B extends z.ZodType ? Infer<B> : unknown : never;
-type ExtractResponse<T> = T extends RouteMethodOptions<any, any, any, infer R> ? R extends z.ZodType ? Infer<R> : unknown : never;
-type ExtractMethod<T> = T extends {
-    GET: any;
-} ? 'GET' : T extends {
-    POST: any;
-} ? 'POST' : T extends {
-    PUT: any;
-} ? 'PUT' : T extends {
-    DELETE: any;
-} ? 'DELETE' : T extends {
-    PATCH: any;
-} ? 'PATCH' : T extends {
-    HEAD: any;
-} ? 'HEAD' : T extends {
-    OPTIONS: any;
-} ? 'OPTIONS' : never;
-type BuildRoutesRegistry<TRoutes extends Record<string, any>> = {
-    [Method in ExtractMethod<TRoutes[keyof TRoutes]> as `$${Lowercase<Method>}`]: {
-        [K in keyof TRoutes as ExtractMethod<TRoutes[K]> extends Method ? K : never]: TRoutes[K];
-    };
-};
-type GetRouteMethod<TRoute> = TRoute extends {
-    path: string;
-} ? Omit<TRoute, 'path'>[keyof Omit<TRoute, 'path'>] : never;
-type CreateClientMethod<TRoute> = GetRouteMethod<TRoute> extends RouteMethodOptions<any, any, any, any> ? (args?: {
-    params?: ExtractParams<GetRouteMethod<TRoute>>;
-    query?: ExtractQuery<GetRouteMethod<TRoute>>;
-    body?: ExtractBody<GetRouteMethod<TRoute>>;
-}) => Promise<ExtractResponse<GetRouteMethod<TRoute>>> : never;
-type CreateClient<TRoutes extends Record<string, Record<string, any>>> = {
-    [Method in keyof TRoutes]: {
-        [RouteName in keyof TRoutes[Method]]: CreateClientMethod<TRoutes[Method][RouteName]>;
-    };
-};
-interface ClientConfig {
-    baseUrl: string;
-    defaultHeaders?: Record<string, string>;
-    timeout?: number;
+interface FileCache {
+    routes: Route[];
+    timestamp: number;
+    hash: string;
 }
-interface RequestArgs {
-    params?: Record<string, string>;
-    query?: Record<string, any>;
-    body?: unknown;
+interface ReloadMetrics {
+    fileChanges: number;
+    totalReloadTime: number;
+    averageReloadTime: number;
+    slowReloads: Array<{
+        file: string;
+        time: number;
+    }>;
 }
-interface RequestOptions {
-    method: string;
-    url: string;
-    headers: Record<string, string>;
-    body?: string;
-    timeout: 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;
 }
 
 /**
- * BlaizeJS Plugin Module
- *
- * Provides the plugin system for extending framework functionality.
+ * Compose multiple middleware functions into a single middleware function
  */
+declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
 
 /**
- * Plugin options
+ * Create a middleware
  */
-interface PluginOptions<_T = any> {
-    /** Plugin configuration */
-    [key: string]: any;
-}
+declare function create$2(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware;
+
 /**
- * Plugin lifecycle hooks
- */
-interface PluginHooks {
-    /** Called when the plugin is registered */
-    register: (app: Server) => void | Promise<void>;
-    /** Called when the server is initialized */
-    initialize?: (app?: Server) => void | Promise<void>;
-    /** Called when the server is terminated */
-    terminate?: (app?: Server) => void | Promise<void>;
-    /** Called when the server starts */
-    onServerStart?: (server: any) => void | Promise<void>;
-    /** Called when the server stops */
-    onServerStop?: (server: any) => void | Promise<void>;
-}
-/**
- * Plugin interface
- */
-interface Plugin extends PluginHooks {
-    /** Plugin name */
-    name: string;
-    /** Plugin version */
-    version: string;
-}
-/**
- * Plugin factory function
- */
-type PluginFactory<T = any> = (options?: T) => Plugin;
-interface PluginLifecycleManager {
-    initializePlugins(server: Server): Promise<void>;
-    terminatePlugins(server: Server): Promise<void>;
-    onServerStart(server: Server, httpServer: any): Promise<void>;
-    onServerStop(server: Server, httpServer: any): Promise<void>;
-}
-interface PluginLifecycleOptions {
-    /** Continue initialization even if a plugin fails */
-    continueOnError?: boolean;
-    /** Log plugin lifecycle events */
-    debug?: boolean;
-    /** Custom error handler for plugin failures */
-    onError?: (plugin: Plugin, phase: string, error: Error) => void;
-}
-
-/**
- * BlaizeJS Server Module
- *
- * Provides the core HTTP/2 server implementation with HTTP/1.1 fallback.
+ * BlaizeJS Server Module
+ *
+ * Provides the core HTTP/2 server implementation with HTTP/1.1 fallback.
  */
 
 interface Http2Options {
@@ -716,6 +1313,454 @@ interface Server {
 }
 type RequestHandler = (req: http.IncomingMessage | http2.Http2ServerRequest, res: http.ServerResponse | http2.Http2ServerResponse) => Promise<void>;
 
+/**
+ * BlaizeJS Plugin Module
+ *
+ * Provides the plugin system for extending framework functionality.
+ */
+
+/**
+ * Plugin options
+ */
+interface PluginOptions<_T = any> {
+    /** Plugin configuration */
+    [key: string]: any;
+}
+/**
+ * Plugin lifecycle hooks
+ */
+interface PluginHooks {
+    /** Called when the plugin is registered */
+    register: (app: Server) => void | Promise<void>;
+    /** Called when the server is initialized */
+    initialize?: (app?: Server) => void | Promise<void>;
+    /** Called when the server is terminated */
+    terminate?: (app?: Server) => void | Promise<void>;
+    /** Called when the server starts */
+    onServerStart?: (server: any) => void | Promise<void>;
+    /** Called when the server stops */
+    onServerStop?: (server: any) => void | Promise<void>;
+}
+/**
+ * Plugin interface
+ */
+interface Plugin extends PluginHooks {
+    /** Plugin name */
+    name: string;
+    /** Plugin version */
+    version: string;
+}
+/**
+ * Plugin factory function
+ */
+type PluginFactory<T = any> = (options?: T) => Plugin;
+interface PluginLifecycleManager {
+    initializePlugins(server: Server): Promise<void>;
+    terminatePlugins(server: Server): Promise<void>;
+    onServerStart(server: Server, httpServer: any): Promise<void>;
+    onServerStop(server: Server, httpServer: any): Promise<void>;
+}
+interface PluginLifecycleOptions {
+    /** Continue initialization even if a plugin fails */
+    continueOnError?: boolean;
+    /** Log plugin lifecycle events */
+    debug?: boolean;
+    /** Custom error handler for plugin failures */
+    onError?: (plugin: Plugin, phase: string, error: Error) => void;
+}
+
+/**
+ * Create a plugin with the given name, version, and setup function
+ */
+declare function create$1<T = any>(name: string, version: string, setup: (app: Server, options: T) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<T>): PluginFactory<T>;
+
+/**
+ * Create a GET route
+ */
+declare const createGetRoute: CreateGetRoute;
+/**
+ * Create a POST route
+ */
+declare const createPostRoute: CreatePostRoute;
+/**
+ * Create a PUT route
+ */
+declare const createPutRoute: CreatePutRoute;
+/**
+ * Create a DELETE route
+ */
+declare const createDeleteRoute: CreateDeleteRoute;
+/**
+ * Create a PATCH route
+ */
+declare const createPatchRoute: CreatePatchRoute;
+/**
+ * Create a HEAD route (same signature as GET - no body)
+ */
+declare const createHeadRoute: CreateHeadRoute;
+/**
+ * Create an OPTIONS route (same signature as GET - no body)
+ */
+declare const createOptionsRoute: CreateOptionsRoute;
+
+/**
+ * Creates a BlaizeJS server instance
+ */
+declare function create(options?: ServerOptionsInput): Server;
+
+type ExtractParams<T> = T extends RouteMethodOptions<infer P, any, any, any> ? P extends z.ZodType ? Infer<P> : Record<string, string> : never;
+type ExtractQuery<T> = T extends RouteMethodOptions<any, infer Q, any, any> ? Q extends z.ZodType ? Infer<Q> : Record<string, string | string[] | undefined> : never;
+type ExtractBody<T> = T extends RouteMethodOptions<any, any, infer B, any> ? B extends z.ZodType ? Infer<B> : unknown : never;
+type ExtractResponse<T> = T extends RouteMethodOptions<any, any, any, infer R> ? R extends z.ZodType ? Infer<R> : unknown : never;
+type ExtractMethod<T> = T extends {
+    GET: any;
+} ? 'GET' : T extends {
+    POST: any;
+} ? 'POST' : T extends {
+    PUT: any;
+} ? 'PUT' : T extends {
+    DELETE: any;
+} ? 'DELETE' : T extends {
+    PATCH: any;
+} ? 'PATCH' : T extends {
+    HEAD: any;
+} ? 'HEAD' : T extends {
+    OPTIONS: any;
+} ? 'OPTIONS' : never;
+type BuildRoutesRegistry<TRoutes extends Record<string, any>> = {
+    [Method in ExtractMethod<TRoutes[keyof TRoutes]> as `$${Lowercase<Method>}`]: {
+        [K in keyof TRoutes as ExtractMethod<TRoutes[K]> extends Method ? K : never]: TRoutes[K];
+    };
+};
+type GetRouteMethod<TRoute> = TRoute extends {
+    path: string;
+} ? Omit<TRoute, 'path'>[keyof Omit<TRoute, 'path'>] : never;
+type CreateClientMethod<TRoute> = GetRouteMethod<TRoute> extends RouteMethodOptions<any, any, any, any> ? (args?: {
+    params?: ExtractParams<GetRouteMethod<TRoute>>;
+    query?: ExtractQuery<GetRouteMethod<TRoute>>;
+    body?: ExtractBody<GetRouteMethod<TRoute>>;
+}) => Promise<ExtractResponse<GetRouteMethod<TRoute>>> : never;
+type CreateClient<TRoutes extends Record<string, Record<string, any>>> = {
+    [Method in keyof TRoutes]: {
+        [RouteName in keyof TRoutes[Method]]: CreateClientMethod<TRoutes[Method][RouteName]>;
+    };
+};
+interface ClientConfig {
+    baseUrl: string;
+    defaultHeaders?: Record<string, string>;
+    timeout?: number;
+}
+interface RequestArgs {
+    params?: Record<string, string>;
+    query?: Record<string, any>;
+    body?: unknown;
+}
+interface RequestOptions {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeout: number;
+}
+
+/**
+ * ValidationError class for request validation failures
+ *
+ * This error is thrown when request validation fails (params, query, body, or response).
+ * It provides structured information about which fields failed validation and why.
+ */
+
+/**
+ * Error thrown when request validation fails
+ *
+ * Automatically sets HTTP status to 400 and provides structured
+ * validation error information for better client debugging.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new ValidationError('Email is required');
+ * ```
+ *
+ * @example With detailed field information:
+ * ```typescript
+ * throw new ValidationError('Validation failed', {
+ *   fields: [
+ *     {
+ *       field: 'email',
+ *       messages: ['Email is required', 'Email must be valid'],
+ *       rejectedValue: '',
+ *       expectedType: 'string'
+ *     }
+ *   ],
+ *   errorCount: 1,
+ *   section: 'body'
+ * });
+ * ```
+ */
+declare class ValidationError extends BlaizeError<ValidationErrorDetails> {
+    /**
+     * Creates a new ValidationError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional structured validation details
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: ValidationErrorDetails | undefined, correlationId?: string | undefined);
+}
+
+/**
+ * NotFoundError class for resource not found errors
+ *
+ * This error is thrown when a requested resource cannot be found.
+ * It provides context about what resource was being looked for and how.
+ */
+
+/**
+ * Error thrown when a requested resource cannot be found
+ *
+ * Automatically sets HTTP status to 404 and provides context
+ * about the missing resource for better debugging and user experience.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new NotFoundError('User not found');
+ * ```
+ *
+ * @example With resource context:
+ * ```typescript
+ * throw new NotFoundError('User not found', {
+ *   resourceType: 'User',
+ *   resourceId: 'user-123',
+ *   suggestion: 'Check if the user ID is correct'
+ * });
+ * ```
+ *
+ * @example API endpoint not found:
+ * ```typescript
+ * throw new NotFoundError('Endpoint not found', {
+ *   path: '/api/v1/unknown',
+ *   method: 'GET',
+ *   suggestion: 'Check the API documentation'
+ * });
+ * ```
+ */
+declare class NotFoundError extends BlaizeError<NotFoundErrorDetails> {
+    /**
+     * Creates a new NotFoundError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional context about the missing resource
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: NotFoundErrorDetails | undefined, correlationId?: string | undefined);
+}
+
+/**
+ * UnauthorizedError class for authentication failures
+ *
+ * This error is thrown when authentication is required or has failed.
+ * It provides context about authentication requirements and failure reasons.
+ */
+
+/**
+ * Error thrown when authentication is required or has failed
+ *
+ * Automatically sets HTTP status to 401 and provides authentication context.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new UnauthorizedError('Authentication required');
+ * ```
+ *
+ * @example With authentication details:
+ * ```typescript
+ * throw new UnauthorizedError('Token expired', {
+ *   reason: 'expired_token',
+ *   authScheme: 'Bearer',
+ *   loginUrl: '/auth/login'
+ * });
+ * ```
+ */
+declare class UnauthorizedError extends BlaizeError<UnauthorizedErrorDetails> {
+    /**
+     * Creates a new UnauthorizedError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional authentication context
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: UnauthorizedErrorDetails | undefined, correlationId?: string | undefined);
+}
+
+/**
+ * ForbiddenError class for authorization failures
+ *
+ * This error is thrown when a user lacks permission to access a resource.
+ * It provides context about required permissions and access control.
+ */
+
+/**
+ * Error thrown when user lacks permission to access a resource
+ *
+ * Automatically sets HTTP status to 403 and provides permission context.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new ForbiddenError('Access denied');
+ * ```
+ *
+ * @example With permission details:
+ * ```typescript
+ * throw new ForbiddenError('Insufficient permissions', {
+ *   requiredPermission: 'admin:users:delete',
+ *   userPermissions: ['admin:users:read'],
+ *   resource: 'user-123',
+ *   action: 'delete'
+ * });
+ * ```
+ */
+declare class ForbiddenError extends BlaizeError<ForbiddenErrorDetails> {
+    /**
+     * Creates a new ForbiddenError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional permission context
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: ForbiddenErrorDetails | undefined, correlationId?: string | undefined);
+}
+
+/**
+ * ConflictError class for resource conflicts
+ *
+ * This error is thrown when a resource conflict occurs, such as duplicate keys,
+ * version mismatches, or concurrent modifications.
+ */
+
+/**
+ * Error thrown when a resource conflict occurs
+ *
+ * Automatically sets HTTP status to 409 and provides conflict context.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new ConflictError('Email already exists');
+ * ```
+ *
+ * @example With conflict details:
+ * ```typescript
+ * throw new ConflictError('Version conflict', {
+ *   conflictType: 'version_mismatch',
+ *   currentVersion: '2',
+ *   expectedVersion: '1',
+ *   resolution: 'Fetch the latest version and retry'
+ * });
+ * ```
+ */
+declare class ConflictError extends BlaizeError<ConflictErrorDetails> {
+    /**
+     * Creates a new ConflictError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional conflict context
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: ConflictErrorDetails | undefined, correlationId?: string | undefined);
+}
+
+/**
+ * RateLimitError class for rate limiting violations
+ *
+ * This error is thrown when rate limits are exceeded.
+ * It provides context about the rate limit and when requests can resume.
+ */
+
+/**
+ * Error thrown when rate limits are exceeded
+ *
+ * Automatically sets HTTP status to 429 and provides rate limit context.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new RateLimitError('Too many requests');
+ * ```
+ *
+ * @example With rate limit details:
+ * ```typescript
+ * throw new RateLimitError('Rate limit exceeded', {
+ *   limit: 100,
+ *   remaining: 0,
+ *   retryAfter: 3600,
+ *   window: 'hour',
+ *   identifier: 'user-123'
+ * });
+ * ```
+ */
+declare class RateLimitError extends BlaizeError<RateLimitErrorDetails> {
+    /**
+     * Creates a new RateLimitError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional rate limit context
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: RateLimitErrorDetails | undefined, correlationId?: string | undefined);
+}
+
+/**
+ * InternalServerError class for server-side errors
+ *
+ * This error is thrown for unexpected server-side errors that are not
+ * the client's fault. It provides debugging context while protecting
+ * sensitive information in production.
+ */
+
+/**
+ * Error thrown for internal server errors
+ *
+ * Automatically sets HTTP status to 500 and provides debugging context.
+ * Note: In production, sensitive details should be filtered by error boundary.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * throw new InternalServerError('Something went wrong');
+ * ```
+ *
+ * @example With debugging details:
+ * ```typescript
+ * throw new InternalServerError('Database error', {
+ *   originalError: error.message,
+ *   component: 'user-service',
+ *   operation: 'createUser',
+ *   retryable: true
+ * });
+ * ```
+ *
+ * @example Wrapping an existing error:
+ * ```typescript
+ * try {
+ *   await database.connect();
+ * } catch (error) {
+ *   throw new InternalServerError('Database connection failed', {
+ *     originalError: error.message,
+ *     stackTrace: error.stack,
+ *     component: 'database',
+ *     retryable: true
+ *   });
+ * }
+ * ```
+ */
+declare class InternalServerError extends BlaizeError<InternalServerErrorDetails> {
+    /**
+     * Creates a new InternalServerError instance
+     *
+     * @param title - Human-readable error message
+     * @param details - Optional debugging context
+     * @param correlationId - Optional correlation ID (uses current context if not provided)
+     */
+    constructor(title: string, details?: InternalServerErrorDetails | undefined, correlationId?: string | undefined);
+}
+
 declare const VERSION = "0.1.0";
 declare const ServerAPI: {
     createServer: typeof create;
@@ -736,6 +1781,7 @@ declare const MiddlewareAPI: {
 declare const PluginsAPI: {
     createPlugin: typeof create$1;
 };
+
 declare const Blaize: {
     createServer: typeof create;
     createMiddleware: typeof create$2;
@@ -762,4 +1808,4 @@ declare const Blaize: {
     VERSION: string;
 };
 
-export { Blaize, type BuildRoutesRegistry, type ClientConfig, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type ErrorHandlerOptions, type ExtractBody, type ExtractMethod, type ExtractParams, type ExtractQuery, type ExtractResponse, type GetContextFn, type Http2Options, type HttpMethod, type Infer, type Matcher, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type NextFunction, type ParsedRoute, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type QueryParams, type RequestArgs, type RequestHandler, type RequestOptions, type RequestParams, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteSchema, type Router, RouterAPI, type RouterOptions, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamOptions, type UnifiedRequest, type UnifiedResponse, type UnknownFunction, VERSION, compose, createDeleteRoute, createGetRoute, createHeadRoute, create$2 as createMiddleware, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPostRoute, createPutRoute, create as createServer, Blaize as default };
+export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyParseError, type BuildRoutesRegistry, type ClientConfig, ConflictError, type ConflictErrorDetails, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type ExtractBody, type ExtractMethod, type ExtractParams, type ExtractQuery, type ExtractResponse, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type Http2Options, type HttpMethod, type Infer, InternalServerError, type InternalServerErrorDetails, type Matcher, 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, 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 ReloadMetrics, type RequestArgs, type RequestHandler, type RequestOptions, type RequestParams, 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 Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamOptions, type TimeoutErrorContext, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnknownFunction, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, compose, createDeleteRoute, createGetRoute, createHeadRoute, create$2 as createMiddleware, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPostRoute, createPutRoute, create as createServer, Blaize as default, isBodyParseError };