balda 0.0.48 → 0.0.50

package/lib/index.d.cts

@@ -222,9 +222,10 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      */
     method: string;
     /**
-     * The headers of the request
+     * The headers of the request — lazily constructed from raw Node.js headers.
      */
-    headers: globalThis.Headers;
+    get headers(): globalThis.Headers;
+    set headers(value: globalThis.Headers);
     /**
      * The signal for aborting the request
      */
@@ -320,7 +321,7 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * The file of the request.
      * @fileParser middleware is required
      */
-    file: (fieldName: string) => FormFile | null;
+    file(fieldName: string): FormFile | null;
     /**
      * The cookies of the request.
      * @cookie middleware is required
@@ -330,7 +331,7 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * The cookie of the request.
      * @cookie middleware is required
      */
-    cookie: (name: string) => string | undefined;
+    cookie(name: string): string | undefined;
     /**
      * tells if the request has timed out.
      * @timeout middleware is required
@@ -342,6 +343,11 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @session middleware is required
      */
     session?: Record<string, any>;
+    /**
+     * Shared no-op async function to avoid per-instance closure allocation.
+     * @internal
+     */
+    private static readonly _noopAsync;
     /**
      * The session of the request. Uses cookies to send the session id
      * @cookie middleware is required
@@ -354,11 +360,8 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @session middleware is required
      */
     destroySession: () => Promise<void>;
-    /**
-     * The ip address of the request.
-     * Tries to get the ip address from the `x-forwarded-for` header. If not available, it will use the remote address from the request.
-     */
-    ip?: string;
+    get ip(): string | undefined;
+    set ip(value: string | undefined);
     /**
      * The files of the request. Only available for multipart/form-data requests and if the file parser middleware is used.
      */
@@ -443,6 +446,31 @@ 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>;
+    /**
+     * Sets a lazy IP extractor function.
+     * IP will only be extracted when `.ip` is first accessed.
+     * @param req - The Node.js IncomingMessage
+     * @internal
+     */
+    setIpExtractor(req: IncomingMessage): void;
+    /**
+     * Sets a lazy IP extractor for Bun runtime.
+     * @internal
+     */
+    setBunIpExtractor(req: globalThis.Request, server: any): void;
+    /**
+     * Sets a lazy IP extractor for Deno runtime.
+     * @internal
+     */
+    setDenoIpExtractor(req: globalThis.Request, info: any): void;
+    /**
+     * Sets raw Node.js headers for lazy Headers construction.
+     * Avoids creating a Web API Headers object until first access.
+     * @param headers - Raw Node.js IncomingMessage headers
+     * @param needsFiltering - Whether HTTP/2 pseudo-header filtering is needed
+     * @internal
+     */
+    setRawHeaders(headers: IncomingMessage["headers"], needsFiltering: boolean): void;
     /**
      * Sets the Node.js IncomingMessage for lazy body reading.
      * Used internally by the Node.js server implementation.
@@ -1590,7 +1618,7 @@ declare class Router {
         body?: RequestSchema;
         query?: RequestSchema;
         all?: RequestSchema;
-    }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>): void;
+    }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>, allowUpdate?: boolean): void;
     /**
      * Find the matching route for the given HTTP method and path.
      * Returns the resolved middleware chain, handler, extracted params, and response schemas; or null if not found.
@@ -1752,7 +1780,11 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
     setNotFoundHandler(notFoundHandler?: ServerRouteHandler): void;
     beforeStart(hook: ServerHook): void;
     listen(cb?: ServerListenCallback): void;
-    waitUntilListening(): Promise<void>;
+    waitUntilListening(): Promise<{
+        port: number;
+        host: string;
+        url: string;
+    }>;
     /**
      * Closes the server and frees the port
      * This method is idempotent and can be called multiple times safely
@@ -2536,7 +2568,11 @@ interface ServerInterface {
      * 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<void>;
+    waitUntilListening: () => Promise<{
+        port: number;
+        host: string;
+        url: string;
+    }>;
     /**
      * Closes the server and frees the port
      * This method is idempotent and can be called multiple times safely

package/lib/index.d.ts

@@ -222,9 +222,10 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      */
     method: string;
     /**
-     * The headers of the request
+     * The headers of the request — lazily constructed from raw Node.js headers.
      */
-    headers: globalThis.Headers;
+    get headers(): globalThis.Headers;
+    set headers(value: globalThis.Headers);
     /**
      * The signal for aborting the request
      */
@@ -320,7 +321,7 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * The file of the request.
      * @fileParser middleware is required
      */
-    file: (fieldName: string) => FormFile | null;
+    file(fieldName: string): FormFile | null;
     /**
      * The cookies of the request.
      * @cookie middleware is required
@@ -330,7 +331,7 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * The cookie of the request.
      * @cookie middleware is required
      */
-    cookie: (name: string) => string | undefined;
+    cookie(name: string): string | undefined;
     /**
      * tells if the request has timed out.
      * @timeout middleware is required
@@ -342,6 +343,11 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @session middleware is required
      */
     session?: Record<string, any>;
+    /**
+     * Shared no-op async function to avoid per-instance closure allocation.
+     * @internal
+     */
+    private static readonly _noopAsync;
     /**
      * The session of the request. Uses cookies to send the session id
      * @cookie middleware is required
@@ -354,11 +360,8 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * @session middleware is required
      */
     destroySession: () => Promise<void>;
-    /**
-     * The ip address of the request.
-     * Tries to get the ip address from the `x-forwarded-for` header. If not available, it will use the remote address from the request.
-     */
-    ip?: string;
+    get ip(): string | undefined;
+    set ip(value: string | undefined);
     /**
      * The files of the request. Only available for multipart/form-data requests and if the file parser middleware is used.
      */
@@ -443,6 +446,31 @@ 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>;
+    /**
+     * Sets a lazy IP extractor function.
+     * IP will only be extracted when `.ip` is first accessed.
+     * @param req - The Node.js IncomingMessage
+     * @internal
+     */
+    setIpExtractor(req: IncomingMessage): void;
+    /**
+     * Sets a lazy IP extractor for Bun runtime.
+     * @internal
+     */
+    setBunIpExtractor(req: globalThis.Request, server: any): void;
+    /**
+     * Sets a lazy IP extractor for Deno runtime.
+     * @internal
+     */
+    setDenoIpExtractor(req: globalThis.Request, info: any): void;
+    /**
+     * Sets raw Node.js headers for lazy Headers construction.
+     * Avoids creating a Web API Headers object until first access.
+     * @param headers - Raw Node.js IncomingMessage headers
+     * @param needsFiltering - Whether HTTP/2 pseudo-header filtering is needed
+     * @internal
+     */
+    setRawHeaders(headers: IncomingMessage["headers"], needsFiltering: boolean): void;
     /**
      * Sets the Node.js IncomingMessage for lazy body reading.
      * Used internally by the Node.js server implementation.
@@ -1590,7 +1618,7 @@ declare class Router {
         body?: RequestSchema;
         query?: RequestSchema;
         all?: RequestSchema;
-    }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>): void;
+    }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>, allowUpdate?: boolean): void;
     /**
      * Find the matching route for the given HTTP method and path.
      * Returns the resolved middleware chain, handler, extracted params, and response schemas; or null if not found.
@@ -1752,7 +1780,11 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
     setNotFoundHandler(notFoundHandler?: ServerRouteHandler): void;
     beforeStart(hook: ServerHook): void;
     listen(cb?: ServerListenCallback): void;
-    waitUntilListening(): Promise<void>;
+    waitUntilListening(): Promise<{
+        port: number;
+        host: string;
+        url: string;
+    }>;
     /**
      * Closes the server and frees the port
      * This method is idempotent and can be called multiple times safely
@@ -2536,7 +2568,11 @@ interface ServerInterface {
      * 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<void>;
+    waitUntilListening: () => Promise<{
+        port: number;
+        host: string;
+        url: string;
+    }>;
     /**
      * Closes the server and frees the port
      * This method is idempotent and can be called multiple times safely