balda 0.0.53 → 0.0.55

package/lib/index.d.cts

@@ -54,6 +54,10 @@ interface ValidationOptions {
      * The schema to validate the query parameters against (Zod, TypeBox, or plain JSON schema)
      */
     query?: RequestSchema;
+    /**
+     * The schema to validate the request headers against (Zod, TypeBox, or plain JSON schema)
+     */
+    headers?: RequestSchema;
     /**
      * The schema to validate both body and query against (Zod, TypeBox, or plain JSON schema)
      */
@@ -93,6 +97,12 @@ type InferBodyType<T> = T extends RequestSchema ? ValidatedData<T> : unknown;
  * Infers the typed query from a schema. Returns `Record<string, string>` if no schema is provided.
  */
 type InferQueryType<T> = T extends RequestSchema ? ValidatedData<T> : Record<string, string>;
+/**
+ * Infers the typed headers from a schema.
+ * Returns `Record<string, string | string[]>` if no schema is provided
+ * (supporting multi-value headers).
+ */
+type InferHeadersType<T> = T extends RequestSchema ? ValidatedData<T> : Record<string, string | string[]>;
 /**
  * Extracts the body type for a specific HTTP status code from a response map.
  * When the status code has a schema defined, enforces type matching with widened
@@ -180,8 +190,9 @@ type FilePluginOptions = {
  * @template Params - The path parameters type (automatically extracted from route)
  * @template TBody - The typed body (inferred from body schema when provided)
  * @template TQuery - The typed query (inferred from query schema when provided)
+ * @template THeaders - The typed headers (inferred from headers schema when provided)
  */
-declare class Request<Params extends Record<string, string> = any, TBody = unknown, TQuery extends Record<string, any> = Record<string, string>> {
+declare class Request<Params extends Record<string, string> = Record<string, string>, TBody = unknown, TQuery extends Record<string, any> = Record<string, string>, THeaders extends Record<string, any> = Record<string, string | string[]>> {
     #private;
     /**
      * Creates a new request object from a Web API Request object.
@@ -228,10 +239,17 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      */
     method: string;
     /**
-     * The headers of the request — lazily constructed from raw Node.js headers.
+     * Raw Headers API object for low-level access.
+     * Use this for case-insensitive lookups, iteration, etc.
      */
-    get headers(): globalThis.Headers;
-    set headers(value: globalThis.Headers);
+    get rawHeaders(): globalThis.Headers;
+    /**
+     * The typed headers of the request.
+     * After validation with a headers schema, this contains the validated/typed header values.
+     * For raw Headers API access, use `rawHeaders`.
+     */
+    get headers(): THeaders;
+    set headers(value: THeaders);
     /**
      * The signal for aborting the request
      */
@@ -449,6 +467,12 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @param throwErrorOnValidationFail - If true, throws ValidationError on validation failure. If false, returns the original data.
      */
     validateAll<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
+    /**
+     * Validates the headers of the request.
+     * @param inputSchema - The schema to validate the headers against (Zod schema, TypeBox, or JSON Schema).
+     * @param throwErrorOnValidationFail - If true, throws ValidationError on validation failure. If false, returns the original headers.
+     */
+    validateHeaders<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
     /**
      * Sets a lazy IP extractor function.
      * IP will only be extracted when `.ip` is first accessed.
@@ -850,9 +874,11 @@ type HTMLString = string;
  */
 type CustomUIGenerator = (specUrl: string, globalOptions: SwaggerGlobalOptions) => HTMLString;
 /**
- * Type of request body for a route
+ * Type of request body for a route.
+ * Common MIME types are provided as literals withintellisense,
+ * custom MIME types can be specified as strings.
  */
-type SwaggerBodyType = "json" | "form-data" | "urlencoded";
+type SwaggerBodyType = "json" | "form-data" | "urlencoded" | "binary" | "text" | "event-stream" | (string & {});
 /**
  * JSONSchema type for OpenAPI/AJV-compatible schemas
  */
@@ -939,17 +965,24 @@ type SwaggerGlobalOptions = (SwaggerGlobalOptionsBase & {
     customUIGenerator: CustomUIGenerator;
 });
 /**
- * Route-specific documentation options (for individual endpoints)
+ * Route-specific documentation options for OpenAPI/Swagger generation.
+ *
+ * These options are for DOCUMENTATION PURPOSES ONLY and are NOT validated or enforced at runtime.
+ * For validated schemas, use the route-level `body`, `query`, and `responses` options.
+ *
+ * @example
+ * // Document route with custom body type
+ * router.get("/download", { swagger: { bodyType: "binary" } }, handler);
+ *
+ * @example
+ * // Document authentication requirements
+ * router.get("/protected", { swagger: { security: { type: "bearer" } } }, handler);
  */
 type SwaggerRouteOptions = {
     /** Service category where the route belongs to */
     service?: string;
     /** Name of the route */
     name?: string;
-    /** Responses for this route (used by decorators) */
-    responses?: Record<number, RequestSchema>;
-    /** Errors for this route */
-    errors?: Record<number, RequestSchema>;
     /** Security requirements for this route */
     security?: Security[] | Security;
     /** Description of the route */
@@ -959,7 +992,10 @@ type SwaggerRouteOptions = {
     /** Exclude from swagger */
     excludeFromSwagger?: boolean;
     /**
-     * The request body type for this route. Allowed values: 'json', 'form-data', 'urlencoded'. Defaults to 'json'.
+     * The request body type for documentation purposes.
+     * Common types: 'json', 'form-data', 'urlencoded', 'binary', 'text', 'event-stream'.
+     * Custom MIME types can be specified as strings (e.g., 'application/vnd.api+json').
+     * Defaults to 'json'.
      */
     bodyType?: SwaggerBodyType;
 };
@@ -1021,6 +1057,7 @@ type OpenIdConnectOptions = {
 /**
  * Decorator to mark a class as a controller, routes defined in the controller will be registered at import time when calling the `listen` method.
  * You can customize the path pattern for controller imports in the server options `controllerPatterns`
+ * @deprecated This decorator is deprecated and class based controllers won't be supported in the future. Please use the `router` directly to define your routes in a functional way for better type-safety.
  * @param path - The path pattern for the controller.
  * @param swaggerOptions - The swagger options for the controller that will be applied to all routes defined in the controller. Controller options will override route options.
  * @swagger If swagger is enabled, the default service name for all routes defined in the controller will be the controller name.
@@ -1672,20 +1709,20 @@ type InferMiddlewareExtensions<T extends readonly any[]> = T extends readonly [i
  * ```
  */
 interface GroupRouter<TGroupExt extends Record<string, any> = Record<string, never>> {
-    get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
     group<const TMiddlewares extends readonly (ServerRouteMiddleware | TypedMiddleware<any>)[] = readonly (ServerRouteMiddleware | TypedMiddleware<any>)[]>(path: string, middleware: TMiddlewares, cb: (router: GroupRouter<TGroupExt & InferMiddlewareExtensions<TMiddlewares>>) => void): void;
     group(path: string, cb: (router: GroupRouter<TGroupExt>) => void): void;
 }
@@ -1717,6 +1754,7 @@ declare class Router {
     addOrUpdate(method: HttpMethod, path: string, middleware: (ServerRouteMiddleware | TypedMiddleware<any>)[], handler: ServerRouteHandler, validationSchemas?: {
         body?: RequestSchema;
         query?: RequestSchema;
+        headers?: RequestSchema;
         all?: RequestSchema;
     }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>, allowUpdate?: boolean): void;
     /**
@@ -1740,37 +1778,37 @@ declare class Router {
      * Register a GET route under this router's base path with type-safe path parameters.
      */
     get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a POST route under this router's base path with type-safe path parameters.
      */
     post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a PATCH route under this router's base path with type-safe path parameters.
      */
     patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a PUT route under this router's base path with type-safe path parameters.
      */
     put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a DELETE route under this router's base path with type-safe path parameters.
      */
     delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register an OPTIONS route under this router's base path with type-safe path parameters.
      */
     options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register an HEAD route under this router's base path with type-safe path parameters.
      */
     head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Create a grouped router that shares a base path and middlewares.
      * The callback receives a typed child router where routes are defined; routes
@@ -1817,12 +1855,13 @@ interface Route {
      */
     responseSchemas?: RouteResponseSchemas;
     /**
-     * Validation schemas for request body, query parameters, or both.
+     * Validation schemas for request body, query parameters, headers, or all.
      * When provided, the handler will receive validated data as additional parameters.
      */
     validationSchemas?: {
         body?: RequestSchema;
         query?: RequestSchema;
+        headers?: RequestSchema;
         all?: RequestSchema;
     };
 }
@@ -2779,10 +2818,11 @@ interface ServerInterface {
      */
     exit: (code?: number) => void;
 }
-type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string, TAll extends RequestSchema | unknown = unknown, TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]> = {
+type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, THeaders extends RequestSchema | unknown = unknown, TPath extends string = string, TAll extends RequestSchema | unknown = unknown, TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]> = {
     middlewares?: TMiddlewares | TypedMiddleware<any>;
     body?: TBody;
     query?: TQuery;
+    headers?: THeaders;
     all?: TAll;
     responses?: TResponses;
     swagger?: SwaggerRouteOptions;
@@ -2793,7 +2833,7 @@ type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Re
 };
 type ServerHook = () => SyncOrAsync;
 type SignalEvent = Deno.Signal | NodeJS.Signals;
-type ControllerHandler<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TAll extends RequestSchema | unknown = unknown, TMiddlewareExt extends Record<string, any> = Record<string, never>> = (req: Request<ExtractParams<TPath>, TBody extends RequestSchema ? InferBodyType<TBody> : InferBodyType<TAll>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>> & TMiddlewareExt, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType<InferResponseMap<TResponses>>;
+type ControllerHandler<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, THeaders extends RequestSchema | unknown = unknown, TAll extends RequestSchema | unknown = unknown, TMiddlewareExt extends Record<string, any> = Record<string, never>> = (req: Request<ExtractParams<TPath>, TBody extends RequestSchema ? InferBodyType<TBody> : InferBodyType<TAll>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>, THeaders extends RequestSchema ? InferHeadersType<THeaders> : Record<string, string | string[]>> & TMiddlewareExt, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType<InferResponseMap<TResponses>>;
 
 type RunTimeType = "bun" | "node" | "deno";
 

package/lib/index.d.ts

@@ -54,6 +54,10 @@ interface ValidationOptions {
      * The schema to validate the query parameters against (Zod, TypeBox, or plain JSON schema)
      */
     query?: RequestSchema;
+    /**
+     * The schema to validate the request headers against (Zod, TypeBox, or plain JSON schema)
+     */
+    headers?: RequestSchema;
     /**
      * The schema to validate both body and query against (Zod, TypeBox, or plain JSON schema)
      */
@@ -93,6 +97,12 @@ type InferBodyType<T> = T extends RequestSchema ? ValidatedData<T> : unknown;
  * Infers the typed query from a schema. Returns `Record<string, string>` if no schema is provided.
  */
 type InferQueryType<T> = T extends RequestSchema ? ValidatedData<T> : Record<string, string>;
+/**
+ * Infers the typed headers from a schema.
+ * Returns `Record<string, string | string[]>` if no schema is provided
+ * (supporting multi-value headers).
+ */
+type InferHeadersType<T> = T extends RequestSchema ? ValidatedData<T> : Record<string, string | string[]>;
 /**
  * Extracts the body type for a specific HTTP status code from a response map.
  * When the status code has a schema defined, enforces type matching with widened
@@ -180,8 +190,9 @@ type FilePluginOptions = {
  * @template Params - The path parameters type (automatically extracted from route)
  * @template TBody - The typed body (inferred from body schema when provided)
  * @template TQuery - The typed query (inferred from query schema when provided)
+ * @template THeaders - The typed headers (inferred from headers schema when provided)
  */
-declare class Request<Params extends Record<string, string> = any, TBody = unknown, TQuery extends Record<string, any> = Record<string, string>> {
+declare class Request<Params extends Record<string, string> = Record<string, string>, TBody = unknown, TQuery extends Record<string, any> = Record<string, string>, THeaders extends Record<string, any> = Record<string, string | string[]>> {
     #private;
     /**
      * Creates a new request object from a Web API Request object.
@@ -228,10 +239,17 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      */
     method: string;
     /**
-     * The headers of the request — lazily constructed from raw Node.js headers.
+     * Raw Headers API object for low-level access.
+     * Use this for case-insensitive lookups, iteration, etc.
      */
-    get headers(): globalThis.Headers;
-    set headers(value: globalThis.Headers);
+    get rawHeaders(): globalThis.Headers;
+    /**
+     * The typed headers of the request.
+     * After validation with a headers schema, this contains the validated/typed header values.
+     * For raw Headers API access, use `rawHeaders`.
+     */
+    get headers(): THeaders;
+    set headers(value: THeaders);
     /**
      * The signal for aborting the request
      */
@@ -449,6 +467,12 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @param throwErrorOnValidationFail - If true, throws ValidationError on validation failure. If false, returns the original data.
      */
     validateAll<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
+    /**
+     * Validates the headers of the request.
+     * @param inputSchema - The schema to validate the headers against (Zod schema, TypeBox, or JSON Schema).
+     * @param throwErrorOnValidationFail - If true, throws ValidationError on validation failure. If false, returns the original headers.
+     */
+    validateHeaders<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
     /**
      * Sets a lazy IP extractor function.
      * IP will only be extracted when `.ip` is first accessed.
@@ -850,9 +874,11 @@ type HTMLString = string;
  */
 type CustomUIGenerator = (specUrl: string, globalOptions: SwaggerGlobalOptions) => HTMLString;
 /**
- * Type of request body for a route
+ * Type of request body for a route.
+ * Common MIME types are provided as literals withintellisense,
+ * custom MIME types can be specified as strings.
  */
-type SwaggerBodyType = "json" | "form-data" | "urlencoded";
+type SwaggerBodyType = "json" | "form-data" | "urlencoded" | "binary" | "text" | "event-stream" | (string & {});
 /**
  * JSONSchema type for OpenAPI/AJV-compatible schemas
  */
@@ -939,17 +965,24 @@ type SwaggerGlobalOptions = (SwaggerGlobalOptionsBase & {
     customUIGenerator: CustomUIGenerator;
 });
 /**
- * Route-specific documentation options (for individual endpoints)
+ * Route-specific documentation options for OpenAPI/Swagger generation.
+ *
+ * These options are for DOCUMENTATION PURPOSES ONLY and are NOT validated or enforced at runtime.
+ * For validated schemas, use the route-level `body`, `query`, and `responses` options.
+ *
+ * @example
+ * // Document route with custom body type
+ * router.get("/download", { swagger: { bodyType: "binary" } }, handler);
+ *
+ * @example
+ * // Document authentication requirements
+ * router.get("/protected", { swagger: { security: { type: "bearer" } } }, handler);
  */
 type SwaggerRouteOptions = {
     /** Service category where the route belongs to */
     service?: string;
     /** Name of the route */
     name?: string;
-    /** Responses for this route (used by decorators) */
-    responses?: Record<number, RequestSchema>;
-    /** Errors for this route */
-    errors?: Record<number, RequestSchema>;
     /** Security requirements for this route */
     security?: Security[] | Security;
     /** Description of the route */
@@ -959,7 +992,10 @@ type SwaggerRouteOptions = {
     /** Exclude from swagger */
     excludeFromSwagger?: boolean;
     /**
-     * The request body type for this route. Allowed values: 'json', 'form-data', 'urlencoded'. Defaults to 'json'.
+     * The request body type for documentation purposes.
+     * Common types: 'json', 'form-data', 'urlencoded', 'binary', 'text', 'event-stream'.
+     * Custom MIME types can be specified as strings (e.g., 'application/vnd.api+json').
+     * Defaults to 'json'.
      */
     bodyType?: SwaggerBodyType;
 };
@@ -1021,6 +1057,7 @@ type OpenIdConnectOptions = {
 /**
  * Decorator to mark a class as a controller, routes defined in the controller will be registered at import time when calling the `listen` method.
  * You can customize the path pattern for controller imports in the server options `controllerPatterns`
+ * @deprecated This decorator is deprecated and class based controllers won't be supported in the future. Please use the `router` directly to define your routes in a functional way for better type-safety.
  * @param path - The path pattern for the controller.
  * @param swaggerOptions - The swagger options for the controller that will be applied to all routes defined in the controller. Controller options will override route options.
  * @swagger If swagger is enabled, the default service name for all routes defined in the controller will be the controller name.
@@ -1672,20 +1709,20 @@ type InferMiddlewareExtensions<T extends readonly any[]> = T extends readonly [i
  * ```
  */
 interface GroupRouter<TGroupExt extends Record<string, any> = Record<string, never>> {
-    get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
-    head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, TGroupExt>): void;
-    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
+    head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath, Record<number, RequestSchema>, unknown, unknown, unknown, unknown, TGroupExt>): void;
+    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, TGroupExt & InferMiddlewareExtensions<TMiddlewares>>): void;
     group<const TMiddlewares extends readonly (ServerRouteMiddleware | TypedMiddleware<any>)[] = readonly (ServerRouteMiddleware | TypedMiddleware<any>)[]>(path: string, middleware: TMiddlewares, cb: (router: GroupRouter<TGroupExt & InferMiddlewareExtensions<TMiddlewares>>) => void): void;
     group(path: string, cb: (router: GroupRouter<TGroupExt>) => void): void;
 }
@@ -1717,6 +1754,7 @@ declare class Router {
     addOrUpdate(method: HttpMethod, path: string, middleware: (ServerRouteMiddleware | TypedMiddleware<any>)[], handler: ServerRouteHandler, validationSchemas?: {
         body?: RequestSchema;
         query?: RequestSchema;
+        headers?: RequestSchema;
         all?: RequestSchema;
     }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>, allowUpdate?: boolean): void;
     /**
@@ -1740,37 +1778,37 @@ declare class Router {
      * Register a GET route under this router's base path with type-safe path parameters.
      */
     get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a POST route under this router's base path with type-safe path parameters.
      */
     post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a PATCH route under this router's base path with type-safe path parameters.
      */
     patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a PUT route under this router's base path with type-safe path parameters.
      */
     put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a DELETE route under this router's base path with type-safe path parameters.
      */
     delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register an OPTIONS route under this router's base path with type-safe path parameters.
      */
     options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register an HEAD route under this router's base path with type-safe path parameters.
      */
     head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
+    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, THeaders, TPath, TAll, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, THeaders, TAll, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Create a grouped router that shares a base path and middlewares.
      * The callback receives a typed child router where routes are defined; routes
@@ -1817,12 +1855,13 @@ interface Route {
      */
     responseSchemas?: RouteResponseSchemas;
     /**
-     * Validation schemas for request body, query parameters, or both.
+     * Validation schemas for request body, query parameters, headers, or all.
      * When provided, the handler will receive validated data as additional parameters.
      */
     validationSchemas?: {
         body?: RequestSchema;
         query?: RequestSchema;
+        headers?: RequestSchema;
         all?: RequestSchema;
     };
 }
@@ -2779,10 +2818,11 @@ interface ServerInterface {
      */
     exit: (code?: number) => void;
 }
-type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string, TAll extends RequestSchema | unknown = unknown, TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]> = {
+type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, THeaders extends RequestSchema | unknown = unknown, TPath extends string = string, TAll extends RequestSchema | unknown = unknown, TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]> = {
     middlewares?: TMiddlewares | TypedMiddleware<any>;
     body?: TBody;
     query?: TQuery;
+    headers?: THeaders;
     all?: TAll;
     responses?: TResponses;
     swagger?: SwaggerRouteOptions;
@@ -2793,7 +2833,7 @@ type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Re
 };
 type ServerHook = () => SyncOrAsync;
 type SignalEvent = Deno.Signal | NodeJS.Signals;
-type ControllerHandler<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TAll extends RequestSchema | unknown = unknown, TMiddlewareExt extends Record<string, any> = Record<string, never>> = (req: Request<ExtractParams<TPath>, TBody extends RequestSchema ? InferBodyType<TBody> : InferBodyType<TAll>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>> & TMiddlewareExt, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType<InferResponseMap<TResponses>>;
+type ControllerHandler<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, THeaders extends RequestSchema | unknown = unknown, TAll extends RequestSchema | unknown = unknown, TMiddlewareExt extends Record<string, any> = Record<string, never>> = (req: Request<ExtractParams<TPath>, TBody extends RequestSchema ? InferBodyType<TBody> : InferBodyType<TAll>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>, THeaders extends RequestSchema ? InferHeadersType<THeaders> : Record<string, string | string[]>> & TMiddlewareExt, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType<InferResponseMap<TResponses>>;
 
 type RunTimeType = "bun" | "node" | "deno";