blaizejs 0.3.4 → 0.4.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';
@@ -706,9 +707,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 +753,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 +774,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 +795,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 +818,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 +850,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 +897,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 +1112,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 +1143,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 +1151,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 +1162,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 +1170,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 +1200,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 +1208,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,14 +1254,105 @@ 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, {}>;
+/**
+ * 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
+ *
+ */
+declare function serviceMiddleware<T = {}>(handler: MiddlewareFunction): Middleware<{}, T>;
+
+type ExtractMethod<T> = T extends {
+    GET: any;
+} ? 'GET' : T extends {
+    POST: any;
+} ? 'POST' : T extends {
+    PUT: any;
+} ? 'PUT' : T extends {
+    DELETE: any;
+} ? 'DELETE' : T extends {
+    PATCH: any;
+} ? 'PATCH' : T extends {
+    HEAD: any;
+} ? 'HEAD' : T extends {
+    OPTIONS: any;
+} ? 'OPTIONS' : never;
+type BuildRoutesRegistry<TRoutes extends Record<string, any>> = {
+    [Method in ExtractMethod<TRoutes[keyof TRoutes]> as `$${Lowercase<Method>}`]: {
+        [K in keyof TRoutes as ExtractMethod<TRoutes[K]> extends Method ? K : never]: TRoutes[K];
+    };
+};
+type GetRouteMethodOptions<TRoute> = TRoute extends {
+    GET: infer M;
+} ? M : TRoute extends {
+    POST: infer M;
+} ? M : TRoute extends {
+    PUT: infer M;
+} ? M : TRoute extends {
+    DELETE: infer M;
+} ? M : TRoute extends {
+    PATCH: infer M;
+} ? M : TRoute extends {
+    HEAD: infer M;
+} ? M : TRoute extends {
+    OPTIONS: infer M;
+} ? M : never;
+type IsNever$1<T> = [T] extends [never] ? true : false;
+type BuildArgsObject<P, Q, B> = (IsNever$1<P> extends true ? {} : {
+    params: Infer<P>;
+}) & (IsNever$1<Q> extends true ? {} : {
+    query: Infer<Q>;
+}) & (IsNever$1<B> extends true ? {} : {
+    body: Infer<B>;
+});
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+type BuildArgs<P, Q, B> = IsEmptyObject<BuildArgsObject<P, Q, B>> extends true ? void : BuildArgsObject<P, Q, B>;
+type CreateClientMethod<TRoute> = GetRouteMethodOptions<TRoute> extends RouteMethodOptions<infer P, infer Q, infer B, infer R> ? BuildArgs<P, Q, B> extends void ? () => Promise<R extends z.ZodType ? Infer<R> : unknown> : (args: BuildArgs<P, Q, B>) => Promise<R extends z.ZodType ? Infer<R> : unknown> : never;
+type CreateClient<TRoutes extends Record<string, Record<string, any>>> = {
+    [Method in keyof TRoutes]: {
+        [RouteName in keyof TRoutes[Method]]: CreateClientMethod<TRoutes[Method][RouteName]>;
+    };
+};
+interface ClientConfig {
+    baseUrl: string;
+    defaultHeaders?: Record<string, string>;
+    timeout?: number;
+}
+interface InternalRequestArgs {
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+    body?: any;
+}
+interface RequestOptions {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeout: number;
+}
 
 /**
- * BlaizeJS Server Module
+ * BlaizeJS Server Module - Enhanced with Correlation Configuration
  *
- * Provides the core HTTP/2 server implementation with HTTP/1.1 fallback.
+ * 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;
@@ -1257,6 +1368,21 @@ interface StopOptions {
     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
  */
@@ -1280,6 +1406,11 @@ interface ServerOptionsInput {
     middleware?: Middleware[];
     /** Plugins to register */
     plugins?: Plugin[];
+    /**
+     * Correlation ID configuration
+     * @since 0.4.0
+     */
+    correlation?: CorrelationOptions;
 }
 /**
  * Configuration for a BlaizeJS server
@@ -1304,11 +1435,20 @@ interface ServerOptions {
     middleware?: Middleware[];
     /** Plugins to register */
     plugins?: Plugin[];
+    /**
+     * Correlation ID configuration
+     * @since 0.4.0
+     */
+    correlation?: CorrelationOptions;
 }
 /**
- * BlaizeJS Server instance
+ * 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 {
+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 */
@@ -1325,13 +1465,47 @@ interface Server {
         unregister: () => void;
     };
     /** Start the server and listen for connections */
-    listen: (port?: number, host?: string) => Promise<Server>;
+    listen: (port?: number, host?: string) => Promise<Server<TState, TServices>>;
     /** Stop the server */
     close: (stopOptions?: StopOptions) => Promise<void>;
-    /** Add global middleware */
-    use: (middleware: Middleware | Middleware[]) => Server;
-    /** Register a plugin */
-    register: (plugin: Plugin) => Promise<Server>;
+    /**
+     * 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 */
@@ -1358,11 +1532,11 @@ interface PluginOptions<_T = any> {
  */
 interface PluginHooks {
     /** Called when the plugin is registered */
-    register: (app: Server) => void | Promise<void>;
+    register: (app: Server<any, any>) => void | Promise<void>;
     /** Called when the server is initialized */
-    initialize?: (app?: Server) => void | Promise<void>;
+    initialize?: (app?: Server<any, any>) => void | Promise<void>;
     /** Called when the server is terminated */
-    terminate?: (app?: Server) => void | Promise<void>;
+    terminate?: (app?: Server<any, any>) => void | Promise<void>;
     /** Called when the server starts */
     onServerStart?: (server: any) => void | Promise<void>;
     /** Called when the server stops */
@@ -1371,21 +1545,27 @@ interface PluginHooks {
 /**
  * Plugin interface
  */
-interface Plugin extends PluginHooks {
+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> = (options?: T) => Plugin;
+type PluginFactory<T = any, TState extends Record<string, unknown> = {}, TServices extends Record<string, unknown> = {}> = (options?: T) => Plugin<TState, TServices>;
 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>;
+    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 */
@@ -1396,10 +1576,253 @@ interface PluginLifecycleOptions {
     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: Server, options: T) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<T>): PluginFactory<T>;
+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
@@ -1430,80 +1853,161 @@ declare const createHeadRoute: CreateHeadRoute;
  * Create an OPTIONS route (same signature as GET - no body)
  */
 declare const createOptionsRoute: CreateOptionsRoute;
-
 /**
- * Creates a BlaizeJS server instance
+ * 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 create(options?: ServerOptionsInput): Server;
-
-type ExtractMethod<T> = T extends {
-    GET: any;
-} ? 'GET' : T extends {
-    POST: any;
-} ? 'POST' : T extends {
-    PUT: any;
-} ? 'PUT' : T extends {
-    DELETE: any;
-} ? 'DELETE' : T extends {
-    PATCH: any;
-} ? 'PATCH' : T extends {
-    HEAD: any;
-} ? 'HEAD' : T extends {
-    OPTIONS: any;
-} ? 'OPTIONS' : never;
-type BuildRoutesRegistry<TRoutes extends Record<string, any>> = {
-    [Method in ExtractMethod<TRoutes[keyof TRoutes]> as `$${Lowercase<Method>}`]: {
-        [K in keyof TRoutes as ExtractMethod<TRoutes[K]> extends Method ? K : never]: TRoutes[K];
+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;
     };
-};
-type GetRouteMethodOptions<TRoute> = TRoute extends {
-    GET: infer M;
-} ? M : TRoute extends {
-    POST: infer M;
-} ? M : TRoute extends {
-    PUT: infer M;
-} ? M : TRoute extends {
-    DELETE: infer M;
-} ? M : TRoute extends {
-    PATCH: infer M;
-} ? M : TRoute extends {
-    HEAD: infer M;
-} ? 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 ? {} : {
-    params: Infer<P>;
-}) & (IsNever<Q> extends true ? {} : {
-    query: Infer<Q>;
-}) & (IsNever<B> extends true ? {} : {
-    body: Infer<B>;
-});
-type IsEmptyObject<T> = keyof T extends never ? true : false;
-type BuildArgs<P, Q, B> = IsEmptyObject<BuildArgsObject<P, Q, B>> extends true ? void : BuildArgsObject<P, Q, B>;
-type CreateClientMethod<TRoute> = GetRouteMethodOptions<TRoute> extends RouteMethodOptions<infer P, infer Q, infer B, infer R> ? BuildArgs<P, Q, B> extends void ? () => Promise<R extends z.ZodType ? Infer<R> : unknown> : (args: BuildArgs<P, Q, B>) => Promise<R extends z.ZodType ? Infer<R> : unknown> : never;
-type CreateClient<TRoutes extends Record<string, Record<string, any>>> = {
-    [Method in keyof TRoutes]: {
-        [RouteName in keyof TRoutes[Method]]: CreateClientMethod<TRoutes[Method][RouteName]>;
+    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;
     };
 };
-interface ClientConfig {
-    baseUrl: string;
-    defaultHeaders?: Record<string, string>;
-    timeout?: number;
-}
-interface InternalRequestArgs {
-    params?: Record<string, any>;
-    query?: Record<string, any>;
-    body?: any;
-}
-interface RequestOptions {
-    method: string;
-    url: string;
-    headers: Record<string, string>;
-    body?: string;
-    timeout: number;
-}
+
+/**
+ * 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 +2326,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 +2336,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 +2351,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 +2367,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 +2381,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 BuildRoutesRegistry, type ClientConfig, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, 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 ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, 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 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 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 StreamOptions, type TimeoutErrorContext, 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 };