balda 0.0.50 → 0.0.52

package/lib/index.d.ts

@@ -95,12 +95,18 @@ type InferBodyType<T> = T extends RequestSchema ? ValidatedData<T> : unknown;
 type InferQueryType<T> = T extends RequestSchema ? ValidatedData<T> : Record<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 exact type matching.
+ * When the status code has a schema defined, enforces type matching with widened
+ * literals (string literals → string, number literals → number, etc.) so that
+ * natural TypeScript return values like `{ status: "ok" }` are accepted without
+ * requiring `as const`.
  * Defaults to `any` when the status code is not present in the map.
  */
-type ResponseBodyForStatus<TMap, TStatus extends number> = TStatus extends keyof TMap ? 0 extends 1 & TMap[TStatus] ? any : {
+type WidenLiterals<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends (infer U)[] ? WidenLiterals<U>[] : T extends object ? {
+    [K in keyof T]: WidenLiterals<T[K]>;
+} : T;
+type ResponseBodyForStatus<TMap, TStatus extends number> = TStatus extends keyof TMap ? 0 extends 1 & TMap[TStatus] ? any : WidenLiterals<{
     [K in keyof TMap[TStatus]]: TMap[TStatus][K];
-} : any;
+}> : any;
 
 type SyncOrAsync<T = void> = T | Promise<T>;
 
@@ -322,14 +328,12 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @fileParser middleware is required
      */
     file(fieldName: string): FormFile | null;
-    /**
-     * The cookies of the request.
-     * @cookie middleware is required
-     */
-    cookies: Record<string, string>;
+    get cookies(): Record<string, string>;
+    set cookies(value: Record<string, string>);
     /**
      * The cookie of the request.
      * @cookie middleware is required
+     * @throws Error if cookie middleware is not registered
      */
     cookie(name: string): string | undefined;
     /**
@@ -337,27 +341,26 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @timeout middleware is required
      */
     timeout?: boolean;
+    get session(): Record<string, any> | undefined;
+    set session(value: Record<string, any> | undefined);
     /**
-     * The session of the request. Uses cookies to send the session id
-     * @cookie middleware is required
-     * @session middleware is required
-     */
-    session?: Record<string, any>;
-    /**
-     * Shared no-op async function to avoid per-instance closure allocation.
+     * Shared throwing functions to avoid per-instance closure allocation.
      * @internal
      */
-    private static readonly _noopAsync;
+    private static readonly _throwSaveSession;
+    private static readonly _throwDestroySession;
     /**
-     * The session of the request. Uses cookies to send the session id
+     * Save the current session data.
      * @cookie middleware is required
      * @session middleware is required
+     * @throws Error if session middleware is not registered
      */
     saveSession: () => Promise<void>;
     /**
-     * The session of the request.
+     * Destroy the current session.
      * @cookie middleware is required
      * @session middleware is required
+     * @throws Error if session middleware is not registered
      */
     destroySession: () => Promise<void>;
     get ip(): string | undefined;
@@ -1590,6 +1593,103 @@ declare class NativeFs {
 }
 declare const nativeFs: NativeFs;
 
+/**
+ * The next function.
+ * This is the function that is passed to the handler function.
+ * It has a pointer to the next middleware or handler function of the middleware chain.
+ */
+type NextFunction = () => SyncOrAsync;
+
+/**
+ * A middleware that carries type information about the properties it adds to the request.
+ * Uses a phantom branded property to flow type info through the type system without runtime cost.
+ *
+ * @template TExtension - The properties this middleware adds to the request object
+ *
+ * @example
+ * ```typescript
+ * const auth = defineMiddleware<{ userId: number }>((req, res, next) => {
+ *   req.userId = getUserIdFromToken(req.headers);
+ *   return next();
+ * });
+ *
+ * router.get("/profile", { middlewares: [auth] }, (req, res) => {
+ *   req.userId; // number — inferred from middleware!
+ * });
+ * ```
+ */
+type TypedMiddleware<TExtension extends Record<string, any> = Record<string, never>> = ((req: Request & TExtension, res: Response$1, next: NextFunction) => SyncOrAsync) & {
+    readonly __middlewareExtension?: TExtension;
+};
+/**
+ * Helper to create a typed middleware with correct request typing inside the middleware body.
+ * The returned function is branded with the extension type so the router can infer it.
+ *
+ * @template TExtension - The properties this middleware adds to the request
+ * @param fn - The middleware function with typed `req` parameter
+ * @returns A branded middleware carrying the extension type
+ *
+ * @example
+ * ```typescript
+ * const auth = defineMiddleware<{ userId: number }>((req, res, next) => {
+ *   req.userId = 123;
+ *   return next();
+ * });
+ * ```
+ */
+declare function defineMiddleware<TExtension extends Record<string, any>>(fn: (req: Request & TExtension, res: Response$1, next: NextFunction) => SyncOrAsync): TypedMiddleware<TExtension>;
+/**
+ * Extracts the extension type from a single middleware.
+ * Returns `{}` for unbranded middlewares (backward compatibility).
+ */
+type InferMiddlewareExtension<T> = T extends TypedMiddleware<infer E> ? E : {};
+/**
+ * Combines extension types from a tuple of middlewares into a single intersection type.
+ *
+ * @example
+ * ```typescript
+ * type Ext = InferMiddlewareExtensions<[TypedMiddleware<{ userId: number }>, TypedMiddleware<{ role: string }>]>;
+ * // { userId: number } & { role: string }
+ * ```
+ */
+type InferMiddlewareExtensions<T extends readonly any[]> = T extends readonly [infer First, ...infer Rest] ? InferMiddlewareExtension<First> & InferMiddlewareExtensions<Rest> : {};
+
+/**
+ * A type-level overlay for Router that carries group-level middleware extensions.
+ * Every route handler defined on a GroupRouter automatically receives `TGroupExt`
+ * merged into its `req` parameter, composed with any route-level TypedMiddleware extensions.
+ *
+ * @template TGroupExt - The accumulated middleware extensions from enclosing group(s)
+ *
+ * @example
+ * ```typescript
+ * router.group("/api", [auth], (r) => {
+ *   // r is GroupRouter<{ userId: number }>
+ *   r.get("/profile", (req, res) => {
+ *     req.userId; // number — inferred from group middleware
+ *   });
+ * });
+ * ```
+ */
+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;
+    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;
+}
+
 /**
  * Singleton that handles the routing of requests to the appropriate handler(s).
  */
@@ -1607,14 +1707,14 @@ declare class Router {
      * @param middlewares - Default middlewares to apply to all routes
      * @param options - Router configuration options
      */
-    constructor(basePath?: string, middlewares?: ServerRouteMiddleware[]);
+    constructor(basePath?: string, middlewares?: (ServerRouteMiddleware | TypedMiddleware<any>)[]);
     /** Returns a shallow copy of all registered routes. */
     getRoutes(): Route[];
     /**
      * Add or update a route
      * @internal
      */
-    addOrUpdate(method: HttpMethod, path: string, middleware: ServerRouteMiddleware[], handler: ServerRouteHandler, validationSchemas?: {
+    addOrUpdate(method: HttpMethod, path: string, middleware: (ServerRouteMiddleware | TypedMiddleware<any>)[], handler: ServerRouteHandler, validationSchemas?: {
         body?: RequestSchema;
         query?: RequestSchema;
         all?: RequestSchema;
@@ -1625,7 +1725,7 @@ declare class Router {
      * Uses O(1) cache lookup for static routes, falls back to O(k) tree traversal for dynamic routes.
      */
     find(method: string, rawPath: string): {
-        middleware: ServerRouteMiddleware[];
+        middleware: (ServerRouteMiddleware | TypedMiddleware<any>)[];
         handler: ServerRouteHandler;
         params: Params;
         responseSchemas?: RouteResponseSchemas;
@@ -1640,50 +1740,51 @@ 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * 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>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): 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;
     /**
      * Create a grouped router that shares a base path and middlewares.
-     * The callback receives a child router where routes are defined; routes
+     * The callback receives a typed child router where routes are defined; routes
      * are then merged back into the parent with the composed base path and middlewares.
+     * TypedMiddleware extensions flow into the callback's router for full type inference.
      */
-    group(path: string, middleware: ServerRouteMiddleware[] | ServerRouteMiddleware, cb: (router: Router) => void): void;
-    group(path: string, cb: (router: Router) => void): void;
+    group<const TMiddlewares extends readonly (ServerRouteMiddleware | TypedMiddleware<any>)[] = readonly (ServerRouteMiddleware | TypedMiddleware<any>)[]>(path: string, middleware: TMiddlewares, cb: (router: GroupRouter<InferMiddlewareExtensions<TMiddlewares>>) => void): void;
+    group(path: string, cb: (router: GroupRouter<{}>) => void): void;
     /**
      * Apply global middlewares to all routes
      * @param middlewares - The middlewares to apply
      * @internal
      */
-    applyGlobalMiddlewaresToAllRoutes(middlewares: ServerRouteMiddleware[]): void;
+    applyGlobalMiddlewaresToAllRoutes(middlewares: (ServerRouteMiddleware | TypedMiddleware<any>)[]): void;
     private normalizeBasePath;
     private joinPath;
     /**
@@ -1702,7 +1803,7 @@ type RouteResponseSchemas = Record<number, RequestSchema>;
 interface Route {
     method: string;
     path: string;
-    middleware: ServerRouteMiddleware[];
+    middleware: (ServerRouteMiddleware | TypedMiddleware<any>)[];
     handler: ServerRouteHandler;
     swaggerOptions?: SwaggerRouteOptions;
     /**
@@ -1772,13 +1873,14 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
     on(event: string, cb: () => SyncOrAsync): void;
     once(event: SignalEvent, cb: () => SyncOrAsync): void;
     once(event: string, cb: () => SyncOrAsync): void;
-    use(...middlewares: ServerRouteMiddleware[]): void;
+    use(...middlewares: (ServerRouteMiddleware | TypedMiddleware<any>)[]): void;
     useExpress(pathOrMiddleware: string | RequestHandler | Router$1, maybeMiddleware?: RequestHandler | Router$1): void;
     expressMiddleware(middleware: RequestHandler): ServerRouteMiddleware;
     mountExpressRouter(basePath: string, expressRouter: Router$1): void;
     setErrorHandler(errorHandler?: ServerErrorHandler): void;
     setNotFoundHandler(notFoundHandler?: ServerRouteHandler): void;
     beforeStart(hook: ServerHook): void;
+    beforeClose(hook: ServerHook): void;
     listen(cb?: ServerListenCallback): void;
     waitUntilListening(): Promise<{
         port: number;
@@ -2283,13 +2385,6 @@ type TrustProxyOptions = {
     hop?: "first" | "last";
 };
 
-/**
- * The next function.
- * This is the function that is passed to the handler function.
- * It has a pointer to the next middleware or handler function of the middleware chain.
- */
-type NextFunction = () => SyncOrAsync;
-
 type ServerHandlerReturnType<TResponseMap extends Record<number, any> = Record<number, any>> = void | Promise<void> | ResponseBodyForStatus<TResponseMap, 200> | Promise<ResponseBodyForStatus<TResponseMap, 200>>;
 type ServerPlugin = {
     bodyParser?: BodyParserOptions;
@@ -2526,7 +2621,7 @@ interface ServerInterface {
     /**
      * Register a global middleware to be applied to all routes after the listener is bound, the middleware is applied in the order it is registered
      */
-    use: (middleware: ServerRouteMiddleware) => void;
+    use: (middleware: ServerRouteMiddleware | TypedMiddleware<any>) => void;
     /**
      * Set the error handler for the server
      * @param errorHandler - The error handler to be applied to all routes
@@ -2555,6 +2650,19 @@ interface ServerInterface {
      * ```
      */
     beforeStart: (hook: ServerHook) => void;
+    /**
+     * Register a hook to be called before the server closes (after it stops accepting requests).
+     * Multiple hooks are called in the order they are registered.
+     * Useful for cleanup tasks like disconnecting from databases or flushing logs.
+     * @param hook - The hook function to call, can be sync or async
+     * @example
+     * ```ts
+     * server.beforeClose(async () => {
+     *   await disconnectFromDatabase();
+     * });
+     * ```
+     */
+    beforeClose: (hook: ServerHook) => void;
     /**
      * 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
@@ -2603,8 +2711,8 @@ 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> = {
-    middlewares?: ServerRouteMiddleware[] | ServerRouteMiddleware;
+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>[]> = {
+    middlewares?: TMiddlewares | TypedMiddleware<any>;
     body?: TBody;
     query?: TQuery;
     all?: TAll;
@@ -2615,7 +2723,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> = (req: Request<ExtractParams<TPath>, TBody extends RequestSchema ? InferBodyType<TBody> : InferBodyType<TAll>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>>, 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, 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 RunTimeType = "bun" | "node" | "deno";
 
@@ -4198,7 +4306,9 @@ declare const compression: (options?: CompressionOptions) => ServerRouteMiddlewa
  *
  * @param options Cookie middleware options
  */
-declare const cookie: (options?: CookieMiddlewareOptions) => ServerRouteMiddleware;
+declare const cookie: (options?: CookieMiddlewareOptions) => TypedMiddleware<{
+    cookies: Record<string, string>;
+}>;
 
 /**
  * CORS plugin
@@ -4295,7 +4405,11 @@ declare const rateLimiter: (keyOptions?: RateLimiterKeyOptions, storageOptions?:
  * @param options.store The store to use for the session
  * @param options.cookie The cookie options
  */
-declare const session: (options?: SessionOptions) => ServerRouteMiddleware;
+declare const session: (options?: SessionOptions) => TypedMiddleware<{
+    session: Record<string, any>;
+    saveSession: () => Promise<void>;
+    destroySession: () => Promise<void>;
+}>;
 
 /**
  * Creates a static file serving middleware and registers all routes for the given path
@@ -4319,7 +4433,9 @@ declare const serveStatic: (options: StaticPluginOptions, swaggerOptions?: Swagg
  * @param options.status The status code to return if the request times out
  * @param options.message The message to return if the request times out
  */
-declare const timeout: (options: TimeoutOptions) => ServerRouteMiddleware;
+declare const timeout: (options: TimeoutOptions) => TypedMiddleware<{
+    timeout: boolean;
+}>;
 
 /**
  * Trust proxy plugin middleware, used to trust the proxy headers to get the client ip
@@ -4540,4 +4656,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, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, 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, PolicyManager, type PolicyProvider, 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, TypedQueue, type TypedRouteMetadata, type ValidatedData, 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, 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, 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, PolicyManager, type PolicyProvider, 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 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 };