balda 0.0.57 → 0.0.59

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 import { JSONSchema as JSONSchema$1, FromSchema } from 'json-schema-to-ts';
-import { Ajv } from 'ajv';
+import { Ajv, ErrorObject } from 'ajv';
+export { ErrorObject, ValidationError } from 'ajv';
 import { IncomingMessage, ServerResponse, Server as Server$2 } from 'node:http';
 import { schedule, TaskContext } from 'node-cron';
 import { Http2Server } from 'node:http2';
@@ -869,6 +870,18 @@ declare const flag: {
  */
 type SwaggerUIType = "standard" | "rapidoc" | "scalar" | "elements" | "custom";
 type HTMLString = string;
+/**
+ * Configuration for validation error response documentation.
+ * Used to document validation errors in Swagger when routes have validation schemas.
+ */
+type ValidationErrorResponseOptions = {
+    /** HTTP status code for validation errors. Default: 422 */
+    statusCode?: number;
+    /** Response description. Default: "Validation error" */
+    description?: string;
+    /** Response schema for the error body. Default: { type: "object", properties: { message: { type: "string" }, errors: { type: "array", items: { type: "object", properties: { instancePath: { type: "string" }, schemaPath: { type: "string" }, keyword: { type: "string" }, params: { type: "object" }, message: { type: "string" } } } }, ajv: { type: "boolean" }, validation: { type: "boolean" } } } */
+    schema?: JSONSchema;
+};
 /**
  * Custom UI generator function that takes the spec URL and global options and returns HTML
  */
@@ -951,6 +964,13 @@ type SwaggerGlobalOptionsBase = {
      * OpenAPI models to be shown in the documentation. Must be valid OpenAPI/AJV JSONSchema objects.
      */
     models?: Record<string, JSONSchema> | JSONSchema[];
+    /**
+     * Global configuration for validation error response documentation.
+     * Applied to all routes that have validation schemas (body, query, headers, or all).
+     * Can be overridden per-route via swagger.validationErrorResponse.
+     * Default: { statusCode: 422, description: "Validation error" }
+     */
+    validationErrorResponse?: ValidationErrorResponseOptions;
 };
 /**
  * Global documentation options for the API (OpenAPI/Swagger style)
@@ -998,6 +1018,12 @@ type SwaggerRouteOptions = {
      * Defaults to 'json'.
      */
     bodyType?: SwaggerBodyType;
+    /**
+     * Override the global validation error response for this route.
+     * Only applies when the route has validation schemas (body, query, headers, or all).
+     * Overrides swagger global validationErrorResponse configuration.
+     */
+    validationErrorResponse?: ValidationErrorResponseOptions;
 };
 type OAuth2Flows = {
     implicit?: OAuth2Flow;
@@ -1378,6 +1404,7 @@ declare class Response$1<TResponseMap extends Record<number, any> = Record<numbe
 }
 
 /**
+ * @deprecated use directly router.delete() instead, this is just a wrapper for backward compatibility and might be removed in future versions
  * Decorator to mark a handler for a DELETE request with type-safe path parameters and response body
  * DELETE requests cannot have a request body (by HTTP spec)
  * Query params must be validated with @validate decorators to be typed
@@ -1406,6 +1433,7 @@ declare class Response$1<TResponseMap extends Record<number, any> = Record<numbe
 declare const del: <TPath extends string = string>(path: TPath, options?: SwaggerRouteOptions) => <T extends (req: Request<ExtractParams<TPath>>, res: Response$1, ...args: any[]) => any>(target: any, propertyKey: string, descriptor: PropertyDescriptor) => TypedPropertyDescriptor<T>;
 
 /**
+ * @deprecated use directly router.get() instead, this is just a wrapper for backward compatibility and might be removed in future versions
  * Decorator to mark a handler for a GET request with type-safe path parameters and response body
  * GET requests cannot have a request body (by HTTP spec)
  * Body and query must be validated with @validate decorators to be typed
@@ -1440,6 +1468,7 @@ declare const del: <TPath extends string = string>(path: TPath, options?: Swagge
 declare const get: <TPath extends string = string>(path: TPath, options?: SwaggerRouteOptions) => <T extends (req: Request<ExtractParams<TPath>>, res: Response$1, ...args: any[]) => any>(target: any, propertyKey: string, descriptor: PropertyDescriptor) => TypedPropertyDescriptor<T>;
 
 /**
+ * @deprecated use directly router.post() instead, this is just a wrapper for backward compatibility and might be removed in future versions
  * Decorator to mark a handler for a PATCH request with type-safe path parameters and response body
  * Body and query must be validated with @validate decorators to be typed
  * @param path - The path of the route (path parameters will be automatically inferred)
@@ -1472,6 +1501,7 @@ declare const get: <TPath extends string = string>(path: TPath, options?: Swagge
 declare const patch: <TPath extends string = string>(path: TPath, options?: SwaggerRouteOptions) => <T extends (req: Request<ExtractParams<TPath>>, res: Response$1, ...args: any[]) => any>(target: any, propertyKey: string, descriptor: PropertyDescriptor) => TypedPropertyDescriptor<T>;
 
 /**
+ * @deprecated use directly router.post() instead, this is just a wrapper for backward compatibility and might be removed in future versions
  * Decorator to mark a handler for a POST request with type-safe path parameters and response body
  * Body and query must be validated with @validate decorators to be typed
  * @param path - The path of the route (path parameters will be automatically inferred)
@@ -1504,6 +1534,7 @@ declare const patch: <TPath extends string = string>(path: TPath, options?: Swag
 declare const post: <TPath extends string = string>(path: TPath, options?: SwaggerRouteOptions) => <T extends (req: Request<ExtractParams<TPath>>, res: Response$1, ...args: any[]) => any>(target: any, propertyKey: string, descriptor: PropertyDescriptor) => TypedPropertyDescriptor<T>;
 
 /**
+ * @deprecated use directly router.post() instead, this is just a wrapper for backward compatibility and might be removed in future versions
  * Decorator to mark a handler for a PUT request with type-safe path parameters and response body
  * Body and query must be validated with @validate decorators to be typed
  * @param path - The path of the route (path parameters will be automatically inferred)
@@ -1710,7 +1741,7 @@ 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, 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;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: BodylessMethodOptions<TResponses, TQuery, THeaders, TPath, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, unknown, TQuery, THeaders, unknown, 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;
@@ -1718,7 +1749,7 @@ interface GroupRouter<TGroupExt extends Record<string, any> = Record<string, nev
     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;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: BodylessMethodOptions<TResponses, TQuery, THeaders, TPath, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, unknown, TQuery, THeaders, unknown, 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;
@@ -1776,9 +1807,10 @@ declare class Router {
     private extractOptionsAndHandler;
     /**
      * Register a GET route under this router's base path with type-safe path parameters.
+     * Note: GET routes cannot have body validation per HTTP specification.
      */
     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, 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;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: BodylessMethodOptions<TResponses, TQuery, THeaders, TPath, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, unknown, TQuery, THeaders, unknown, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register a POST route under this router's base path with type-safe path parameters.
      */
@@ -1796,9 +1828,10 @@ declare class Router {
     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.
+     * Note: DELETE routes cannot have body validation per HTTP specification.
      */
     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, 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;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TQuery extends RequestSchema | undefined = undefined, THeaders extends RequestSchema | undefined = undefined, const TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]>(path: TPath, options: BodylessMethodOptions<TResponses, TQuery, THeaders, TPath, TMiddlewares>, handler: ControllerHandler<TPath, TResponses, unknown, TQuery, THeaders, unknown, InferMiddlewareExtensions<TMiddlewares>>): void;
     /**
      * Register an OPTIONS route under this router's base path with type-safe path parameters.
      */
@@ -1871,16 +1904,65 @@ interface Route {
 type ClientRouter = Omit<Router, "applyGlobalMiddlewaresToAllRoutes" | "addOrUpdate">;
 
 /**
- * Custom handler invoked when a policy check fails.
- * When set, replaces the default `res.unauthorized({ error: "Unauthorized" })` response.
+ * Configuration for custom policy error handling.
+ * Replaces the default 401 response with a custom status and body shape.
+ *
+ * @template T - The schema type (Zod, TypeBox, or JSON Schema). When provided,
+ *               the map function return type is inferred as ValidatedData<T>.
  */
-type PolicyErrorHandler = (req: Request, res: Response$1) => SyncOrAsync;
+interface PolicyErrorHandlerOptions<T extends RequestSchema = RequestSchema> {
+    /** HTTP status code for the response. Default: 401 */
+    status?: number;
+    /**
+     * Zod/TypeBox/JSON schema for the response body.
+     * Used for Swagger documentation and type inference for map return type.
+     */
+    schema?: T;
+    /**
+     * Transform policy error to your custom response shape.
+     * Required if schema is provided.
+     * @param req - The request object (for path, method, headers, user, etc.)
+     * @returns The response body to send. When schema is provided, return type is ValidatedData<T>.
+     *          Can be async (return Promise) for asynchronous transformations.
+     */
+    map?: (req: Request) => ValidatedData<T> | Promise<ValidatedData<T>>;
+}
 
 /**
- * Custom handler invoked when request validation fails.
- * When set, replaces the default `res.badRequest(error)` response.
+ * The serialized validation error object passed to the map function.
+ * This is the JSON-serializable shape of AJV's ValidationError.
+ */
+interface SerializedValidationError {
+    message: string;
+    errors: ErrorObject[];
+    ajv: true;
+    validation: true;
+}
+/**
+ * Configuration for custom validation error handling.
+ * Replaces the default 422 response with a custom status and body shape.
+ *
+ * @template T - The schema type (Zod, TypeBox, or JSON Schema). When provided,
+ *               the map function return type is inferred as ValidatedData<T>.
  */
-type ValidationErrorHandler = (req: Request, res: Response$1, error: unknown) => SyncOrAsync;
+interface ValidationErrorHandlerOptions<T extends RequestSchema = RequestSchema> {
+    /** HTTP status code for the response. Default: 422 */
+    status?: number;
+    /**
+     * Zod/TypeBox/JSON schema for the response body.
+     * Used for Swagger documentation and type inference for map return type.
+     */
+    schema?: T;
+    /**
+     * Transform AJV errors to your custom response shape.
+     * Required if schema is provided.
+     * @param error - The validation error object with AJV ErrorObject array
+     * @param req - The request object (for path, method, headers, etc.)
+     * @returns The response body to send. When schema is provided, return type is ValidatedData<T>.
+     *          Can be async (return Promise) for asynchronous transformations.
+     */
+    map?: (error: SerializedValidationError, req: Request) => ValidatedData<T> | Promise<ValidatedData<T>>;
+}
 
 /**
  * The server class that is used to create and manage the server
@@ -1902,9 +1984,12 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
      * @param options.host - The hostname to listen on, if not provided, it will use the HOST environment variable, if not provided, it will default to 0.0.0.0
      * @param options.controllerPatterns - The patterns to match for controllers, defaults to an empty array
      * @param options.plugins - The plugins to apply to the server, by default no plugins are applied, plugins are applied in the order they are defined in the options
-     * @param options.logger - The logger to use for the server, by default a default logger is used
+     * @param options.logger - The pino logger to use for the server, by default a default logger is used
      * @param options.tapOptions - Options fetch to the runtime server before the server is up and running
      * @param options.abortSignal - An optional AbortSignal to gracefully shutdown the server when aborted
+     * @param options.ajvInstance - An optional AJV instance to use for validation, if not provided, a default instance will be used
+     * @param options.nodeHttpClient - The node http client to use, it can be "http", "https" or "http2-secure", by default it's "http", if you set it to "https" or "http2-secure" you must also provide the httpsOptions
+     * @param options.httpsOptions - The https options to use if the nodeHttpClient is set to "https" or "http2-secure"
      */
     constructor(options?: ServerOptions<H>);
     get protectedKeys(): string[];
@@ -1934,13 +2019,13 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
     mountExpressRouter(basePath: string, expressRouter: Router$1): void;
     setErrorHandler(errorHandler?: ServerErrorHandler): void;
     setNotFoundHandler(notFoundHandler?: ServerRouteHandler): void;
-    setValidationErrorHandler(handler: ValidationErrorHandler): void;
-    setPolicyErrorHandler(handler: PolicyErrorHandler): void;
+    setValidationErrorHandler<T extends RequestSchema>(options: ValidationErrorHandlerOptions<T>): void;
+    setPolicyErrorHandler<T extends RequestSchema>(options: PolicyErrorHandlerOptions<T>): void;
     beforeStart(hook: ServerHook): void;
     beforeClose(hook: ServerHook): void;
     listen(cb?: ServerListenCallback): void;
     listen(port: number, cb?: ServerListenCallback): void;
-    waitUntilListening(): Promise<{
+    waitUntilListening(port?: number): Promise<{
         port: number;
         host: string;
         url: string;
@@ -1990,10 +2075,14 @@ declare class MockResponse<T = any> {
     body(): T;
     statusCode(): number;
     headers(): Record<string, string>;
+    cookies(): Record<string, string>;
     assertStatus(status: number): this;
     assertHeader(header: string, value: string): this;
     assertHeaderExists(header: string): this;
     assertHeaderNotExists(header: string): this;
+    assertCookie(name: string, value: string): this;
+    assertCookieExists(name: string): this;
+    assertCookieNotExists(name: string): this;
     assertBodySubset(subset: Partial<T>): this;
     assertBodyDeepEqual(expected: T): this;
     assertBodyNotSubset(subset: Partial<T>): this;
@@ -2728,28 +2817,83 @@ interface ServerInterface {
     setNotFoundHandler: (notFoundHandler?: ServerRouteHandler) => void;
     /**
      * Set a custom handler for validation errors (body/query validation failures).
-     * When set, replaces the default `res.badRequest(error)` response.
-     * @param handler - The handler to invoke when validation fails
-     * @example
+     * Replaces the default 422 response with a custom status and body shape.
+     *
+     * The 'map' function is required when 'schema' is provided.
+     * The schema is used for Swagger documentation, 'map' transforms the error to your shape.
+     *
+     * @param options - Configuration object
+     *
+     * @example Basic usage - custom status and map
      * ```ts
-     * server.setValidationErrorHandler((req, res, error) => {
-     *   res.status(422).json({ code: "VALIDATION_FAILED", details: error });
+     * server.setValidationErrorHandler({
+     *   status: 400,
+     *   map: (error, req) => ({
+     *     path: req.path,
+     *     errors: error.errors,
+     *   }),
+     * });
+     * ```
+     *
+     * @example With schema for Swagger docs
+     * ```ts
+     * import { z } from "zod";
+     *
+     * server.setValidationErrorHandler({
+     *   status: 422,
+     *   schema: z.object({
+     *     code: z.string(),
+     *     message: z.string(),
+     *     errors: z.array(z.object({
+     *       field: z.string(),
+     *       message: z.string(),
+     *     })),
+     *   }),
+     *   map: (error, req) => ({
+     *     code: "VALIDATION_ERROR",
+     *     message: error.message,
+     *     errors: error.errors.map(e => ({
+     *       field: e.instancePath,
+     *       message: e.message,
+     *     })),
+     *   }),
      * });
      * ```
      */
-    setValidationErrorHandler: (handler: ValidationErrorHandler) => void;
+    setValidationErrorHandler: (options: ValidationErrorHandlerOptions) => void;
     /**
      * Set a custom handler for policy authorization failures.
      * When set, replaces the default `res.unauthorized({ error: "Unauthorized" })` response.
-     * @param handler - The handler to invoke when a policy check fails
-     * @example
+     *
+     * @param options - Configuration object with status, schema, and map function
+     *
+     * @example Basic usage
+     * ```ts
+     * server.setPolicyErrorHandler({
+     *   status: 403,
+     *   map: (req) => ({
+     *     code: "FORBIDDEN",
+     *     message: "Access denied",
+     *   }),
+     * });
+     * ```
+     *
+     * @example With schema for Swagger docs
      * ```ts
-     * server.setPolicyErrorHandler((req, res) => {
-     *   res.status(403).json({ code: "FORBIDDEN", message: "Access denied" });
+     * server.setPolicyErrorHandler({
+     *   status: 401,
+     *   schema: z.object({
+     *     code: z.string(),
+     *     message: z.string(),
+     *   }),
+     *   map: (req) => ({
+     *     code: "UNAUTHORIZED",
+     *     message: "Authentication required",
+     *   }),
      * });
      * ```
      */
-    setPolicyErrorHandler: (handler: PolicyErrorHandler) => void;
+    setPolicyErrorHandler: (options: PolicyErrorHandlerOptions) => void;
     /**
      * Register a hook to be called after bootstrap (controllers imported, plugins applied) but before the server starts accepting requests.
      * Multiple hooks are called in the order they are registered.
@@ -2779,14 +2923,12 @@ interface ServerInterface {
      * Binds the server to the port and hostname defined in the serverOptions, meant to be called only once
      * It initializes the server without blocking the event loop, you can pass a callback to be called when the server is listening
      * Use `waitUntilListening` instead if you want to wait for the server to be listening for requests before returning
-     * @warning All routes defined with decorators are defined on this method just before the server starts listening for requests
      */
     listen: (cb?: ServerListenCallback) => void;
     /**
      * Binds the server to the port and hostname defined in the serverOptions, meant to be called only once
      * It initializes the server blocking the event loop, it will wait for the server to be listening for requests before returning
      * Use `listen` instead if you want to initialize the server without blocking the event loop
-     * @warning All routes defined with decorators are defined on this method just before the server starts listening for requests
      */
     waitUntilListening: () => Promise<{
         port: number;
@@ -2836,6 +2978,21 @@ type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Re
     /** Policy configuration for this route. Accepts a single policy or an array of policies. */
     policy?: PolicyRouteConfig | PolicyRouteConfig[];
 };
+/**
+ * Options for routes that don't allow request body (GET, DELETE).
+ * Excludes 'body' and 'all' validation options per HTTP specification.
+ */
+type BodylessMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TQuery extends RequestSchema | unknown = unknown, THeaders extends RequestSchema | unknown = unknown, TPath extends string = string, TMiddlewares extends readonly TypedMiddleware<any>[] = readonly TypedMiddleware<any>[]> = {
+    middlewares?: TMiddlewares | TypedMiddleware<any>;
+    query?: TQuery;
+    headers?: THeaders;
+    responses?: TResponses;
+    swagger?: SwaggerRouteOptions;
+    /** Cache configuration for this route. Body-based caching is not available for GET/DELETE. */
+    cache?: TypedCacheRouteConfig<unknown, TQuery, TPath>;
+    /** Policy configuration for this route. Accepts a single policy or an array of policies. */
+    policy?: PolicyRouteConfig | PolicyRouteConfig[];
+};
 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, 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>>;
@@ -4750,4 +4907,4 @@ declare enum CacheStatus {
  */
 declare const router: ClientRouter;
 
-export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, CACHE_STATUS_HEADER, type CacheKeyIncludes, type CacheMiddlewareOptions, type CachePluginOptions, type CacheProvider, type CacheRedisOptions, type CacheRouteConfig, CacheService, type CacheServiceInterface, type CacheStats, CacheStatus, Command, type CommandOptions, CommandRegistry, type CompressionOptions, type CookieMiddlewareOptions, type CorsOptions, type CronSchedule, type CronScheduleParams, CronService, type CronUIOptions, CustomAdapter, type CustomQueueConfiguration, type CustomStorageProviderOptions, CustomTypedQueue, type CustomValidationError, DEFAULT_CACHE_OPTIONS, EdgeAdapter, EjsAdapter, type ExtractParams, GraphQL, type GraphQLContext, type GraphQLOptions, type GraphQLResolverFunction, type GraphQLResolverMap, type GraphQLResolverType, type GraphQLResolvers, type GraphQLSchemaInput, type GraphQLTypeDef, type GroupRouter, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, type InferMiddlewareExtension, type InferMiddlewareExtensions, type InferResponseMap, type InferSchemaType, LocalStorageProvider, type LocalStorageProviderOptions, type LockBehavior, type LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, MemoryCacheProvider, MemoryPubSub, type MethodOverrideOptions, MockResponse, MockServer, type MockServerOptions, type MqttConnectionOptions, type MqttHandler, type MqttPublishOptions, MqttService, type MqttSubscribeOptions, type MqttSubscription, type MqttTopics, MustacheAdapter, type NextFunction, type NodeHttpClient, type NodeServer as NodeHttpServerClient, PGBossConfiguration, type PGBossConfigurationOptions, PGBossPubSub, type PolicyDecorator, type PolicyErrorHandler, PolicyManager, type PolicyProvider, type PolicyRouteConfig, type PublishTopic, QueueManager, QueueService, type RateLimiterKeyOptions, RedisCacheProvider, Request, type RequestSchema, Response$1 as Response, type ResponseBodyForStatus, type RuntimeServer, S3StorageProvider, type S3StorageProviderOptions, SQSConfiguration, type SQSConfigurationOptions, SQSPubSub, type CacheMetrics as SchemaCacheMetrics, type SerializeOptions, Server, type ServerConnectInput, type ServerErrorHandler, type ServerHook, type ServerInterface, type ServerListenCallback, type ServerOptions, type ServerRouteHandler, type ServerRouteMiddleware, type ServerTapOptions, type SessionOptions, type SignalEvent, type StaticPluginOptions, Storage, type StorageInterface, type StorageOptions, type StorageProviderOptions, type TemplateMailOptions, type TimeoutOptions, type TrustProxyOptions, type TypedCacheKeyIncludes, type TypedCacheRouteConfig, type TypedHandler, type TypedMiddleware, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationErrorHandler, type ValidationOptions, arg, asyncLocalStorage, asyncStorage, bullmqQueue, cache, cacheMiddleware, clearAllCaches as clearAllSchemaCaches, commandRegistry, compression, controller, cookie, cors, createExpressAdapter, createPolicyDecorator, createQueue, cron, cronUIInstance, cronUi, Server as default, defineMiddleware, defineQueueConfiguration, del, expressHandler, expressMiddleware, flag, get, getCacheService, getCacheMetrics as getSchemaCacheMetrics, hash, helmet, initCacheService, log, logCacheMetrics as logSchemaCacheMetrics, logger, memoryQueue, methodOverride, middleware, mountExpressRouter, mqtt, patch, pgbossQueue, post, put, rateLimiter, resetCacheService, router, serialize, serveStatic, session, setCronGlobalErrorHandler, setMqttGlobalErrorHandler, sqsQueue, timeout as timeoutMw, trustProxy, validate };
+export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, type BodylessMethodOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, CACHE_STATUS_HEADER, type CacheKeyIncludes, type CacheMiddlewareOptions, type CachePluginOptions, type CacheProvider, type CacheRedisOptions, type CacheRouteConfig, CacheService, type CacheServiceInterface, type CacheStats, CacheStatus, Command, type CommandOptions, CommandRegistry, type CompressionOptions, type CookieMiddlewareOptions, type CorsOptions, type CronSchedule, type CronScheduleParams, CronService, type CronUIOptions, CustomAdapter, type CustomQueueConfiguration, type CustomStorageProviderOptions, CustomTypedQueue, type CustomValidationError, DEFAULT_CACHE_OPTIONS, EdgeAdapter, EjsAdapter, type ExtractParams, GraphQL, type GraphQLContext, type GraphQLOptions, type GraphQLResolverFunction, type GraphQLResolverMap, type GraphQLResolverType, type GraphQLResolvers, type GraphQLSchemaInput, type GraphQLTypeDef, type GroupRouter, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, type InferMiddlewareExtension, type InferMiddlewareExtensions, type InferResponseMap, type InferSchemaType, LocalStorageProvider, type LocalStorageProviderOptions, type LockBehavior, type LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, MemoryCacheProvider, MemoryPubSub, type MethodOverrideOptions, MockResponse, MockServer, type MockServerOptions, type MqttConnectionOptions, type MqttHandler, type MqttPublishOptions, MqttService, type MqttSubscribeOptions, type MqttSubscription, type MqttTopics, MustacheAdapter, type NextFunction, type NodeHttpClient, type NodeServer as NodeHttpServerClient, PGBossConfiguration, type PGBossConfigurationOptions, PGBossPubSub, type PolicyDecorator, type PolicyErrorHandlerOptions, PolicyManager, type PolicyProvider, type PolicyRouteConfig, type PublishTopic, QueueManager, QueueService, type RateLimiterKeyOptions, RedisCacheProvider, Request, type RequestSchema, Response$1 as Response, type ResponseBodyForStatus, type RuntimeServer, S3StorageProvider, type S3StorageProviderOptions, SQSConfiguration, type SQSConfigurationOptions, SQSPubSub, type CacheMetrics as SchemaCacheMetrics, type SerializeOptions, type SerializedValidationError, Server, type ServerConnectInput, type ServerErrorHandler, type ServerHook, type ServerInterface, type ServerListenCallback, type ServerOptions, type ServerRouteHandler, type ServerRouteMiddleware, type ServerTapOptions, type SessionOptions, type SignalEvent, type StandardMethodOptions, type StaticPluginOptions, Storage, type StorageInterface, type StorageOptions, type StorageProviderOptions, type TemplateMailOptions, type TimeoutOptions, type TrustProxyOptions, type TypedCacheKeyIncludes, type TypedCacheRouteConfig, type TypedHandler, type TypedMiddleware, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationErrorHandlerOptions, type ValidationOptions, arg, asyncLocalStorage, asyncStorage, bullmqQueue, cache, cacheMiddleware, clearAllCaches as clearAllSchemaCaches, commandRegistry, compression, controller, cookie, cors, createExpressAdapter, createPolicyDecorator, createQueue, cron, cronUIInstance, cronUi, Server as default, defineMiddleware, defineQueueConfiguration, del, expressHandler, expressMiddleware, flag, get, getCacheService, getCacheMetrics as getSchemaCacheMetrics, hash, helmet, initCacheService, log, logCacheMetrics as logSchemaCacheMetrics, logger, memoryQueue, methodOverride, middleware, mountExpressRouter, mqtt, patch, pgbossQueue, post, put, rateLimiter, resetCacheService, router, serialize, serveStatic, session, setCronGlobalErrorHandler, setMqttGlobalErrorHandler, sqsQueue, timeout as timeoutMw, trustProxy, validate };