blaizejs 0.3.4 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as zod from 'zod';
 import { z } from 'zod';
 import http, { IncomingMessage, ServerResponse } from 'node:http';
 import http2, { Http2ServerRequest, Http2ServerResponse } from 'node:http2';
@@ -180,6 +181,8 @@ declare enum ErrorType {
     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) */
@@ -201,7 +204,13 @@ declare enum ErrorType {
     /** Response parsing failure (0) */
     PARSE_ERROR = "PARSE_ERROR",
     /** Generic HTTP error (varies) */
-    HTTP_ERROR = "HTTP_ERROR"
+    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"
 }
 /**
  * Error severity levels for logging and monitoring
@@ -356,7 +365,7 @@ interface ForbiddenErrorDetails {
     /** Action being attempted */
     action?: string;
     /** Reason for access denial */
-    reason?: 'insufficient_permissions' | 'account_suspended' | 'resource_locked' | string;
+    reason?: 'insufficient_permissions' | 'account_suspended' | 'resource_locked' | 'origin_not_allowed' | string;
     /** Additional context */
     [key: string]: unknown;
 }
@@ -491,6 +500,115 @@ interface ErrorTransformContext {
     responseSample?: string;
     [key: string]: unknown;
 }
+/**
+ * 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.
+ */
+/**
+ * Details for SSE connection errors
+ */
+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;
+}
+/**
+ * Details for SSE buffer overflow errors
+ */
+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;
+}
+/**
+ * Details for SSE stream closed errors
+ */
+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;
+}
+/**
+ * Context for SSE connection errors
+ */
+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;
+    };
+}
+/**
+ * Context for SSE stream errors (server-sent errors)
+ */
+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;
+}
+/**
+ * Context for SSE heartbeat timeout errors
+ */
+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 an uploaded file in a multipart/form-data request
@@ -706,9 +824,17 @@ interface State {
      */
     _bodyError?: BodyParseError;
 }
+/**
+ * Services container for storing injectable services/dependencies
+ * Allows middleware to contribute services that are accessible throughout the request lifecycle
+ */
+interface Services {
+    [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>;
@@ -744,8 +870,12 @@ interface ContextRequest<TBody = unknown> {
 }
 /**
  * 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, TBody = unknown, TQuery = QueryParams> {
+interface Context<S extends State = State, Svc extends Services = Services, TBody = unknown, TQuery = QueryParams> {
     /**
      * Request information
      */
@@ -761,6 +891,11 @@ interface Context<S extends State = State, TBody = unknown, TQuery = QueryParams
      * 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;
 }
 type MultipartLimits = {
     maxFileSize?: number;
@@ -777,9 +912,15 @@ interface ContextOptions {
      */
     parseBody?: boolean;
     /**
-     * Additional state to merge into the context
+     * 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
      */
@@ -794,7 +935,7 @@ interface ContextOptions {
 /**
  * Function to get the current context from AsyncLocalStorage
  */
-type GetContextFn = <S extends State = State>() => Context<S> | undefined;
+type GetContextFn = <S extends State = State, Svc extends Services = Services>() => Context<S, Svc> | undefined;
 /**
  * Factory function for creating a new context
  */
@@ -826,18 +967,21 @@ interface MiddlewareOptions {
     /** The middleware handler function */
     handler: MiddlewareFunction;
     /** Skip function to conditionally bypass middleware */
-    skip?: ((ctx: Context) => boolean) | undefined;
+    skip?: ((ctx: Context<any, any>) => boolean) | undefined;
     /** Enable debugging for this middleware */
     debug?: boolean;
 }
 /**
- * Middleware type
+ * 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 Middleware {
+interface Middleware<TState = {}, TServices = {}> {
     name: string;
     execute: MiddlewareFunction;
     skip?: ((ctx: Context) => boolean) | undefined;
     debug?: boolean | undefined;
+    _services?: TServices;
 }
 
 /**
@@ -870,7 +1014,8 @@ ED extends z.ZodType = z.ZodType<any>> {
 /**
  * Route handler function with strongly typed params and response
  */
-type RouteHandler<TParams = Record<string, string>, TQuery = Record<string, string | string[] | undefined>, TBody = unknown, TResponse = unknown> = (ctx: Context<State, TBody, TQuery>, params: TParams) => Promise<TResponse> | TResponse;
+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
  */
@@ -1084,32 +1229,29 @@ interface FindRouteFilesOptions {
     ignore?: string[] | undefined;
 }
 /**
- * GET route creator - no body schema needed
- * FIXED: Default type parameters to never instead of z.ZodType<any>
+ * GET route creator with state and services support
+ * Now returns a higher-order function to handle generics properly
  */
-type CreateGetRoute = <P = never, // Changed from z.ZodType<any>
-Q = never, // Changed from z.ZodType<any>
-R = never>(config: {
+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, [
+    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>;
+    ] 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, // GET never has body
-    R extends never ? never : R extends z.ZodType ? R : never>;
+    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;
 };
 /**
- * POST route creator - includes body schema
- * FIXED: Default type parameters to never
+ * POST route creator with state and services support
  */
-type CreatePostRoute = <P = never, Q = never, B = never, R = never>(config: {
+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;
@@ -1118,7 +1260,7 @@ type CreatePostRoute = <P = never, Q = never, B = never, R = never>(config: {
     };
     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>;
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
     middleware?: Middleware[];
     options?: Record<string, unknown>;
 }) => {
@@ -1126,10 +1268,9 @@ type CreatePostRoute = <P = never, Q = never, B = never, R = never>(config: {
     path: string;
 };
 /**
- * PUT route creator - includes body schema
- * FIXED: Default type parameters to never
+ * PUT route creator with state and services support
  */
-type CreatePutRoute = <P = never, Q = never, B = never, R = never>(config: {
+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;
@@ -1138,7 +1279,7 @@ type CreatePutRoute = <P = never, Q = never, B = never, R = never>(config: {
     };
     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>;
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
     middleware?: Middleware[];
     options?: Record<string, unknown>;
 }) => {
@@ -1146,30 +1287,28 @@ type CreatePutRoute = <P = never, Q = never, B = never, R = never>(config: {
     path: string;
 };
 /**
- * DELETE route creator - typically no body
- * FIXED: Default type parameters to never
+ * DELETE route creator with state and services support
  */
-type CreateDeleteRoute = <P = never, Q = never, R = never>(config: {
+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, [
+    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>;
+    ] 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, // DELETE never has body
-    R extends never ? never : R extends z.ZodType ? R : never>;
+    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 - includes body schema
- * FIXED: Default type parameters to never
+ * PATCH route creator with state and services support
  */
-type CreatePatchRoute = <P = never, Q = never, B = never, R = never>(config: {
+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;
@@ -1178,7 +1317,7 @@ type CreatePatchRoute = <P = never, Q = never, B = never, R = never>(config: {
     };
     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>;
+    ] extends [never] ? void : R extends z.ZodType ? Infer<R> : void, TState, TServices>;
     middleware?: Middleware[];
     options?: Record<string, unknown>;
 }) => {
@@ -1186,43 +1325,41 @@ type CreatePatchRoute = <P = never, Q = never, B = never, R = never>(config: {
     path: string;
 };
 /**
- * HEAD route creator - no body schema needed (same as GET)
- * FIXED: Default type parameters to never
+ * HEAD route creator with state and services support
  */
-type CreateHeadRoute = <P = never, Q = never, R = never>(config: {
+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, [
+    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>;
+    ] 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, // HEAD never has body
-    R extends never ? never : R extends z.ZodType ? R : never>;
+    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 - typically no body or response schema
- * FIXED: Default type parameters to never
+ * OPTIONS route creator with state and services support
  */
-type CreateOptionsRoute = <P = never, Q = never, R = never>(config: {
+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, [
+    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>;
+    ] 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, // OPTIONS never has body
-    R extends never ? never : R extends z.ZodType ? R : never>;
+    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;
 };
 
@@ -1234,214 +1371,466 @@ declare function compose(middlewareStack: Middleware[]): MiddlewareFunction;
 /**
  * Create a middleware
  */
-declare function create$2(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware;
-
+declare function create$2<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
+/**
+ * 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
+ *
+ */
+declare function stateMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<T, {}>;
 /**
- * BlaizeJS Server Module
+ * 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
  *
- * Provides the core HTTP/2 server implementation with HTTP/1.1 fallback.
  */
+declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
 
-interface Http2Options {
-    enabled?: boolean | undefined;
-    keyFile?: string | undefined;
-    certFile?: string | undefined;
-}
-interface StartOptions {
-    port?: number;
-    host?: string;
-}
-interface StopOptions {
-    timeout?: number;
-    plugins?: Plugin[];
-    onStopping?: () => Promise<void> | void;
-    onStopped?: () => Promise<void> | void;
-}
 /**
- * Server options for configuring the BlaizeJS server
+ * Represents a single Server-Sent Event
+ * @template T - The type of data payload
+ *
+ * @example
+ * ```typescript
+ * const event: SSEEvent<{ message: string }> = {
+ *   id: '123',
+ *   event: 'message',
+ *   data: { message: 'Hello, world!' },
+ *   retry: 5000
+ * };
+ * ```
  */
-interface ServerOptionsInput {
-    /** Port to listen on (default: 3000) */
-    port?: number;
-    /** Host to bind to (default: localhost) */
-    host?: string;
-    /** Directory containing route files (default: ./routes) */
-    routesDir?: string;
-    /** HTTP/2 options */
-    http2?: {
-        /** Enable HTTP/2 (default: true) */
-        enabled?: boolean | undefined;
-        /** Path to key file for HTTPS/HTTP2 */
-        keyFile?: string | undefined;
-        /** Path to certificate file for HTTPS/HTTP2 */
-        certFile?: string | undefined;
-    };
-    /** Global middleware to apply to all routes */
-    middleware?: Middleware[];
-    /** Plugins to register */
-    plugins?: Plugin[];
+interface SSEEvent<T = unknown> {
+    /** Unique identifier for the event */
+    id: string;
+    /** Event type/name for client-side event listeners */
+    event: string;
+    /** The actual data payload of the event */
+    data: T;
+    /** Optional retry interval in milliseconds for reconnection */
+    retry?: number;
 }
 /**
- * Configuration for a BlaizeJS server
+ * Backpressure handling strategies for SSE streams
+ *
+ * - `drop-oldest`: Remove oldest events from buffer when full
+ * - `drop-newest`: Reject new events when buffer is full
+ * - `close`: Close the stream when buffer limit is reached
  */
-interface ServerOptions {
-    /** Port to listen on (default: 3000) */
-    port: number;
-    /** Host to bind to (default: localhost) */
-    host: string;
-    /** Directory containing route files (default: ./routes) */
-    routesDir: string;
-    /** HTTP/2 options */
-    http2?: {
-        /** Enable HTTP/2 (default: true) */
-        enabled?: boolean | undefined;
-        /** Path to key file for HTTPS/HTTP2 */
-        keyFile?: string | undefined;
-        /** Path to certificate file for HTTPS/HTTP2 */
-        certFile?: string | undefined;
-    };
-    /** Global middleware to apply to all routes */
-    middleware?: Middleware[];
-    /** Plugins to register */
-    plugins?: Plugin[];
-}
+type SSEBufferStrategy = 'drop-oldest' | 'drop-newest' | 'close';
 /**
- * BlaizeJS Server instance
+ * Configuration options for SSE streams
+ *
+ * @example
+ * ```typescript
+ * const options: SSEOptions = {
+ *   autoClose: true,
+ *   maxBufferSize: 100,
+ *   bufferStrategy: 'drop-oldest'
+ * };
+ * ```
  */
-interface Server {
-    /** The underlying HTTP or HTTP/2 server */
-    server: http.Server | http2.Http2Server | undefined;
-    /** The port the server is configured to listen on */
-    port: number;
-    /** The host the server is bound to */
-    host: string;
-    events: EventEmitter;
-    /** Direct access to registered plugins */
-    plugins: Plugin[];
-    /** Direct access to registered plugins */
-    middleware: Middleware[];
-    /** Internal property for signal hanlders */
-    _signalHandlers?: {
-        unregister: () => void;
-    };
-    /** Start the server and listen for connections */
-    listen: (port?: number, host?: string) => Promise<Server>;
-    /** Stop the server */
-    close: (stopOptions?: StopOptions) => Promise<void>;
-    /** Add global middleware */
-    use: (middleware: Middleware | Middleware[]) => Server;
-    /** Register a plugin */
-    register: (plugin: Plugin) => Promise<Server>;
-    /** Access to the routing system */
-    router: Router;
-    /** Context storage system */
-    context: AsyncLocalStorage<Context>;
-    pluginManager: PluginLifecycleManager;
+interface SSEOptions {
+    /** ms between heartbeat pings (0 to disable) */
+    heartbeatInterval?: number;
+    /** Maximum size in bytes for a single event */
+    maxEventSize?: number;
+    /** Automatically close stream when client disconnects */
+    autoClose?: boolean;
+    /** Maximum number of events to buffer before applying strategy */
+    maxBufferSize?: number;
+    /** Strategy to handle buffer overflow conditions */
+    bufferStrategy?: SSEBufferStrategy;
 }
-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.
+ * Connection states for SSE streams
  */
-
+type SSEConnectionState = 'connecting' | 'connected' | 'disconnected' | 'closed';
 /**
- * Plugin options
+ * SSE stream interface for managing server-sent events
+ *
+ * @example
+ * ```typescript
+ * const stream: SSEStream = createSSEStream(response);
+ *
+ * // Send typed event
+ * stream.send('notification', { type: 'info', message: 'Update available' });
+ *
+ * // Send error event
+ * stream.sendError(new Error('Processing failed'));
+ *
+ * // Clean up on close
+ * stream.onClose(() => {
+ *   console.log('Client disconnected');
+ * });
+ *
+ * // Close stream
+ * stream.close();
+ * ```
  */
-interface PluginOptions<_T = any> {
-    /** Plugin configuration */
-    [key: string]: any;
+interface SSEStream {
+    /**
+     * Send an event with typed data to the client
+     * @template T - Type of the data payload
+     * @param event - Event name/type
+     * @param data - Event data payload
+     */
+    send<T>(event: string, data: T): void;
+    /**
+     * Send an error event to the client
+     * @param error - Error object to send
+     */
+    sendError(error: Error): void;
+    /**
+     * Close the SSE stream connection
+     */
+    close(): void;
+    /**
+     * Register a callback for stream closure
+     * @param cb - Callback function to execute on close
+     */
+    onClose(cb: () => void): void;
 }
 /**
- * Plugin lifecycle hooks
+ * Extended SSE stream with additional control methods
  */
-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>;
+interface SSEStreamExtended extends SSEStream {
+    readonly id: string;
+    [Symbol.asyncIterator](): AsyncGenerator<BufferedEvent, void, unknown>;
+    /** Current connection state */
+    readonly state: SSEConnectionState;
+    /** Number of events in the buffer */
+    readonly bufferSize: number;
+    /** Check if stream is writable */
+    readonly isWritable: boolean;
+    /**
+     * Ping the client to keep connection alive
+     * @param comment - Optional comment to include in ping
+     */
+    ping(comment?: string): void;
+    /**
+     * Set retry interval for client reconnection
+     * @param milliseconds - Retry interval in milliseconds
+     */
+    setRetry(milliseconds: number): void;
+    /**
+     * Flush any buffered events immediately
+     */
+    flush(): void;
+    getMetrics(): StreamMetrics;
 }
 /**
- * Plugin interface
+ * SSE event serialization format
  */
-interface Plugin extends PluginHooks {
-    /** Plugin name */
-    name: string;
-    /** Plugin version */
-    version: string;
+interface SSESerializedEvent {
+    /** Event ID field */
+    id?: string;
+    /** Event type field */
+    event?: string;
+    /** Data field (can be multi-line) */
+    data: string;
+    /** Retry field */
+    retry?: number;
+    /** Comment field for keep-alive */
+    comment?: string;
 }
 /**
- * Plugin factory function
+ * SSE event handler function type
+ * @template T - Type of the event data
  */
-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;
+type SSEEventHandler<T = unknown> = (event: SSEEvent<T>) => void | Promise<void>;
+/**
+ * SSE event listener registration
+ */
+interface SSEEventListener {
+    /** Event type to listen for (use '*' for all events) */
+    event: string;
+    /** Handler function for the event */
+    handler: SSEEventHandler;
+    /** Optional listener identifier for removal */
+    id?: string;
 }
-
 /**
- * Create a plugin with the given name, version, and setup function
+ * SSE metrics for monitoring stream performance
  */
-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 SSEMetrics {
+    /** Total number of events sent */
+    eventsSent: number;
+    /** Total number of events dropped */
+    eventsDropped: number;
+    /** Current number of connected clients */
+    activeConnections: number;
+    /** Total bytes sent */
+    bytesSent: number;
+    /** Average event send latency in milliseconds */
+    averageLatency: number;
+    /** Connection duration in milliseconds */
+    connectionDuration: number;
+}
 /**
- * Create a GET route
- * SIMPLER FIX: Just pass the config through, TypeScript will handle the types
+ * SSE stream manager for handling multiple clients
  */
-declare const createGetRoute: CreateGetRoute;
+interface SSEStreamManager {
+    /**
+     * Create a new SSE stream for a client
+     * @param clientId - Unique identifier for the client
+     * @param options - Stream configuration options
+     */
+    createStream(clientId: string, options?: SSEOptions): SSEStream;
+    /**
+     * Get an existing stream by client ID
+     * @param clientId - Client identifier
+     */
+    getStream(clientId: string): SSEStream | undefined;
+    /**
+     * Broadcast an event to all connected clients
+     * @template T - Type of the event data
+     * @param event - Event name
+     * @param data - Event data
+     */
+    broadcast<T>(event: string, data: T): void;
+    /**
+     * Broadcast to specific clients
+     * @template T - Type of the event data
+     * @param clientIds - Array of client IDs
+     * @param event - Event name
+     * @param data - Event data
+     */
+    multicast<T>(clientIds: string[], event: string, data: T): void;
+    /**
+     * Close a specific client stream
+     * @param clientId - Client identifier
+     */
+    closeStream(clientId: string): void;
+    /**
+     * Close all active streams
+     */
+    closeAll(): void;
+    /**
+     * Get metrics for all streams
+     */
+    getMetrics(): SSEMetrics;
+}
 /**
- * Create a POST route
+ * Result type for operations that can fail
  */
-declare const createPostRoute: CreatePostRoute;
+type RegistryResult<T> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: string;
+};
 /**
- * Create a PUT route
+ * Connection metadata stored in the registry
  */
-declare const createPutRoute: CreatePutRoute;
+interface ConnectionEntry {
+    stream: SSEStream;
+    connectedAt: number;
+    lastActivity: number;
+    clientIp?: string;
+    userAgent?: string;
+}
 /**
- * Create a DELETE route
+ * Internal connection registry interface
  */
-declare const createDeleteRoute: CreateDeleteRoute;
+interface ConnectionRegistry {
+    /** Add a new connection to the registry */
+    add: (id: string, stream: SSEStream, metadata?: {
+        clientIp?: string;
+        userAgent?: string;
+    }) => void;
+    /** Remove a connection from the registry */
+    remove: (id: string) => void;
+    /** Get current connection count */
+    count: () => number;
+    /** Clean up inactive or closed connections */
+    cleanup: () => void;
+    /** Get connection by ID (for internal use) */
+    get: (id: string) => SSEStream | undefined;
+    /** Check if a connection exists */
+    has: (id: string) => boolean;
+    /** Get all connection IDs */
+    getIds: () => string[];
+    /** Shutdown the registry and close all connections */
+    shutdown: () => void;
+}
 /**
- * Create a PATCH route
+ * Extended stream interface for typed events
  */
-declare const createPatchRoute: CreatePatchRoute;
+interface TypedSSEStream<TEvents extends Record<string, z.ZodType>> extends SSEStreamExtended {
+    send<K extends keyof TEvents>(event: K & string, data: z.infer<TEvents[K]>): void;
+}
 /**
- * Create a HEAD route (same signature as GET - no body)
+ * Schema for SSE route validation with generic type parameters
  */
-declare const createHeadRoute: CreateHeadRoute;
+interface SSERouteSchema<P extends z.ZodType = z.ZodType<any>, Q extends z.ZodType = z.ZodType<any>, E = any> {
+    /** Parameter schema for validation */
+    params?: P;
+    /** Query schema for validation */
+    query?: Q;
+    /** Events schema for validation (SSE-specific, replaces response) */
+    events?: E;
+}
 /**
- * Create an OPTIONS route (same signature as GET - no body)
+ * SSE route handler function with stream as first parameter
+ * This is the user-facing API - they write handlers with this signature
  */
-declare const createOptionsRoute: CreateOptionsRoute;
-
+type SSERouteHandler<TStream extends SSEStreamExtended = SSEStreamExtended, TParams = Record<string, string>, TQuery = Record<string, string | string[] | undefined>, TState extends State = State, TServices extends Services = Services> = (stream: TStream, ctx: Context<TState, TServices, never, TQuery>, // SSE never has body
+params: TParams) => Promise<void> | void;
 /**
- * Creates a BlaizeJS server instance
+ * SSE route creator with state and services support
+ * Returns a higher-order function to handle generics properly
+ *
+ * The return type matches what the implementation actually returns:
+ * - A route object with a GET property
+ * - The GET property contains the wrapped handler and schemas
+ * - The wrapped handler has the standard (ctx, params) signature expected by the router
  */
-declare function create(options?: ServerOptionsInput): Server;
-
-type ExtractMethod<T> = T extends {
-    GET: any;
-} ? 'GET' : T extends {
-    POST: any;
-} ? 'POST' : T extends {
-    PUT: any;
+type CreateSSERoute = <TState extends State = State, TServices extends Services = Services>() => <P = never, Q = never, E = never>(config: {
+    schema?: {
+        params?: P extends never ? never : P;
+        query?: Q extends never ? never : Q;
+        events?: E extends never ? never : E;
+    };
+    handler: SSERouteHandler<E extends Record<string, z.ZodType> ? TypedSSEStream<E> : SSEStreamExtended, P extends z.ZodType ? Infer<P> : Record<string, string>, Q extends z.ZodType ? Infer<Q> : QueryParams, TState, TServices>;
+    middleware?: Middleware[];
+    options?: Record<string, unknown>;
+}) => {
+    GET: {
+        handler: (ctx: any, params: any) => Promise<void>;
+        schema?: {
+            params?: P extends never ? undefined : P;
+            query?: Q extends never ? undefined : Q;
+        };
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    };
+    path: string;
+};
+/**
+ * Buffered event with metadata
+ */
+interface BufferedEvent {
+    id: string;
+    event: string;
+    data: unknown;
+    size: number;
+    timestamp: number;
+    correlationId: string;
+}
+/**
+ * Stream metrics for monitoring
+ */
+interface StreamMetrics {
+    eventsSent: number;
+    eventsDropped: number;
+    bytesWritten: number;
+    bufferHighWatermark: number;
+    lastEventTime: number;
+}
+
+/**
+ * SSE Client Types for BlaizeJS
+ * Location: packages/blaize-client/src/sse/types.ts
+ */
+
+/**
+ * Event handlers map
+ */
+interface EventHandlers {
+    [event: string]: Set<(data: any) => void>;
+}
+/**
+ * SSE connection configuration options
+ */
+interface SSEClientOptions {
+    headers?: Record<string, string>;
+    withCredentials?: boolean;
+    reconnect?: {
+        enabled: boolean;
+        maxAttempts?: number;
+        strategy?: ReconnectStrategy;
+        initialDelay?: number;
+    };
+    bufferMissedEvents?: boolean;
+    maxMissedEvents?: number;
+    heartbeatTimeout?: number;
+    parseJSON?: boolean;
+    /**
+     * Whether to wait for connection before resolving the promise.
+     * If false, returns the client immediately without waiting.
+     * Default: true
+     */
+    waitForConnection?: boolean;
+    /**
+     * Optional timeout for initial connection in milliseconds.
+     * If not set, no timeout is applied (relies on EventSource native timeout).
+     * Only applies if waitForConnection is true.
+     */
+    connectionTimeout?: number;
+}
+/**
+ * Metrics for SSE connection monitoring
+ */
+interface SSEClientMetrics {
+    eventsReceived: number;
+    bytesReceived: number;
+    connectionDuration: number;
+    reconnectAttempts: number;
+    lastEventId?: string;
+}
+/**
+ * Reconnection delay calculation strategy
+ */
+type ReconnectStrategy = (attempt: number) => number;
+/**
+ * SSE Client interface with type-safe event handling
+ */
+interface SSEClient<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+    on<K extends keyof TEvents>(event: K & string, handler: (data: TEvents[K]) => void): void;
+    on(event: 'error', handler: (error: BlaizeError) => void): void;
+    on(event: 'open', handler: () => void): void;
+    on(event: 'close', handler: (event: CloseEvent) => void): void;
+    off<K extends keyof TEvents>(event: K & string, handler?: (data: TEvents[K]) => void): void;
+    off(event: 'error', handler?: (error: BlaizeError) => void): void;
+    off(event: 'open', handler?: () => void): void;
+    off(event: 'close', handler?: (event: CloseEvent) => void): void;
+    once<K extends keyof TEvents>(event: K & string, handler: (data: TEvents[K]) => void): void;
+    once(event: 'error', handler: (error: BlaizeError) => void): void;
+    once(event: 'open', handler: () => void): void;
+    once(event: 'close', handler: (event: CloseEvent) => void): void;
+    close(): void;
+    readonly state: SSEConnectionState;
+    readonly metrics: SSEClientMetrics;
+    readonly lastEventId?: string;
+}
+/**
+ * Close event for SSE connections
+ */
+interface CloseEvent {
+    reconnect: boolean;
+    reason?: string;
+}
+/**
+ * Internal SSE connection factory
+ * Returns a Promise that resolves to an SSEClient instance
+ */
+type SSEConnectionFactory<TEvents extends Record<string, unknown> = Record<string, unknown>> = (options?: SSEClientOptions) => Promise<SSEClient<TEvents>>;
+
+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 {
@@ -1471,12 +1860,12 @@ type GetRouteMethodOptions<TRoute> = TRoute extends {
 } ? M : TRoute extends {
     OPTIONS: infer M;
 } ? M : never;
-type IsNever<T> = [T] extends [never] ? true : false;
-type BuildArgsObject<P, Q, B> = (IsNever<P> extends true ? {} : {
+type IsNever$1<T> = [T] extends [never] ? true : false;
+type BuildArgsObject<P, Q, B> = (IsNever$1<P> extends true ? {} : {
     params: Infer<P>;
-}) & (IsNever<Q> extends true ? {} : {
+}) & (IsNever$1<Q> extends true ? {} : {
     query: Infer<Q>;
-}) & (IsNever<B> extends true ? {} : {
+}) & (IsNever$1<B> extends true ? {} : {
     body: Infer<B>;
 });
 type IsEmptyObject<T> = keyof T extends never ? true : false;
@@ -1491,6 +1880,7 @@ interface ClientConfig {
     baseUrl: string;
     defaultHeaders?: Record<string, string>;
     timeout?: number;
+    sse?: SSEClientOptions;
 }
 interface InternalRequestArgs {
     params?: Record<string, any>;
@@ -1504,6 +1894,1049 @@ interface RequestOptions {
     body?: string;
     timeout: number;
 }
+/**
+ * Detect if a route has SSE support
+ * SSE routes have a special 'SSE' method key
+ */
+type HasSSEMethod<TRoute> = TRoute extends {
+    SSE: any;
+} ? true : false;
+/**
+ * Extract SSE event types from route schema
+ */
+type ExtractSSEEvents<TRoute> = TRoute extends {
+    SSE: {
+        events?: infer E;
+    };
+} ? E extends z.ZodType ? z.infer<E> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extract SSE query parameters from route
+ */
+type ExtractSSEQuery<TRoute> = TRoute extends {
+    SSE: {
+        schema?: {
+            query?: infer Q;
+        };
+    };
+} ? Q extends z.ZodType ? z.infer<Q> : Record<string, unknown> : never;
+/**
+ * Extract SSE params from route
+ */
+type ExtractSSEParams<TRoute> = TRoute extends {
+    SSE: {
+        schema?: {
+            params?: infer P;
+        };
+    };
+} ? P extends z.ZodType ? z.infer<P> : Record<string, string> : never;
+/**
+ * Build SSE method arguments
+ */
+type BuildSSEArgs<TRoute> = ExtractSSEParams<TRoute> extends never ? ExtractSSEQuery<TRoute> extends never ? {
+    options?: SSEClientOptions;
+} : {
+    query: ExtractSSEQuery<TRoute>;
+    options?: SSEClientOptions;
+} : ExtractSSEQuery<TRoute> extends never ? {
+    params: ExtractSSEParams<TRoute>;
+    options?: SSEClientOptions;
+} : {
+    params: ExtractSSEParams<TRoute>;
+    query: ExtractSSEQuery<TRoute>;
+    options?: SSEClientOptions;
+};
+/**
+ * Create SSE client method
+ */
+type CreateSSEMethod<TRoute> = HasSSEMethod<TRoute> extends true ? BuildSSEArgs<TRoute> extends {
+    options?: SSEClientOptions;
+} ? (args?: BuildSSEArgs<TRoute>) => Promise<SSEClient<ExtractSSEEvents<TRoute>>> : (args: BuildSSEArgs<TRoute>) => Promise<SSEClient<ExtractSSEEvents<TRoute>>> : never;
+/**
+ * Extract SSE routes from registry
+ */
+type ExtractSSERoutes<TRoutes extends Record<string, any>> = {
+    [K in keyof TRoutes as HasSSEMethod<TRoutes[K]> extends true ? K : never]: TRoutes[K];
+};
+/**
+ * Enhanced client with SSE support
+ */
+type CreateEnhancedClient<TRoutes extends Record<string, any>, TRegistry> = TRegistry & {
+    $sse: {
+        [K in keyof ExtractSSERoutes<TRoutes>]: CreateSSEMethod<TRoutes[K]>;
+    };
+};
+
+/**
+ * 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
+ */
+
+/**
+ * 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')
+ * ];
+ * ```
+ */
+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>)>;
+/**
+ * HTTP methods that can be allowed in CORS
+ * Based on W3C CORS specification
+ */
+type CorsHttpMethod = HttpMethod | 'CONNECT' | 'TRACE';
+/**
+ * Main CORS configuration options
+ *
+ * @example
+ * ```typescript
+ * const corsOptions: CorsOptions = {
+ *   origin: 'https://example.com',
+ *   methods: ['GET', 'POST'],
+ *   credentials: true,
+ *   maxAge: 86400
+ * };
+ * ```
+ */
+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;
+}
+/**
+ * Internal CORS validation result
+ * Used by middleware implementation
+ */
+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;
+}
+/**
+ * CORS preflight request information
+ * Extracted from OPTIONS request headers
+ */
+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[];
+}
+/**
+ * Cache entry for origin validation results
+ * Used for performance optimization
+ */
+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;
+}
+/**
+ * Configuration for CORS origin validation cache
+ */
+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;
+}
+/**
+ * Statistics for CORS middleware performance monitoring
+ */
+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
+ */
+interface CacheEntry {
+    allowed: boolean;
+    expiresAt: number;
+    lastAccessed: number;
+}
+/**
+ * Cache configuration
+ */
+interface CacheConfig {
+    ttl: number;
+    maxSize: number;
+}
+
+/**
+ * BlaizeJS Server Module - Enhanced with Correlation Configuration
+ *
+ * Provides the core HTTP/2 server implementation with HTTP/1.1 fallback
+ * and correlation ID tracking configuration.
+ */
+
+type UnknownServer = Server<Record<string, unknown>, Record<string, unknown>>;
+interface Http2Options {
+    enabled?: boolean | undefined;
+    keyFile?: string | undefined;
+    certFile?: string | undefined;
+}
+interface StartOptions {
+    port?: number;
+    host?: string;
+}
+interface StopOptions {
+    timeout?: number;
+    plugins?: Plugin[];
+    onStopping?: () => Promise<void> | void;
+    onStopped?: () => Promise<void> | void;
+}
+/**
+ * Correlation ID configuration options
+ */
+interface CorrelationOptions {
+    /**
+     * The HTTP header name to use for correlation IDs
+     * @default 'x-correlation-id'
+     */
+    headerName?: string;
+    /**
+     * Custom correlation ID generator function
+     * @default () => `req_${timestamp}_${random}`
+     */
+    generator?: () => string;
+}
+/**
+ * Server options for configuring the BlaizeJS server
+ */
+interface ServerOptionsInput {
+    /** Port to listen on (default: 3000) */
+    port?: number;
+    /** Host to bind to (default: localhost) */
+    host?: string;
+    /** Directory containing route files (default: ./routes) */
+    routesDir?: string;
+    /** HTTP/2 options */
+    http2?: {
+        /** Enable HTTP/2 (default: true) */
+        enabled?: boolean | undefined;
+        /** Path to key file for HTTPS/HTTP2 */
+        keyFile?: string | undefined;
+        /** Path to certificate file for HTTPS/HTTP2 */
+        certFile?: string | undefined;
+    };
+    /** Global middleware to apply to all routes */
+    middleware?: Middleware[];
+    /** Plugins to register */
+    plugins?: Plugin[];
+    /**
+     * Correlation ID configuration
+     * @since 0.4.0
+     */
+    correlation?: CorrelationOptions;
+    /**
+     * CORS configuration
+     *
+     * - `true`: Enable CORS with development defaults (allow all origins)
+     * - `false`: Disable CORS (no headers set)
+     * - `CorsOptions`: Custom CORS configuration
+     *
+     * @default false (CORS disabled)
+     * @since 0.5.0
+     *
+     * @example
+     * ```typescript
+     * // Enable with dev defaults
+     * const server = createServer({ cors: true });
+     *
+     * // Custom configuration
+     * const server = createServer({
+     *   cors: {
+     *     origin: 'https://example.com',
+     *     credentials: true,
+     *     maxAge: 86400
+     *   }
+     * });
+     *
+     * // Disable CORS
+     * const server = createServer({ cors: false });
+     * ```
+     */
+    cors?: CorsOptions | boolean;
+}
+/**
+ * Configuration for a BlaizeJS server
+ */
+interface ServerOptions {
+    /** Port to listen on (default: 3000) */
+    port: number;
+    /** Host to bind to (default: localhost) */
+    host: string;
+    /** Directory containing route files (default: ./routes) */
+    routesDir: string;
+    /** HTTP/2 options */
+    http2?: {
+        /** Enable HTTP/2 (default: true) */
+        enabled?: boolean | undefined;
+        /** Path to key file for HTTPS/HTTP2 */
+        keyFile?: string | undefined;
+        /** Path to certificate file for HTTPS/HTTP2 */
+        certFile?: string | undefined;
+    };
+    /** Global middleware to apply to all routes */
+    middleware?: Middleware[];
+    /** Plugins to register */
+    plugins?: Plugin[];
+    /**
+     * Correlation ID configuration
+     * @since 0.4.0
+     */
+    correlation?: CorrelationOptions;
+    /**
+     * CORS configuration
+     * @since 0.5.0
+     */
+    cors?: CorsOptions | boolean;
+}
+/**
+ * BlaizeJS Server instance with generic type accumulation
+ *
+ * @template TState - The accumulated state type from middleware
+ * @template TServices - The accumulated services type from middleware and plugins
+ *
+ */
+interface Server<TState, TServices> {
+    /** The underlying HTTP or HTTP/2 server */
+    server: http.Server | http2.Http2Server | undefined;
+    /** The port the server is configured to listen on */
+    port: number;
+    /** CORS configuration for this server */
+    corsOptions?: CorsOptions | boolean;
+    /** The host the server is bound to */
+    host: string;
+    events: EventEmitter;
+    /** Direct access to registered plugins */
+    plugins: Plugin[];
+    /** Direct access to registered plugins */
+    middleware: Middleware[];
+    /** Internal property for signal hanlders */
+    _signalHandlers?: {
+        unregister: () => void;
+    };
+    /** Start the server and listen for connections */
+    listen: (port?: number, host?: string) => Promise<Server<TState, TServices>>;
+    /** Stop the server */
+    close: (stopOptions?: StopOptions) => Promise<void>;
+    /**
+     * Add global middleware to the server
+     *
+     * @param middleware - Single middleware or array of middleware to add
+     * @returns New Server instance with accumulated types from the middleware
+     *
+     * @example
+     * ```typescript
+     * // Single middleware
+     * const serverWithAuth = server.use(authMiddleware);
+     * // serverWithAuth has type Server<{user: User}, {auth: AuthService}>
+     *
+     * // Array of middleware
+     * const serverWithMiddleware = server.use([authMiddleware, loggerMiddleware]);
+     * // serverWithMiddleware has type Server<{user, requestId}, {auth, logger}>
+     * ```
+     */
+    use<MS, MSvc>(middleware: Middleware<MS, MSvc>): Server<TState & MS, TServices & MSvc>;
+    use<MW extends readonly Middleware<any, any>[]>(middleware: MW): Server<TState & UnionToIntersection<ExtractMiddlewareState<MW[number]>>, TServices & UnionToIntersection<ExtractMiddlewareServices<MW[number]>>>;
+    /**
+     * Register a plugin with the server
+     *
+     * @param plugin - Single plugin or array of plugins to register
+     * @returns Promise resolving to new Server instance with accumulated types
+     *
+     * @example
+     * ```typescript
+     * // Single plugin
+     * const serverWithDb = await server.register(databasePlugin);
+     * // serverWithDb has type Server<{}, {db: DatabaseService}>
+     *
+     * // Array of plugins
+     * const serverWithPlugins = await server.register([dbPlugin, cachePlugin]);
+     * // serverWithPlugins has type Server<{}, {db, cache}>
+     * ```
+     */
+    register<PS, PSvc>(plugin: Plugin<PS, PSvc>): Promise<Server<TState & PS, TServices & PSvc>>;
+    register<P extends readonly Plugin<any, any>[]>(plugin: P): Promise<Server<TState & UnionToIntersection<ExtractPluginState<P[number]>>, TServices & UnionToIntersection<ExtractPluginServices<P[number]>>>>;
+    /** Access to the routing system */
+    router: Router;
+    /** Context storage system */
+    context: AsyncLocalStorage<Context>;
+    pluginManager: PluginLifecycleManager;
+}
+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<any, any>) => void | Promise<void>;
+    /** Called when the server is initialized */
+    initialize?: (app?: Server<any, any>) => void | Promise<void>;
+    /** Called when the server is terminated */
+    terminate?: (app?: Server<any, any>) => 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<TState = {}, TServices = {}> extends PluginHooks {
+    /** Plugin name */
+    name: string;
+    /** Plugin version */
+    version: string;
+    /**
+     * Type carriers for compile-time type information
+     * These are never used at runtime but allow TypeScript to track types
+     */
+    _state?: TState;
+    _services?: TServices;
+}
+/**
+ * Plugin factory function
+ */
+type PluginFactory<T = any, TState extends Record<string, unknown> = {}, TServices extends Record<string, unknown> = {}> = (options?: T) => Plugin<TState, TServices>;
+interface PluginLifecycleManager {
+    initializePlugins(server: Server<any, any>): Promise<void>;
+    terminatePlugins(server: Server<any, any>): Promise<void>;
+    onServerStart(server: Server<any, any>, httpServer: any): Promise<void>;
+    onServerStop(server: Server<any, any>, 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;
+}
+
+/**
+ * Type composition utilities for extracting and composing middleware type contributions
+ * @module composition
+ * @since v0.4.0
+ */
+
+/**
+ * Extracts the State type contribution from a middleware
+ * @template T - The middleware type to extract from
+ * @returns The state type if present, empty object otherwise
+ */
+type ExtractMiddlewareState<T> = T extends Middleware<infer S, any> ? S : {};
+/**
+ * Extracts the State type contribution from a plugin
+ * @template T - The plugin type to extract from
+ * @returns The state type if present, empty object otherwise
+ */
+type ExtractPluginState<T> = T extends Plugin<infer S, any> ? S : {};
+/**
+ * Extracts the Services type contribution from a middleware
+ * @template T - The middleware type to extract from
+ * @returns The services type if present, empty object otherwise
+ */
+type ExtractMiddlewareServices<T> = T extends Middleware<any, infer S> ? S : {};
+/**
+ * Extracts the Services type contribution from a plugin
+ * @template T - The plugin type to extract from
+ * @returns The services type if present, empty object otherwise
+ */
+type ExtractPluginServices<T> = T extends Plugin<any, infer S> ? S : {};
+/**
+ * Utility type to convert a union type to an intersection type
+ * This is the magic that allows us to compose multiple middleware contributions
+ *
+ * @example
+ * type U = { a: string } | { b: number }
+ * type I = UnionToIntersection<U> // { a: string } & { b: number }
+ *
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Composes state contributions from an array of middleware
+ * Merges all state types into a single intersection type
+ *
+ * @template T - ReadonlyArray of Middleware
+ * @returns Intersection of all state contributions
+ *
+ * @example
+ * const middlewares = [authMiddleware, loggerMiddleware] as const;
+ * type ComposedState = ComposeStates<typeof middlewares>;
+ * // Result: { user: User } & { requestId: string }
+ */
+type ComposeMiddlewareStates<T extends ReadonlyArray<Middleware>> = T extends readonly [] ? {} : UnionToIntersection<ExtractMiddlewareState<T[number]>>;
+/**
+ * Composes state contributions from an array of plugins
+ * Merges all state types into a single intersection type
+ *
+ * @template T - ReadonlyArray of Plugin
+ * @returns Intersection of all state contributions
+ *
+ * @example
+ * const plugins = [authPlugin, dbPlugin] as const;
+ * type ComposedState = ComposePluginStates<typeof plugins>;
+ * // Result: { config: AuthConfig } & { dbConnected: boolean }
+ */
+type ComposePluginStates<T extends ReadonlyArray<Plugin<any, any>>> = T extends readonly [] ? {} : UnionToIntersection<ExtractPluginState<T[number]>>;
+/**
+ * Composes service contributions from an array of middleware
+ * Merges all service types into a single intersection type
+ *
+ * @template T - ReadonlyArray of Middleware
+ * @returns Intersection of all service contributions
+ *
+ * @example
+ * const middlewares = [dbMiddleware, cacheMiddleware] as const;
+ * type ComposedServices = ComposeServices<typeof middlewares>;
+ * // Result: { db: Database } & { cache: Cache }
+ */
+type ComposeMiddlewareServices<T extends ReadonlyArray<Middleware>> = T extends readonly [] ? {} : UnionToIntersection<ExtractMiddlewareServices<T[number]>>;
+/**
+ * Composes service contributions from an array of plugins
+ * Merges all service types into a single intersection type
+ *
+ * @template T - ReadonlyArray of Plugin
+ * @returns Intersection of all service contributions
+ *
+ * @example
+ * const plugins = [dbPlugin, cachePlugin] as const;
+ * type ComposedServices = ComposePluginServices<typeof plugins>;
+ * // Result: { db: Database } & { cache: Cache }
+ */
+type ComposePluginServices<T extends ReadonlyArray<Plugin<any, any>>> = T extends readonly [] ? {} : UnionToIntersection<ExtractPluginServices<T[number]>>;
+/**
+ * Safe version of ExtractState that handles edge cases
+ * @template T - The middleware type to extract from
+ * @returns The state type, handling never/any/unknown gracefully
+ */
+type SafeExtractMiddlewareState<T> = IsNever<T> extends true ? {} : IsAny<T> extends true ? {} : T extends Middleware<infer S, any> ? unknown extends S ? {} : S : {};
+/**
+ * Safe version of ExtractPluginState that handles edge cases
+ * @template T - The plugin type to extract from
+ * @returns The state type, handling never/any/unknown gracefully
+ */
+type SafeExtractPluginState<T> = IsNever<T> extends true ? {} : IsAny<T> extends true ? {} : T extends Plugin<infer S, any> ? unknown extends S ? {} : S : {};
+/**
+ * Safe version of ExtractServices that handles edge cases
+ * @template T - The middleware type to extract from
+ * @returns The services type, handling never/any/unknown gracefully
+ */
+type SafeExtractMiddlewareServices<T> = IsNever<T> extends true ? {} : IsAny<T> extends true ? {} : T extends Middleware<any, infer S> ? unknown extends S ? {} : S : {};
+/**
+ * Safe version of ExtractPluginServices that handles edge cases
+ * @template T - The plugin type to extract from
+ * @returns The services type, handling never/any/unknown gracefully
+ */
+type SafeExtractPluginServices<T> = IsNever<T> extends true ? {} : IsAny<T> extends true ? {} : T extends Plugin<any, infer S> ? unknown extends S ? {} : S : {};
+/**
+ * Composes state with better edge case handling
+ * @template T - ReadonlyArray of Middleware
+ * @returns Safely composed state types
+ */
+type SafeComposeMiddlewareStates<T extends ReadonlyArray<Middleware>> = T extends readonly [] ? {} : T extends readonly [infer First, ...infer Rest] ? First extends Middleware ? Rest extends ReadonlyArray<Middleware> ? SafeExtractMiddlewareState<First> & SafeComposeMiddlewareStates<Rest> : SafeExtractMiddlewareState<First> : {} : UnionToIntersection<SafeExtractMiddlewareState<T[number]>>;
+/**
+ * Composes plugin state with better edge case handling
+ * @template T - ReadonlyArray of Plugin
+ * @returns Safely composed state types
+ */
+type SafeComposePluginStates<T extends ReadonlyArray<Plugin<any, any>>> = T extends readonly [] ? {} : T extends readonly [infer First, ...infer Rest] ? First extends Plugin<any, any> ? Rest extends ReadonlyArray<Plugin<any, any>> ? SafeExtractPluginState<First> & SafeComposePluginStates<Rest> : SafeExtractPluginState<First> : {} : UnionToIntersection<SafeExtractPluginState<T[number]>>;
+/**
+ * Composes services with better edge case handling
+ * @template T - ReadonlyArray of Middleware
+ * @returns Safely composed service types
+ */
+type SafeComposeMiddlewareServices<T extends ReadonlyArray<Middleware>> = T extends readonly [] ? {} : T extends readonly [infer First, ...infer Rest] ? First extends Middleware ? Rest extends ReadonlyArray<Middleware> ? SafeExtractMiddlewareServices<First> & SafeComposeMiddlewareServices<Rest> : SafeExtractMiddlewareServices<First> : {} : UnionToIntersection<SafeExtractMiddlewareServices<T[number]>>;
+/**
+ * Composes plugin services with better edge case handling
+ * @template T - ReadonlyArray of Plugin
+ * @returns Safely composed service types
+ */
+type SafeComposePluginServices<T extends ReadonlyArray<Plugin<any, any>>> = T extends readonly [] ? {} : T extends readonly [infer First, ...infer Rest] ? First extends Plugin<any, any> ? Rest extends ReadonlyArray<Plugin<any, any>> ? SafeExtractPluginServices<First> & SafeComposePluginServices<Rest> : SafeExtractPluginServices<First> : {} : UnionToIntersection<SafeExtractPluginServices<T[number]>>;
+/**
+ * Utility to merge two state types
+ * Handles conflicts by using the rightmost (latest) type
+ *
+ * @template A - First state type
+ * @template B - Second state type
+ * @returns Merged state with B taking precedence
+ */
+type MergeStates<A, B> = Omit<A, keyof B> & B;
+/**
+ * Utility to merge two service types
+ * Handles conflicts by using the rightmost (latest) type
+ *
+ * @template A - First services type
+ * @template B - Second services type
+ * @returns Merged services with B taking precedence
+ */
+type MergeServices<A, B> = Omit<A, keyof B> & B;
+/**
+ * Extract both state and services from a middleware at once
+ * @template T - The middleware type
+ * @returns Object with state and services types
+ */
+type ExtractMiddlewareTypes<T> = {
+    state: ExtractMiddlewareState<T>;
+    services: ExtractMiddlewareServices<T>;
+};
+/**
+ * Extract both state and services from a plugin at once
+ * @template T - The plugin type
+ * @returns Object with state and services types
+ */
+type ExtractPluginTypes<T> = {
+    state: ExtractPluginState<T>;
+    services: ExtractPluginServices<T>;
+};
+/**
+ * Compose both state and services from middleware array at once
+ * @template T - ReadonlyArray of Middleware
+ * @returns Object with composed state and services
+ */
+type ComposeMiddlewareTypes<T extends ReadonlyArray<Middleware>> = {
+    state: ComposeMiddlewareStates<T>;
+    services: ComposeMiddlewareServices<T>;
+};
+/**
+ * Compose both state and services from plugin array at once
+ * @template T - ReadonlyArray of Plugin
+ * @returns Object with composed state and services
+ */
+type ComposePluginTypes<T extends ReadonlyArray<Plugin<any, any>>> = {
+    state: ComposePluginStates<T>;
+    services: ComposePluginServices<T>;
+};
+/**
+ * Type guard to check if a value is a Middleware
+ * @param value - Value to check
+ * @returns True if value is a Middleware
+ */
+declare function isMiddleware(value: unknown): value is Middleware;
+/**
+ * Type guard to check if a value is a Plugin
+ * @param value - Value to check
+ * @returns True if value is a Plugin
+ */
+declare function isPlugin(value: unknown): value is Plugin;
+/**
+ * Type helper for middleware arrays
+ * Ensures proper readonly array typing for composition
+ *
+ * @example
+ * const middlewares = asMiddlewareArray([auth, logger, cache]);
+ * type State = ComposeStates<typeof middlewares>;
+ */
+declare function asMiddlewareArray<T extends ReadonlyArray<Middleware>>(middlewares: T): T;
+/**
+ * Type helper for plugin arrays
+ * Ensures proper readonly array typing for composition
+ *
+ * @example
+ * const plugins = asPluginArray([dbPlugin, cachePlugin]);
+ * type Services = ComposePluginServices<typeof plugins>;
+ */
+declare function asPluginArray<T extends ReadonlyArray<Plugin<any, any>>>(plugins: T): T;
+/**
+ * Create a typed middleware array with inferred types
+ * Useful for getting proper const assertions
+ *
+ * @example
+ * const middlewares = createMiddlewareArray(auth, logger, cache);
+ * type State = ComposeStates<typeof middlewares>;
+ */
+declare function createMiddlewareArray<T extends ReadonlyArray<Middleware>>(...middlewares: T): T;
+/**
+ * Create a typed plugin array with inferred types
+ * Useful for getting proper const assertions
+ *
+ * @example
+ * const plugins = createPluginArray(dbPlugin, cachePlugin);
+ * type Services = ComposePluginServices<typeof plugins>;
+ */
+declare function createPluginArray<T extends ReadonlyArray<Plugin<any, any>>>(...plugins: T): T;
+
+/**
+ * Create a plugin with the given name, version, and setup function
+ */
+declare function create$1<T = any>(name: string, version: string, setup: (app: UnknownServer, options: T) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<T>): PluginFactory<T>;
+
+/**
+ * Create a GET route
+ * SIMPLER FIX: Just pass the config through, TypeScript will handle the types
+ */
+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;
+/**
+ * Factory that creates all route methods with consistent types
+ * This is the RECOMMENDED approach for most applications
+ *
+ * Usage in server.ts:
+ * ```typescript
+ * export const route = createRouteFactory<AppState, AppServices>();
+ * ```
+ *
+ * Usage in route files:
+ * ```typescript
+ * import { route } from '../server';
+ *
+ * export const GET = route.get({
+ *   handler: async (ctx) => {
+ *     // ctx.state and ctx.services are fully typed!
+ *   }
+ * });
+ * ```
+ */
+declare function createRouteFactory<TState extends State = State, TServices extends Services = Services>(): {
+    readonly get: <P = never, Q = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, never, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        GET: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly post: <P = never, Q = never, B = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            body?: (B extends never ? never : B) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, B extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<B> : unknown, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        POST: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, B extends never ? never : B extends zod.ZodType<any, zod.ZodTypeDef, any> ? B : never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly put: <P = never, Q = never, B = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            body?: (B extends never ? never : B) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, B extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<B> : unknown, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        PUT: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, B extends never ? never : B extends zod.ZodType<any, zod.ZodTypeDef, any> ? B : never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly delete: <P = never, Q = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, never, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        DELETE: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly patch: <P = never, Q = never, B = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            body?: (B extends never ? never : B) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, B extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<B> : unknown, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        PATCH: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, B extends never ? never : B extends zod.ZodType<any, zod.ZodTypeDef, any> ? B : never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly head: <P = never, Q = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, never, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        HEAD: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly options: <P = never, Q = never, R = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            response?: (R extends never ? never : R) | undefined;
+        } | undefined;
+        handler: RouteHandler<P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, never, [R] extends [never] ? void : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<R> : void, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        OPTIONS: RouteMethodOptions<P extends never ? never : P extends zod.ZodType<any, zod.ZodTypeDef, any> ? P : never, Q extends never ? never : Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Q : never, never, R extends never ? never : R extends zod.ZodType<any, zod.ZodTypeDef, any> ? R : never, zod.ZodType<any, zod.ZodTypeDef, any>>;
+        path: string;
+    };
+    readonly sse: <P = never, Q = never, E = never>(config: {
+        schema?: {
+            params?: (P extends never ? never : P) | undefined;
+            query?: (Q extends never ? never : Q) | undefined;
+            events?: (E extends never ? never : E) | undefined;
+        } | undefined;
+        handler: SSERouteHandler<E extends Record<string, zod.ZodType<any, zod.ZodTypeDef, any>> ? TypedSSEStream<E> : SSEStreamExtended, P extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<P> : Record<string, string>, Q extends zod.ZodType<any, zod.ZodTypeDef, any> ? Infer<Q> : QueryParams, TState, TServices>;
+        middleware?: Middleware[];
+        options?: Record<string, unknown>;
+    }) => {
+        GET: {
+            handler: (ctx: any, params: any) => Promise<void>;
+            schema?: {
+                params?: (P extends never ? undefined : P) | undefined;
+                query?: (Q extends never ? undefined : Q) | undefined;
+            } | undefined;
+            middleware?: Middleware[];
+            options?: Record<string, unknown>;
+        };
+        path: string;
+    };
+};
+
+/**
+ * Creates a BlaizeJS server instance
+ */
+declare function create<const TMw extends readonly Middleware<any, any>[] = [], const TP extends readonly Plugin<any, any>[] = []>(options?: ServerOptionsInput & {
+    middleware?: TMw;
+    plugins?: TP;
+}): Server<ComposeMiddlewareStates<TMw> & ComposePluginStates<TP>, ComposeMiddlewareServices<TMw> & ComposePluginServices<TP>>;
+
+/**
+ * Type inference utilities for BlaizeJS
+ * Minimal set of utilities needed for type-safe routing
+ */
+
+/**
+ * Infers the context type from a server instance
+ *
+ * @example
+ * ```typescript
+ * const server = createServer().use(authMiddleware);
+ * type AppContext = InferContext<typeof server>;
+ * ```
+ */
+type InferContext<T> = T extends Server<infer TState, infer TServices> ? TState extends State ? TServices extends Services ? Context<TState, TServices, any, any> : Context<State, Services, any, any> : Context<State, Services, any, any> : Context<State, Services, any, any>;
+/**
+ * Runtime helper that provides type hints for development
+ * Returns an empty object but gives TypeScript the correct context type
+ *
+ * @param _server - The server instance (not used at runtime)
+ * @returns An empty object typed as the server's context
+ */
+declare function inferContext<TState extends State, TServices extends Services>(_server: Server<TState, TServices>): InferContext<Server<TState, TServices>>;
+
+/**
+ * Gets the current correlation ID from AsyncLocalStorage
+ *
+ * @returns The current correlation ID, or 'unknown' if none is set
+ */
+declare function getCorrelationId(): string;
 
 /**
  * ValidationError class for request validation failures
@@ -1822,6 +3255,7 @@ declare class UnprocessableEntityError extends BlaizeError {
 declare const VERSION = "0.1.0";
 declare const ServerAPI: {
     createServer: typeof create;
+    inferContext: typeof inferContext;
 };
 declare const RouterAPI: {
     createDeleteRoute: CreateDeleteRoute;
@@ -1831,9 +3265,12 @@ declare const RouterAPI: {
     createPatchRoute: CreatePatchRoute;
     createPostRoute: CreatePostRoute;
     createPutRoute: CreatePutRoute;
+    createRouteFactory: typeof createRouteFactory;
 };
 declare const MiddlewareAPI: {
     createMiddleware: typeof create$2;
+    createServiceMiddleware: typeof serviceMiddleware;
+    createStateMiddleware: typeof stateMiddleware;
     compose: typeof compose;
 };
 declare const PluginsAPI: {
@@ -1843,9 +3280,13 @@ declare const PluginsAPI: {
 declare const Blaize: {
     createServer: typeof create;
     createMiddleware: typeof create$2;
+    createServiceMiddleware: typeof serviceMiddleware;
+    createStateMiddleware: typeof stateMiddleware;
     createPlugin: typeof create$1;
+    getCorrelationId: typeof getCorrelationId;
     Server: {
         createServer: typeof create;
+        inferContext: typeof inferContext;
     };
     Router: {
         createDeleteRoute: CreateDeleteRoute;
@@ -1855,9 +3296,12 @@ declare const Blaize: {
         createPatchRoute: CreatePatchRoute;
         createPostRoute: CreatePostRoute;
         createPutRoute: CreatePutRoute;
+        createRouteFactory: typeof createRouteFactory;
     };
     Middleware: {
         createMiddleware: typeof create$2;
+        createServiceMiddleware: typeof serviceMiddleware;
+        createStateMiddleware: typeof stateMiddleware;
         compose: typeof compose;
     };
     Plugins: {
@@ -1866,4 +3310,4 @@ declare const Blaize: {
     VERSION: string;
 };
 
-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 ExtractMethod, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type Http2Options, type HttpMethod, type Infer, type InternalRequestArgs, 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, 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 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 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, UnprocessableEntityError, UnsupportedMediaTypeError, 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, isBodyParseError };
+export { Blaize, BlaizeError, type BlaizeErrorResponse, 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 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, compose, createDeleteRoute, createGetRoute, createHeadRoute, create$2 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, getCorrelationId, inferContext, isBodyParseError, isMiddleware, isPlugin };