@fluojs/runtime 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/health/health.d.ts

@@ -1,18 +1,39 @@
 import type { ModuleType } from '../types.js';
+/**
+ * Describes the health status contract.
+ */
 export interface HealthStatus {
     status: 'ok' | 'unavailable';
 }
+/**
+ * Describes the health check response contract.
+ */
 export interface HealthCheckResponse {
     body: unknown;
     statusCode?: number;
 }
+/**
+ * Describes the readiness status contract.
+ */
 export interface ReadinessStatus {
     status: 'ready' | 'starting' | 'unavailable';
 }
+/**
+ * Describes the health module options contract.
+ */
 export interface HealthModuleOptions {
     healthCheck?: (ctx: import('@fluojs/http').RequestContext) => HealthStatus | HealthCheckResponse | Promise<HealthStatus | HealthCheckResponse>;
     path?: string;
 }
+/**
+ * Defines the readiness check type.
+ */
 export type ReadinessCheck = () => boolean | Promise<boolean>;
+/**
+ * Create health module.
+ *
+ * @param options The options.
+ * @returns The create health module result.
+ */
 export declare function createHealthModule(options?: HealthModuleOptions): ModuleType;
 //# sourceMappingURL=health.d.ts.map

package/dist/health/health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/health/health.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,IAAI,GAAG,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,cAAc,EAAE,cAAc,KACrD,YAAY,GACZ,mBAAmB,GACnB,OAAO,CAAC,YAAY,GAAG,mBAAmB,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9D,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CA0EhF"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/health/health.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,IAAI,GAAG,aAAa,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,cAAc,EAAE,cAAc,KACrD,YAAY,GACZ,mBAAmB,GACnB,OAAO,CAAC,YAAY,GAAG,mBAAmB,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CA0EhF"}

package/dist/health/health.js

@@ -5,6 +5,33 @@ function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.descrip
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { Controller, Get } from '@fluojs/http';
 import { defineModule } from '../bootstrap.js';
+
+/**
+ * Describes the health status contract.
+ */
+
+/**
+ * Describes the health check response contract.
+ */
+
+/**
+ * Describes the readiness status contract.
+ */
+
+/**
+ * Describes the health module options contract.
+ */
+
+/**
+ * Defines the readiness check type.
+ */
+
+/**
+ * Create health module.
+ *
+ * @param options The options.
+ * @returns The create health module result.
+ */
 export function createHealthModule(options = {}) {
   let _initProto, _initClass;
   const basePath = options.path ?? '';

package/dist/logging/json-logger.d.ts

@@ -1,3 +1,8 @@
 import type { ApplicationLogger } from '../types.js';
+/**
+ * Create json application logger.
+ *
+ * @returns The create json application logger result.
+ */
 export declare function createJsonApplicationLogger(): ApplicationLogger;
 //# sourceMappingURL=json-logger.d.ts.map

package/dist/logging/json-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-logger.d.ts","sourceRoot":"","sources":["../../src/logging/json-logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAqCrD,wBAAgB,2BAA2B,IAAI,iBAAiB,CAe/D"}
+{"version":3,"file":"json-logger.d.ts","sourceRoot":"","sources":["../../src/logging/json-logger.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAqCrD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,iBAAiB,CAe/D"}

package/dist/logging/json-logger.js

@@ -21,6 +21,12 @@ function buildEntry(level, message, context, error) {
   }
   return entry;
 }
+
+/**
+ * Create json application logger.
+ *
+ * @returns The create json application logger result.
+ */
 export function createJsonApplicationLogger() {
   return {
     debug(message, context) {

package/dist/logging/logger.d.ts

@@ -1,3 +1,8 @@
 import type { ApplicationLogger } from '../types.js';
+/**
+ * Create console application logger.
+ *
+ * @returns The create console application logger result.
+ */
 export declare function createConsoleApplicationLogger(): ApplicationLogger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAuBrD,wBAAgB,8BAA8B,IAAI,iBAAiB,CAmBlE"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAuBrD;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,iBAAiB,CAmBlE"}

package/dist/logging/logger.js

@@ -15,6 +15,12 @@ function formatLog(level, context, message, color) {
   const contextLabel = colorize(`[${context}]`, BRIGHT_YELLOW, color);
   return `${prefix} ${pid} - ${timestamp} ${levelLabel} ${contextLabel} ${message}`;
 }
+
+/**
+ * Create console application logger.
+ *
+ * @returns The create console application logger result.
+ */
 export function createConsoleApplicationLogger() {
   return {
     debug(message, context = 'fluo') {

package/dist/module-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-graph.d.ts","sourceRoot":"","sources":["../src/module-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAK1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAMvD;AAyDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,QAAQ,EAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAE5E;AAyTD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,cAAc,EAAE,CASjH"}
+{"version":3,"file":"module-graph.d.ts","sourceRoot":"","sources":["../src/module-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAK1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAMvD;AAyDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,QAAQ,EAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAE5E;AA8UD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,cAAc,EAAE,CASjH"}

package/dist/module-graph.js

@@ -132,7 +132,9 @@ function compileModule(moduleType, runtimeProviderTokens, compiled = new Map(),
   const compiledModule = {
     type: moduleType,
     definition,
+    accessibleTokens: new Set(),
     exportedTokens: new Set(),
+    importedExportedTokens: new Set(),
     providerTokens
   };
   compiled.set(moduleType, compiledModule);
@@ -154,11 +156,21 @@ function resolveImportedModules(compiledModule, compiledByType) {
   });
 }
 function createImportedExportedTokenSet(importedModules) {
-  return new Set(importedModules.flatMap(imported => Array.from(imported.exportedTokens)));
+  const importedExportedTokens = new Set();
+  for (const importedModule of importedModules) {
+    for (const token of importedModule.exportedTokens) {
+      importedExportedTokens.add(token);
+    }
+  }
+  return importedExportedTokens;
 }
 function createAccessibleTokenSet(runtimeProviderTokens, moduleProviderTokens, importedExportedTokens, globalExportedTokens) {
   return new Set([...runtimeProviderTokens, ...moduleProviderTokens, ...importedExportedTokens, ...globalExportedTokens]);
 }
+function memoizeAccessibleTokenSet(compiledModule, importedModules, runtimeProviderTokens, globalExportedTokens) {
+  compiledModule.importedExportedTokens = createImportedExportedTokenSet(importedModules);
+  compiledModule.accessibleTokens = createAccessibleTokenSet(runtimeProviderTokens, compiledModule.providerTokens, compiledModule.importedExportedTokens, globalExportedTokens);
+}
 function validateProviderVisibility(compiledModule, scope, accessibleTokens) {
   for (const provider of compiledModule.definition.providers ?? []) {
     validateProviderInjectionMetadata(provider, scope);
@@ -222,12 +234,10 @@ function validateCompiledModules(modules, runtimeProviders, runtimeProviderToken
   }
   for (const compiledModule of modules) {
     const scope = `module ${compiledModule.type.name}`;
-    const importedModules = resolveImportedModules(compiledModule, compiledByType);
-    const importedExportedTokens = createImportedExportedTokenSet(importedModules);
-    const accessibleTokens = createAccessibleTokenSet(runtimeProviderTokens, compiledModule.providerTokens, importedExportedTokens, globalExportedTokens);
-    validateProviderVisibility(compiledModule, scope, accessibleTokens);
-    validateControllerVisibility(compiledModule, scope, accessibleTokens);
-    compiledModule.exportedTokens = createExportedTokenSet(compiledModule, importedExportedTokens);
+    memoizeAccessibleTokenSet(compiledModule, resolveImportedModules(compiledModule, compiledByType), runtimeProviderTokens, globalExportedTokens);
+    validateProviderVisibility(compiledModule, scope, compiledModule.accessibleTokens);
+    validateControllerVisibility(compiledModule, scope, compiledModule.accessibleTokens);
+    compiledModule.exportedTokens = createExportedTokenSet(compiledModule, compiledModule.importedExportedTokens);
   }
 }
 

package/dist/node/internal-node-compression.d.ts

@@ -1,7 +1,22 @@
 import type { ServerResponse } from 'node:http';
 import type { FrameworkResponseCompression } from '@fluojs/http';
 type Encoding = 'br' | 'gzip' | 'identity';
+/**
+ * Create node response compression.
+ *
+ * @param response The response.
+ * @param acceptEncoding The accept encoding.
+ * @returns The create node response compression result.
+ */
 export declare function createNodeResponseCompression(response: ServerResponse, acceptEncoding: string | undefined): FrameworkResponseCompression | undefined;
+/**
+ * Compress node response.
+ *
+ * @param response The response.
+ * @param body The body.
+ * @param encoding The encoding.
+ * @returns The compress node response result.
+ */
 export declare function compressNodeResponse(response: ServerResponse, body: Uint8Array, encoding: Exclude<Encoding, 'identity'>): Promise<void>;
 export {};
 //# sourceMappingURL=internal-node-compression.d.ts.map

package/dist/node/internal-node-compression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-node-compression.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-compression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,cAAc,CAAC;AAiBtB,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3C,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,cAAc,EACxB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,4BAA4B,GAAG,SAAS,CAqB1C;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"internal-node-compression.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-compression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,cAAc,CAAC;AAiBtB,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,cAAc,EACxB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,4BAA4B,GAAG,SAAS,CAqB1C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/node/internal-node-compression.js

@@ -1,6 +1,13 @@
 import { createBrotliCompress, createGzip } from 'node:zlib';
 const COMPRESS_THRESHOLD = 1024;
 const SKIP_CONTENT_TYPES = new Set(['image/', 'audio/', 'video/', 'application/zip', 'application/gzip', 'application/x-bzip', 'application/x-bzip2', 'application/x-xz', 'application/zstd', 'application/octet-stream']);
+/**
+ * Create node response compression.
+ *
+ * @param response The response.
+ * @param acceptEncoding The accept encoding.
+ * @returns The create node response compression result.
+ */
 export function createNodeResponseCompression(response, acceptEncoding) {
   if (!acceptEncoding) {
     return undefined;
@@ -19,6 +26,15 @@ export function createNodeResponseCompression(response, acceptEncoding) {
     }
   };
 }
+
+/**
+ * Compress node response.
+ *
+ * @param response The response.
+ * @param body The body.
+ * @param encoding The encoding.
+ * @returns The compress node response result.
+ */
 export function compressNodeResponse(response, body, encoding) {
   const stream = encoding === 'br' ? createBrotliCompress() : createGzip();
   response.setHeader('Content-Encoding', encoding);

package/dist/node/internal-node-request.d.ts

@@ -1,6 +1,9 @@
 import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
 import { PayloadTooLargeException, type FrameworkRequest } from '@fluojs/http';
 import { type MultipartOptions } from '../multipart.js';
+/**
+ * HTTP payload-size error that closes the underlying Node request stream after the response commits.
+ */
 export declare class NodeRequestPayloadTooLargeException extends PayloadTooLargeException {
     private readonly request;
     constructor(request: IncomingMessage);
@@ -17,6 +20,24 @@ export declare class NodeRequestPayloadTooLargeException extends PayloadTooLarge
  * @returns The normalized framework request used by the dispatcher.
  */
 export declare function createFrameworkRequest(request: IncomingMessage, signal: AbortSignal, multipartOptions?: MultipartOptions, maxBodySize?: number, preserveRawBody?: boolean): Promise<FrameworkRequest>;
+/**
+ * Creates the cheap Node framework request shell before consuming the body stream.
+ *
+ * @param request - Raw Node request carrying headers, URL, and body stream.
+ * @param signal - Abort signal tied to the response lifecycle.
+ * @param multipartOptions - Multipart parser options applied when materializing multipart requests.
+ * @param maxBodySize - Maximum allowed non-multipart body size in bytes.
+ * @param preserveRawBody - Whether materialization should retain raw request body bytes.
+ * @returns The framework request shell with metadata snapshotted and body materialization deferred.
+ */
+export declare function createDeferredFrameworkRequest(request: IncomingMessage, signal: AbortSignal, multipartOptions?: MultipartOptions, maxBodySize?: number, preserveRawBody?: boolean): FrameworkRequest;
+/**
+ * Materializes a deferred Node framework request body exactly once.
+ *
+ * @param request - Framework request returned by {@link createDeferredFrameworkRequest}.
+ * @returns A promise that settles after body, rawBody, and files fields are populated when applicable.
+ */
+export declare function materializeFrameworkRequestBody(request: FrameworkRequest): Promise<void>;
 /**
  * Creates an abort signal that fires when the Node response closes unexpectedly.
  *

package/dist/node/internal-node-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-node-request.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EACf,cAAc,EACf,MAAM,WAAW,CAAC;AAInB,OAAO,EAEL,wBAAwB,EACxB,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAOzB,qBAAa,mCAAoC,SAAQ,wBAAwB;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe;IAIrD,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;CAahD;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,EACnB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,SAAkB,EAC7B,eAAe,UAAQ,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAqD3B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,WAAW,CAezE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAG5F"}
+{"version":3,"file":"internal-node-request.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EACf,cAAc,EACf,MAAM,WAAW,CAAC;AAInB,OAAO,EAEL,wBAAwB,EACxB,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAUzB;;GAEG;AACH,qBAAa,mCAAoC,SAAQ,wBAAwB;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe;IAIrD,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;CAahD;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,EACnB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,SAAkB,EAC7B,eAAe,UAAQ,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAW3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,EACnB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,SAAkB,EAC7B,eAAe,UAAQ,GACtB,gBAAgB,CA2DlB;AAoBD;;;;;GAKG;AACH,wBAAsB,+BAA+B,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9F;AAyBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,WAAW,CAezE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAG5F"}

package/dist/node/internal-node-request.js

@@ -2,6 +2,9 @@ import { Readable } from 'node:stream';
 import { URL } from 'node:url';
 import { BadRequestException, PayloadTooLargeException } from '@fluojs/http';
 import { parseMultipart } from '../multipart.js';
+/**
+ * HTTP payload-size error that closes the underlying Node request stream after the response commits.
+ */
 export class NodeRequestPayloadTooLargeException extends PayloadTooLargeException {
   constructor(request) {
     super('Request body exceeds the size limit.');
@@ -31,49 +34,114 @@ export class NodeRequestPayloadTooLargeException extends PayloadTooLargeExceptio
  * @returns The normalized framework request used by the dispatcher.
  */
 export async function createFrameworkRequest(request, signal, multipartOptions, maxBodySize = 1 * 1024 * 1024, preserveRawBody = false) {
+  const frameworkRequest = createDeferredFrameworkRequest(request, signal, multipartOptions, maxBodySize, preserveRawBody);
+  await materializeFrameworkRequestBody(frameworkRequest);
+  return frameworkRequest;
+}
+
+/**
+ * Creates the cheap Node framework request shell before consuming the body stream.
+ *
+ * @param request - Raw Node request carrying headers, URL, and body stream.
+ * @param signal - Abort signal tied to the response lifecycle.
+ * @param multipartOptions - Multipart parser options applied when materializing multipart requests.
+ * @param maxBodySize - Maximum allowed non-multipart body size in bytes.
+ * @param preserveRawBody - Whether materialization should retain raw request body bytes.
+ * @returns The framework request shell with metadata snapshotted and body materialization deferred.
+ */
+export function createDeferredFrameworkRequest(request, signal, multipartOptions, maxBodySize = 1 * 1024 * 1024, preserveRawBody = false) {
   const url = new URL(request.url ?? '/', 'http://localhost');
   const headers = cloneRequestHeaders(request.headers);
+  const cookieHeader = cloneHeaderValue(headers.cookie);
+  const searchParams = new URLSearchParams(url.searchParams);
+  const cookies = createMemoizedValue(() => parseCookieHeader(cookieHeader));
+  const query = createMemoizedValue(() => parseQueryParams(searchParams));
   const contentType = readPrimaryHeaderValue(headers['content-type']);
   const isMultipart = typeof contentType === 'string' && contentType.includes('multipart/form-data');
-  let body;
-  let files;
-  let rawBody;
-  if (isMultipart) {
-    const result = await parseMultipart({
-      body: Readable.toWeb(request),
-      headers,
-      method: request.method,
-      url: url.toString()
-    }, {
-      ...multipartOptions,
-      maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
-    });
-    body = result.fields;
-    files = result.files;
-  } else {
+  const materializeBody = createMemoizedAsyncValue(async () => {
+    if (isMultipart) {
+      const result = await parseMultipart({
+        body: Readable.toWeb(request),
+        headers,
+        method: request.method,
+        url: url.toString()
+      }, {
+        ...multipartOptions,
+        maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
+      });
+      frameworkRequest.body = result.fields;
+      frameworkRequest.files = result.files;
+      return;
+    }
+    if (!hasNodeRequestBody(request)) {
+      frameworkRequest.body = undefined;
+      return;
+    }
     const bodyResult = await readRequestBody(request, headers['content-type'], maxBodySize, preserveRawBody);
-    body = bodyResult.body;
-    rawBody = bodyResult.rawBody;
-  }
+    frameworkRequest.body = bodyResult.body;
+    if (bodyResult.rawBody) {
+      frameworkRequest.rawBody = bodyResult.rawBody;
+    }
+  });
   const frameworkRequest = {
-    body,
-    cookies: parseCookieHeader(headers.cookie),
+    get cookies() {
+      return cookies();
+    },
     headers,
     method: request.method ?? 'GET',
     params: {},
     path: url.pathname,
-    query: parseQueryParams(url.searchParams),
+    get query() {
+      return query();
+    },
     raw: request,
     signal,
-    url: url.pathname + url.search
+    url: url.pathname + url.search,
+    materializeBody
   };
-  if (files) {
-    frameworkRequest.files = files;
+  return frameworkRequest;
+}
+function hasNodeRequestBody(request) {
+  const contentLength = request.headers['content-length'];
+  const transferEncoding = request.headers['transfer-encoding'];
+  const primaryContentLength = Array.isArray(contentLength) ? contentLength[0] : contentLength;
+  if (transferEncoding !== undefined) {
+    return true;
   }
-  if (rawBody) {
-    frameworkRequest.rawBody = rawBody;
+  if (primaryContentLength === undefined) {
+    return true;
   }
-  return frameworkRequest;
+  const parsedContentLength = Number(primaryContentLength);
+  return !Number.isFinite(parsedContentLength) || parsedContentLength !== 0;
+}
+
+/**
+ * Materializes a deferred Node framework request body exactly once.
+ *
+ * @param request - Framework request returned by {@link createDeferredFrameworkRequest}.
+ * @returns A promise that settles after body, rawBody, and files fields are populated when applicable.
+ */
+export async function materializeFrameworkRequestBody(request) {
+  await request.materializeBody?.();
+  delete request.materializeBody;
+}
+function createMemoizedValue(factory) {
+  let initialized = false;
+  let value;
+  return () => {
+    if (!initialized) {
+      value = factory();
+      initialized = true;
+    }
+    return value;
+  };
+}
+function createMemoizedAsyncValue(factory) {
+  let promise;
+  return () => {
+    promise ??= factory();
+    return promise;
+  };
 }
 
 /**
@@ -124,9 +192,12 @@ function parseQueryParams(searchParams) {
   return query;
 }
 function cloneRequestHeaders(headers) {
-  const clonedEntries = Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? [...value] : value]);
+  const clonedEntries = Object.entries(headers).map(([name, value]) => [name, cloneHeaderValue(value)]);
   return Object.fromEntries(clonedEntries);
 }
+function cloneHeaderValue(value) {
+  return Array.isArray(value) ? [...value] : value;
+}
 function readPrimaryHeaderValue(headerValue) {
   if (Array.isArray(headerValue)) {
     return headerValue[0];

package/dist/node/internal-node-response.d.ts

@@ -1,8 +1,28 @@
 import type { ServerResponse } from 'node:http';
 import { type FrameworkResponseCompression, type FrameworkResponse } from '@fluojs/http';
+/**
+ * Defines the mutable framework response type.
+ */
 export type MutableFrameworkResponse = FrameworkResponse & {
     statusSet?: boolean;
 };
-export declare function createFrameworkResponse(response: ServerResponse, compression?: FrameworkResponseCompression): MutableFrameworkResponse;
+type FrameworkResponseCompressionFactory = () => FrameworkResponseCompression | undefined;
+/**
+ * Create framework response.
+ *
+ * @param response The response.
+ * @param compression The compression.
+ * @returns The create framework response result.
+ */
+export declare function createFrameworkResponse(response: ServerResponse, compression?: FrameworkResponseCompression | FrameworkResponseCompressionFactory): MutableFrameworkResponse;
+/**
+ * Write node adapter error response.
+ *
+ * @param error The error.
+ * @param response The response.
+ * @param requestId The request id.
+ * @returns The write node adapter error response result.
+ */
 export declare function writeNodeAdapterErrorResponse(error: unknown, response: FrameworkResponse, requestId?: string): Promise<void>;
+export {};
 //# sourceMappingURL=internal-node-response.d.ts.map

package/dist/node/internal-node-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-node-response.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAIL,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EAEvB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,wBAAwB,GAAG,iBAAiB,GAAG;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA6CnF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,WAAW,CAAC,EAAE,4BAA4B,GACzC,wBAAwB,CA+F1B;AAED,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"internal-node-response.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAIL,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EAEvB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,iBAAiB,GAAG;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnF,KAAK,mCAAmC,GAAG,MAAM,4BAA4B,GAAG,SAAS,CAAC;AA6C1F;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,WAAW,CAAC,EAAE,4BAA4B,GAAG,mCAAmC,GAC/E,wBAAwB,CAqH1B;AAED;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/node/internal-node-response.js

@@ -1,4 +1,9 @@
 import { createErrorResponse, HttpException, InternalServerErrorException } from '@fluojs/http';
+
+/**
+ * Defines the mutable framework response type.
+ */
+
 function createFrameworkResponseStream(response) {
   return {
     close() {
@@ -39,7 +44,28 @@ function createFrameworkResponseStream(response) {
     }
   };
 }
+
+/**
+ * Create framework response.
+ *
+ * @param response The response.
+ * @param compression The compression.
+ * @returns The create framework response result.
+ */
 export function createFrameworkResponse(response, compression) {
+  let activeStream;
+  const resolveCompression = (() => {
+    const factory = typeof compression === 'function' ? compression : () => compression;
+    let resolved = false;
+    let value;
+    return () => {
+      if (!resolved) {
+        value = factory();
+        resolved = true;
+      }
+      return value;
+    };
+  })();
   const mergeSetCookieHeader = (current, incoming) => {
     const nextValues = Array.isArray(incoming) ? incoming : [incoming];
     if (current === undefined) {
@@ -56,7 +82,10 @@ export function createFrameworkResponse(response, compression) {
     committed: response.headersSent || response.writableEnded,
     headers: {},
     raw: response,
-    stream: createFrameworkResponseStream(response),
+    get stream() {
+      activeStream ??= createFrameworkResponseStream(response);
+      return activeStream;
+    },
     redirect(status, location) {
       this.setStatus(status);
       this.setHeader('Location', location);
@@ -74,9 +103,10 @@ export function createFrameworkResponse(response, compression) {
       }
       const contentType = response.getHeader('Content-Type');
       const payload = typeof serialized.payload === 'string' ? Buffer.from(serialized.payload, 'utf8') : serialized.payload;
-      if (compression) {
+      const activeCompression = resolveCompression();
+      if (activeCompression) {
         this.committed = true;
-        return Promise.resolve(compression.write(payload, {
+        return Promise.resolve(activeCompression.write(payload, {
           contentType
         })).then(handled => {
           if (!handled && !response.writableEnded) {
@@ -113,6 +143,15 @@ export function createFrameworkResponse(response, compression) {
   };
   return frameworkResponse;
 }
+
+/**
+ * Write node adapter error response.
+ *
+ * @param error The error.
+ * @param response The response.
+ * @param requestId The request id.
+ * @returns The write node adapter error response result.
+ */
 export async function writeNodeAdapterErrorResponse(error, response, requestId) {
   const httpError = toHttpException(error);
   response.setStatus(httpError.status);

package/dist/node/internal-node.d.ts

@@ -11,6 +11,9 @@ declare module '@fluojs/http' {
         rawBody?: Uint8Array;
     }
 }
+/**
+ * Describes the node http adapter options contract.
+ */
 export interface NodeHttpAdapterOptions {
     host?: string;
     https?: HttpsServerOptions;
@@ -21,8 +24,17 @@ export interface NodeHttpAdapterOptions {
     retryLimit?: number;
     shutdownTimeoutMs?: number;
 }
+/**
+ * Defines the node application signal type.
+ */
 export type NodeApplicationSignal = 'SIGINT' | 'SIGTERM';
+/**
+ * Defines the cors input type.
+ */
 export type CorsInput = false | string | string[] | CorsOptions;
+/**
+ * Describes the bootstrap node application options contract.
+ */
 export interface BootstrapNodeApplicationOptions extends Omit<CreateApplicationOptions, 'adapter' | 'logger' | 'middleware'> {
     compression?: boolean;
     cors?: CorsInput;
@@ -41,6 +53,9 @@ export interface BootstrapNodeApplicationOptions extends Omit<CreateApplicationO
     securityHeaders?: false | SecurityHeadersOptions;
     shutdownTimeoutMs?: number;
 }
+/**
+ * Describes the run node application options contract.
+ */
 export interface RunNodeApplicationOptions extends BootstrapNodeApplicationOptions {
     forceExitTimeoutMs?: number;
     shutdownSignals?: false | readonly NodeApplicationSignal[];
@@ -50,6 +65,9 @@ interface NodeListenTarget {
     url: string;
 }
 type NodeServer = ReturnType<typeof createHttpServer> | ReturnType<typeof createHttpsServer>;
+/**
+ * Represents the node http application adapter.
+ */
 export declare class NodeHttpApplicationAdapter implements HttpApplicationAdapter {
     private readonly port;
     private readonly host;
@@ -73,8 +91,30 @@ export declare class NodeHttpApplicationAdapter implements HttpApplicationAdapte
     close(): Promise<void>;
     private handleRequest;
 }
+/**
+ * Create node http adapter.
+ *
+ * @param options The options.
+ * @param compression The compression.
+ * @param multipartOptions The multipart options.
+ * @returns The create node http adapter result.
+ */
 export declare function createNodeHttpAdapter(options?: NodeHttpAdapterOptions, compression?: boolean, multipartOptions?: MultipartOptions): HttpApplicationAdapter;
+/**
+ * Bootstrap node application.
+ *
+ * @param rootModule The root module.
+ * @param options The options.
+ * @returns The bootstrap node application result.
+ */
 export declare function bootstrapNodeApplication(rootModule: ModuleType, options: BootstrapNodeApplicationOptions): Promise<Application>;
+/**
+ * Run node application.
+ *
+ * @param rootModule The root module.
+ * @param options The options.
+ * @returns The run node application result.
+ */
 export declare function runNodeApplication(rootModule: ModuleType, options: RunNodeApplicationOptions): Promise<Application>;
 export { compressNodeResponse, createNodeResponseCompression, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals, registerShutdownSignals, };
 //# sourceMappingURL=internal-node.d.ts.map