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

package/README.ko.md

@@ -115,7 +115,7 @@ stream(_input: undefined, ctx: RequestContext) {
 
 ## 요청 정리와 런타임 이식성
 
-디스패처는 활성 dispatch 동안에만 `AsyncLocalStorage`로 `RequestContext`를 바인딩하고, 요청 observer가 끝난 뒤 `finally` 경로에서 request-scoped DI 컨테이너를 dispose합니다. 이 동작은 정상 성공, 처리된 오류, 중단된 요청 경로에서 request-scoped provider가 다음 요청으로 새지 않게 합니다.
+디스패처는 활성 dispatch 동안에만 `AsyncLocalStorage`로 `RequestContext`를 바인딩합니다. 요청이 controller graph, middleware, guard, interceptor, observer, DTO converter, custom binder 또는 수동 `getCurrentRequestContext()` / `assertRequestContext()` container 접근을 통해 request-scoped DI를 사용할 수 있으면, 디스패처는 요청 observer가 끝난 뒤 `finally` 경로에서 isolated request-scoped DI 컨테이너를 생성하고 dispose합니다. Singleton-only route는 `RequestContext.container`가 접근되기 전까지 이 컨테이너 lifecycle을 건너뛰어 baseline 경로의 불필요한 per-request allocation을 피하면서도, graph가 모호하거나 request-scoped이면 request-scoped provider isolation을 유지합니다. 따라서 공개 `RequestContext.container` 읽기는 request-scoped provider resolve에 항상 안전합니다. singleton-only fast path는 내부 dispatcher 최적화일 뿐, 공개 context가 root container를 노출한다는 약속이 아닙니다.
 
 어댑터는 플랫폼이 제공한다면 `FrameworkRequest.signal`에 `AbortSignal`을 전달해야 합니다. SSE에서는 가능하면 `FrameworkResponse.stream.onClose(...)`도 노출해야 합니다. `SseResponse`는 request abort와 raw stream close를 모두 구독하고, 멱등하게 닫히며, 어느 쪽이 먼저 종료되더라도 등록한 listener를 제거합니다.
 
@@ -133,6 +133,9 @@ stream(_input: undefined, ctx: RequestContext) {
 `./internal` 서브경로는 플랫폼 어댑터와 핵심 런타임에서 사용하는 저수준 유틸리티만 내보냅니다. 이들은 변경될 수 있으며 일반적인 애플리케이션 코드에서 사용해서는 안 됩니다.
 
 - `DefaultBinder`: 런타임 부트스트랩 경로에서 사용하는 기본 DTO/요청 바인더.
+- `bindRawRequestNativeRouteHandoff(...)` / `attachFrameworkRequestNativeRouteHandoff(...)`: public dispatcher API를 넓히지 않고 의미 보존이 가능한 native route match를 재사용하기 위한 내부 adapter/runtime 헬퍼.
+- Native route handoff는 framework request에 붙는 시점의 method와 path를 함께 스냅샷합니다. app middleware가 handler matching 전에 둘 중 하나를 rewrite하면 dispatcher는 stale handoff를 무시하고 일반 route matching으로 fallback합니다.
+- `isRoutePathNormalizationSensitive(path)`: duplicate slash와 trailing slash 요청을 generic dispatcher 경로에 남기기 위한 내부 guard.
 - `resolveClientIdentity(request)`: 속도 제한과 런타임 통합에서 사용하는 보수적 클라이언트 식별 해석기.
 
 ## 관련 패키지

package/README.md

@@ -117,7 +117,7 @@ stream(_input: undefined, ctx: RequestContext) {
 
 ## Request Cleanup and Portability
 
-The dispatcher binds `RequestContext` with `AsyncLocalStorage` for the active dispatch only and disposes the request-scoped DI container from its `finally` path after request observers finish. This keeps per-request providers from leaking across normal success, handled error, and aborted request paths.
+The dispatcher binds `RequestContext` with `AsyncLocalStorage` for the active dispatch only. When a request may use request-scoped DI through its controller graph, middleware, guards, interceptors, observers, DTO converters, a custom binder, or manual `getCurrentRequestContext()` / `assertRequestContext()` container access, the dispatcher creates and disposes an isolated request-scoped DI container from its `finally` path after request observers finish. Singleton-only routes skip that container lifecycle until `RequestContext.container` is accessed, so the baseline path avoids unnecessary per-request allocation while preserving request-scoped provider isolation whenever the graph is ambiguous or request-scoped. Public `RequestContext.container` reads are therefore always safe for resolving request-scoped providers; the singleton-only fast path is an internal dispatcher optimization, not a promise that the public context exposes the root container.
 
 Adapters should pass an `AbortSignal` on `FrameworkRequest.signal` when the platform exposes one. For SSE, adapters should also expose `FrameworkResponse.stream.onClose(...)` when possible; `SseResponse` listens to both request abort and raw stream close, closes idempotently, and removes registered listeners when either side terminates first.
 
@@ -135,6 +135,9 @@ Adapters should pass an `AbortSignal` on `FrameworkRequest.signal` when the plat
 The `./internal` subpath exports only the low-level utilities used by platform adapters and the core runtime. These are subject to change and should not be used in typical application code.
 
 - `DefaultBinder`: Default DTO/request binder used by the runtime bootstrap path.
+- `bindRawRequestNativeRouteHandoff(...)` / `attachFrameworkRequestNativeRouteHandoff(...)`: Internal adapter/runtime helpers for reusing semantically safe native route matches without widening the public dispatcher API.
+- Native route handoffs snapshot the framework request method and path when attached; if app middleware rewrites either value before handler matching, the dispatcher ignores the stale handoff and falls back to normal route matching.
+- `isRoutePathNormalizationSensitive(path)`: Internal guard for keeping duplicate-slash and trailing-slash requests on the generic dispatcher path.
 - `resolveClientIdentity(request)`: Conservative client identity resolver used by rate limiting and other runtime integrations.
 
 ## Related Packages

package/dist/adapter.d.ts

@@ -1,14 +1,23 @@
 import type { MaybePromise } from '@fluojs/core';
 import type { Dispatcher } from './types.js';
+/**
+ * Describes the server backed http adapter realtime capability contract.
+ */
 export interface ServerBackedHttpAdapterRealtimeCapability {
     kind: 'server-backed';
     server: unknown;
 }
+/**
+ * Describes the unsupported http adapter realtime capability contract.
+ */
 export interface UnsupportedHttpAdapterRealtimeCapability {
     kind: 'unsupported';
     mode: 'no-op';
     reason: string;
 }
+/**
+ * Describes the fetch style http adapter realtime capability contract.
+ */
 export interface FetchStyleHttpAdapterRealtimeCapability {
     contract: 'raw-websocket-expansion';
     kind: 'fetch-style';
@@ -17,9 +26,31 @@ export interface FetchStyleHttpAdapterRealtimeCapability {
     support: 'contract-only' | 'supported';
     version: 1;
 }
+/**
+ * Defines the http adapter realtime capability type.
+ */
 export type HttpAdapterRealtimeCapability = ServerBackedHttpAdapterRealtimeCapability | FetchStyleHttpAdapterRealtimeCapability | UnsupportedHttpAdapterRealtimeCapability;
+/**
+ * Create server backed http adapter realtime capability.
+ *
+ * @param server The server.
+ * @returns The create server backed http adapter realtime capability result.
+ */
 export declare function createServerBackedHttpAdapterRealtimeCapability(server: unknown): ServerBackedHttpAdapterRealtimeCapability;
+/**
+ * Create unsupported http adapter realtime capability.
+ *
+ * @param reason The reason.
+ * @returns The create unsupported http adapter realtime capability result.
+ */
 export declare function createUnsupportedHttpAdapterRealtimeCapability(reason: string): UnsupportedHttpAdapterRealtimeCapability;
+/**
+ * Create fetch style http adapter realtime capability.
+ *
+ * @param reason The reason.
+ * @param options The options.
+ * @returns The create fetch style http adapter realtime capability result.
+ */
 export declare function createFetchStyleHttpAdapterRealtimeCapability(reason: string, options?: {
     support?: FetchStyleHttpAdapterRealtimeCapability['support'];
 }): FetchStyleHttpAdapterRealtimeCapability;

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,yCAAyC;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,wCAAwC;IACvD,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uCAAuC;IACtD,QAAQ,EAAE,yBAAyB,CAAC;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,GAAG,WAAW,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC;CACZ;AAED,MAAM,MAAM,6BAA6B,GACrC,yCAAyC,GACzC,uCAAuC,GACvC,wCAAwC,CAAC;AAE7C,wBAAgB,+CAA+C,CAC7D,MAAM,EAAE,OAAO,GACd,yCAAyC,CAK3C;AAED,wBAAgB,8CAA8C,CAC5D,MAAM,EAAE,MAAM,GACb,wCAAwC,CAM1C;AAED,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;CACzD,GACL,uCAAuC,CASzC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC;IAEtB,qBAAqB,CAAC,IAAI,6BAA6B,CAAC;IAExD;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,IAAI,sBAAsB,CAUzE"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,yCAAyC;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wCAAwC;IACvD,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uCAAuC;IACtD,QAAQ,EAAE,yBAAyB,CAAC;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,GAAG,WAAW,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GACrC,yCAAyC,GACzC,uCAAuC,GACvC,wCAAwC,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,+CAA+C,CAC7D,MAAM,EAAE,OAAO,GACd,yCAAyC,CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,8CAA8C,CAC5D,MAAM,EAAE,MAAM,GACb,wCAAwC,CAM1C;AAED;;;;;;GAMG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;CACzD,GACL,uCAAuC,CASzC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC;IAEtB,qBAAqB,CAAC,IAAI,6BAA6B,CAAC;IAExD;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,IAAI,sBAAsB,CAUzE"}

package/dist/adapter.js

@@ -1,9 +1,38 @@
+/**
+ * Describes the server backed http adapter realtime capability contract.
+ */
+
+/**
+ * Describes the unsupported http adapter realtime capability contract.
+ */
+
+/**
+ * Describes the fetch style http adapter realtime capability contract.
+ */
+
+/**
+ * Defines the http adapter realtime capability type.
+ */
+
+/**
+ * Create server backed http adapter realtime capability.
+ *
+ * @param server The server.
+ * @returns The create server backed http adapter realtime capability result.
+ */
 export function createServerBackedHttpAdapterRealtimeCapability(server) {
   return {
     kind: 'server-backed',
     server
   };
 }
+
+/**
+ * Create unsupported http adapter realtime capability.
+ *
+ * @param reason The reason.
+ * @returns The create unsupported http adapter realtime capability result.
+ */
 export function createUnsupportedHttpAdapterRealtimeCapability(reason) {
   return {
     kind: 'unsupported',
@@ -11,6 +40,14 @@ export function createUnsupportedHttpAdapterRealtimeCapability(reason) {
     reason
   };
 }
+
+/**
+ * Create fetch style http adapter realtime capability.
+ *
+ * @param reason The reason.
+ * @param options The options.
+ * @returns The create fetch style http adapter realtime capability result.
+ */
 export function createFetchStyleHttpAdapterRealtimeCapability(reason, options = {}) {
   return {
     contract: 'raw-websocket-expansion',

package/dist/adapters/binding.d.ts

@@ -1,8 +1,14 @@
 import { type Constructor } from '@fluojs/core';
 import type { ArgumentResolverContext, Binder, Converter, ConverterLike, ConverterTarget } from '../types.js';
+/**
+ * Represents the default converter.
+ */
 export declare class DefaultConverter implements Converter {
     convert(value: unknown, _target: ConverterTarget): unknown;
 }
+/**
+ * Represents the default binder.
+ */
 export declare class DefaultBinder implements Binder {
     private readonly converters;
     constructor(converters?: readonly ConverterLike[]);

package/dist/adapters/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAA6D,MAAM,cAAc,CAAC;AAK3H,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AA4FhI,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAyDD,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,GAAE,SAAS,aAAa,EAAO;IAEhE,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;CA0EjF"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAI5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AAiDhI;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAyDD;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,GAAE,SAAS,aAAa,EAAO;IAEhE,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;CA+DjF"}

package/dist/adapters/binding.js

@@ -1,7 +1,7 @@
 import { InvariantError } from '@fluojs/core';
-import { getDtoBindingSchema } from '@fluojs/core/internal';
 import { BadRequestException } from '../exceptions.js';
 import { toInputErrorDetail } from '../input-error-detail.js';
+import { getCompiledDtoBindingPlan } from './dto-binding-plan.js';
 const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function isPlainObject(value) {
   if (typeof value !== 'object' || value === null) {
@@ -10,44 +10,6 @@ function isPlainObject(value) {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
-function toFieldName(propertyKey) {
-  return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
-}
-function resolveSourceKey(propertyKey, key) {
-  return key ?? toFieldName(propertyKey);
-}
-function readHeader(request, key) {
-  return request.headers[key.toLowerCase()] ?? request.headers[key];
-}
-function readSourceValue(request, source, propertyKey, key) {
-  const resolvedKey = resolveSourceKey(propertyKey, key);
-  switch (source) {
-    case 'path':
-      return request.params[resolvedKey];
-    case 'query':
-      return request.query[resolvedKey];
-    case 'header':
-      return readHeader(request, resolvedKey);
-    case 'cookie':
-      return request.cookies[resolvedKey];
-    case 'body':
-      {
-        if (!isPlainObject(request.body)) {
-          if (request.body !== undefined && request.body !== null) {
-            throw new BadRequestException('Request body must be a plain object.', {
-              details: [toInputErrorDetail({
-                code: 'INVALID_BODY',
-                message: 'Request body must be a plain object.',
-                source: 'body'
-              })]
-            });
-          }
-          return undefined;
-        }
-        return request.body[resolvedKey];
-      }
-  }
-}
 function validateBodyKeys(request, bodyKeys) {
   if (request.body === undefined || request.body === null) {
     return;
@@ -87,6 +49,10 @@ function validateBodyKeys(request, bodyKeys) {
     });
   }
 }
+
+/**
+ * Represents the default converter.
+ */
 export class DefaultConverter {
   convert(value, _target) {
     return value;
@@ -131,45 +97,48 @@ async function resolveConverter(value, context, cache) {
     throw error;
   }
 }
+
+/**
+ * Represents the default binder.
+ */
 export class DefaultBinder {
   constructor(converters = []) {
     this.converters = converters;
   }
   async bind(dto, context) {
-    const schema = getDtoBindingSchema(dto);
+    const plan = getCompiledDtoBindingPlan(dto);
     const value = new dto();
     const converterCache = new Map();
-    const bodyKeys = new Set(schema.filter(entry => entry.metadata.source === 'body').map(entry => resolveSourceKey(entry.propertyKey, entry.metadata.key)));
     const globalConverters = (await Promise.all(this.converters.map(converter => resolveConverter(converter, context, converterCache)))).filter(converter => Boolean(converter));
-    validateBodyKeys(context.requestContext.request, bodyKeys);
+    validateBodyKeys(context.requestContext.request, plan.bodyKeys);
     const details = [];
-    for (const entry of schema) {
-      const rawValue = readSourceValue(context.requestContext.request, entry.metadata.source, entry.propertyKey, entry.metadata.key);
+    for (const entry of plan.entries) {
+      const rawValue = entry.read(context.requestContext.request);
       if (rawValue === undefined) {
-        if (entry.metadata.optional) {
+        if (entry.optional) {
           continue;
         }
         details.push(toInputErrorDetail({
           code: 'MISSING_FIELD',
-          field: toFieldName(entry.propertyKey),
-          message: `Missing required ${entry.metadata.source} field ${resolveSourceKey(entry.propertyKey, entry.metadata.key)}.`,
-          source: entry.metadata.source
+          field: entry.fieldName,
+          message: `Missing required ${entry.source} field ${entry.sourceKey}.`,
+          source: entry.source
         }));
         continue;
       }
       const target = {
         dto,
         handler: context.handler,
-        key: resolveSourceKey(entry.propertyKey, entry.metadata.key),
+        key: entry.sourceKey,
         propertyKey: entry.propertyKey,
         requestContext: context.requestContext,
-        source: entry.metadata.source
+        source: entry.source
       };
       let convertedValue = rawValue;
       for (const converter of globalConverters) {
         convertedValue = await converter.convert(convertedValue, target);
       }
-      const fieldConverter = await resolveConverter(entry.metadata.converter, context, converterCache);
+      const fieldConverter = await resolveConverter(entry.converter, context, converterCache);
       if (fieldConverter) {
         convertedValue = await fieldConverter.convert(convertedValue, target);
       }

package/dist/adapters/dto-binding-plan.d.ts

@@ -0,0 +1,19 @@
+import { type Constructor, type MetadataPropertyKey, type MetadataSource } from '@fluojs/core';
+import { type DtoFieldBindingMetadata } from '@fluojs/core/internal';
+import type { FrameworkRequest } from '../types.js';
+export interface CompiledDtoBindingPlanEntry {
+    readonly converter?: DtoFieldBindingMetadata['converter'];
+    readonly fieldName: string;
+    readonly optional: boolean;
+    readonly propertyKey: MetadataPropertyKey;
+    readonly read: (request: FrameworkRequest) => unknown;
+    readonly source: MetadataSource;
+    readonly sourceKey: string;
+}
+export interface CompiledDtoBindingPlan {
+    readonly bodyKeys: ReadonlySet<string>;
+    readonly entries: readonly CompiledDtoBindingPlanEntry[];
+    readonly propertyKeys: readonly MetadataPropertyKey[];
+}
+export declare function getCompiledDtoBindingPlan(dto: Constructor): CompiledDtoBindingPlan;
+//# sourceMappingURL=dto-binding-plan.d.ts.map

package/dist/adapters/dto-binding-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto-binding-plan.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-binding-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAmD,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEtH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAcpD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACvD;AAqBD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,sBAAsB,CA4BlF"}

package/dist/adapters/dto-binding-plan.js

@@ -0,0 +1,54 @@
+import { getDtoBindingSchema } from '@fluojs/core/internal';
+function toFieldName(propertyKey) {
+  return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
+}
+function resolveSourceKey(propertyKey, key) {
+  return key ?? toFieldName(propertyKey);
+}
+function readHeader(request, key) {
+  return request.headers[key.toLowerCase()] ?? request.headers[key];
+}
+const dtoBindingPlanCache = new WeakMap();
+function createSourceReader(source, sourceKey) {
+  switch (source) {
+    case 'path':
+      return request => request.params[sourceKey];
+    case 'query':
+      return request => request.query[sourceKey];
+    case 'header':
+      return request => readHeader(request, sourceKey);
+    case 'cookie':
+      return request => request.cookies[sourceKey];
+    case 'body':
+      return request => request.body?.[sourceKey];
+    default:
+      return () => undefined;
+  }
+}
+export function getCompiledDtoBindingPlan(dto) {
+  const cached = dtoBindingPlanCache.get(dto);
+  if (cached) {
+    return cached;
+  }
+  const entries = getDtoBindingSchema(dto).map(entry => {
+    const sourceKey = resolveSourceKey(entry.propertyKey, entry.metadata.key);
+    return {
+      ...(entry.metadata.converter === undefined ? {} : {
+        converter: entry.metadata.converter
+      }),
+      fieldName: toFieldName(entry.propertyKey),
+      optional: entry.metadata.optional === true,
+      propertyKey: entry.propertyKey,
+      read: createSourceReader(entry.metadata.source, sourceKey),
+      source: entry.metadata.source,
+      sourceKey
+    };
+  });
+  const next = {
+    bodyKeys: new Set(entries.filter(entry => entry.source === 'body').map(entry => entry.sourceKey)),
+    entries,
+    propertyKeys: entries.map(entry => entry.propertyKey)
+  };
+  dtoBindingPlanCache.set(dto, next);
+  return next;
+}

package/dist/adapters/dto-validation-adapter.d.ts

@@ -1,5 +1,8 @@
 import { type Constructor } from '@fluojs/core';
 import type { Validator } from '../types.js';
+/**
+ * Represents the http dto validation adapter.
+ */
 export declare class HttpDtoValidationAdapter implements Validator {
     private readonly validator;
     private throwBadRequestForValidationError;

package/dist/adapters/dto-validation-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto-validation-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-validation-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAMhD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMzC,OAAO,CAAC,6BAA6B;IAiB/B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWzE"}
+{"version":3,"file":"dto-validation-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-validation-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAG9D;;GAEG;AACH,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMzC,OAAO,CAAC,6BAA6B;IAiB/B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWzE"}

package/dist/adapters/dto-validation-adapter.js

@@ -1,7 +1,11 @@
-import { getDtoBindingSchema } from '@fluojs/core/internal';
 import { DefaultValidator as BaseDefaultValidator, DtoValidationError } from '@fluojs/validation';
 import { BadRequestException } from '../exceptions.js';
 import { toInputErrorDetail } from '../input-error-detail.js';
+import { getCompiledDtoBindingPlan } from './dto-binding-plan.js';
+
+/**
+ * Represents the http dto validation adapter.
+ */
 export class HttpDtoValidationAdapter {
   validator = new BaseDefaultValidator();
   throwBadRequestForValidationError(error) {
@@ -15,9 +19,9 @@ export class HttpDtoValidationAdapter {
     }
     const source = value;
     const filtered = Object.create(Object.getPrototypeOf(value));
-    for (const binding of getDtoBindingSchema(target)) {
-      if (Object.hasOwn(source, binding.propertyKey)) {
-        filtered[binding.propertyKey] = source[binding.propertyKey];
+    for (const propertyKey of getCompiledDtoBindingPlan(target).propertyKeys) {
+      if (Object.hasOwn(source, propertyKey)) {
+        filtered[propertyKey] = source[propertyKey];
       }
     }
     return filtered;

package/dist/dispatch/dispatch-content-negotiation.d.ts

@@ -1,9 +1,26 @@
 import type { ContentNegotiationOptions, FrameworkRequest, HandlerDescriptor, ResponseFormatter } from '../types.js';
+/**
+ * Describes the resolved content negotiation contract.
+ */
 export interface ResolvedContentNegotiation {
     defaultFormatter: ResponseFormatter;
     formatters: ResponseFormatter[];
     normalizedMediaTypes: string[];
 }
+/**
+ * Resolve content negotiation.
+ *
+ * @param options The options.
+ * @returns The resolve content negotiation result.
+ */
 export declare function resolveContentNegotiation(options: ContentNegotiationOptions | undefined): ResolvedContentNegotiation | undefined;
+/**
+ * Select response formatter.
+ *
+ * @param handler The handler.
+ * @param request The request.
+ * @param contentNegotiation The content negotiation.
+ * @returns The select response formatter result.
+ */
 export declare function selectResponseFormatter(handler: HandlerDescriptor, request: FrameworkRequest, contentNegotiation: ResolvedContentNegotiation): ResponseFormatter;
 //# sourceMappingURL=dispatch-content-negotiation.d.ts.map

package/dist/dispatch/dispatch-content-negotiation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-content-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-content-negotiation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAQrB,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AA2GD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CA+BhI;AAqCD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAC7C,iBAAiB,CA2CnB"}
+{"version":3,"file":"dispatch-content-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-content-negotiation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAQrB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AA2GD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CA+BhI;AAqCD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAC7C,iBAAiB,CA2CnB"}

package/dist/dispatch/dispatch-content-negotiation.js

@@ -1,4 +1,9 @@
 import { NotAcceptableException } from '../exceptions.js';
+
+/**
+ * Describes the resolved content negotiation contract.
+ */
+
 const NO_ACCEPTABLE_REPRESENTATION_MESSAGE = 'No acceptable response representation found.';
 function normalizeMediaType(value) {
   return value.split(';')[0]?.trim().toLowerCase() ?? '';
@@ -77,6 +82,13 @@ function matchesMediaRange(mediaRange, mediaType) {
   }
   return rangeSubtype === '*' || rangeSubtype === mediaTypeSubtype;
 }
+
+/**
+ * Resolve content negotiation.
+ *
+ * @param options The options.
+ * @returns The resolve content negotiation result.
+ */
 export function resolveContentNegotiation(options) {
   if (!options?.formatters?.length) {
     return undefined;
@@ -128,6 +140,15 @@ function resolveDefaultFormatter(allowedFormatters, allowedNormalizedMediaTypes,
   const idx = allowedNormalizedMediaTypes.indexOf(defaultMediaType);
   return idx >= 0 ? allowedFormatters[idx] : allowedFormatters[0] ?? contentNegotiation.defaultFormatter;
 }
+
+/**
+ * Select response formatter.
+ *
+ * @param handler The handler.
+ * @param request The request.
+ * @param contentNegotiation The content negotiation.
+ * @returns The select response formatter result.
+ */
 export function selectResponseFormatter(handler, request, contentNegotiation) {
   const {
     formatters: allowedFormatters,

package/dist/dispatch/dispatch-error-policy.d.ts

@@ -1,3 +1,11 @@
 import type { FrameworkResponse } from '../types.js';
+/**
+ * Write error response.
+ *
+ * @param error The error.
+ * @param response The response.
+ * @param requestId The request id.
+ * @returns The write error response result.
+ */
 export declare function writeErrorResponse(error: unknown, response: FrameworkResponse, requestId?: string): Promise<void>;
 //# sourceMappingURL=dispatch-error-policy.d.ts.map

package/dist/dispatch/dispatch-error-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-error-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-error-policy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiBrD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvH"}
+{"version":3,"file":"dispatch-error-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-error-policy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiBrD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvH"}

package/dist/dispatch/dispatch-error-policy.js

@@ -14,6 +14,15 @@ function toHttpException(error) {
     cause: error
   });
 }
+
+/**
+ * Write error response.
+ *
+ * @param error The error.
+ * @param response The response.
+ * @param requestId The request id.
+ * @returns The write error response result.
+ */
 export async function writeErrorResponse(error, response, requestId) {
   if (response.committed) {
     return;

package/dist/dispatch/dispatch-handler-policy.d.ts

@@ -1,3 +1,13 @@
+import type { RequestScopeContainer } from '@fluojs/di';
 import type { Binder, HandlerDescriptor, RequestContext } from '../types.js';
-export declare function invokeControllerHandler(handler: HandlerDescriptor, requestContext: RequestContext, binder?: Binder): Promise<unknown>;
+/**
+ * Invoke controller handler.
+ *
+ * @param handler The handler.
+ * @param requestContext The request context.
+ * @param binder The binder.
+ * @param controllerContainer Container used for resolving the controller instance before handler invocation.
+ * @returns The invoke controller handler result.
+ */
+export declare function invokeControllerHandler(handler: HandlerDescriptor, requestContext: RequestContext, binder?: Binder, controllerContainer?: RequestScopeContainer): Promise<unknown>;
 //# sourceMappingURL=dispatch-handler-policy.d.ts.map

package/dist/dispatch/dispatch-handler-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-handler-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-handler-policy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA2B,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKtG,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,cAAc,EAAE,cAAc,EAC9B,MAAM,GAAE,MAAsB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAuBlB"}
+{"version":3,"file":"dispatch-handler-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-handler-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAIxD,OAAO,KAAK,EAA2B,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKtG;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,cAAc,EAAE,cAAc,EAC9B,MAAM,GAAE,MAAsB,EAC9B,mBAAmB,GAAE,qBAAgD,GACpE,OAAO,CAAC,OAAO,CAAC,CAuBlB"}

package/dist/dispatch/dispatch-handler-policy.js

@@ -3,8 +3,18 @@ import { DefaultBinder } from '../adapters/binding.js';
 import { HttpDtoValidationAdapter } from '../adapters/dto-validation-adapter.js';
 const defaultBinder = new DefaultBinder();
 const defaultValidator = new HttpDtoValidationAdapter();
-export async function invokeControllerHandler(handler, requestContext, binder = defaultBinder) {
-  const controller = await requestContext.container.resolve(handler.controllerToken);
+
+/**
+ * Invoke controller handler.
+ *
+ * @param handler The handler.
+ * @param requestContext The request context.
+ * @param binder The binder.
+ * @param controllerContainer Container used for resolving the controller instance before handler invocation.
+ * @returns The invoke controller handler result.
+ */
+export async function invokeControllerHandler(handler, requestContext, binder = defaultBinder, controllerContainer = requestContext.container) {
+  const controller = await controllerContainer.resolve(handler.controllerToken);
   const method = controller[handler.methodName];
   if (typeof method !== 'function') {
     throw new InvariantError(`Controller ${handler.controllerToken.name} does not expose handler method ${handler.methodName}.`);

package/dist/dispatch/dispatch-response-policy.d.ts

@@ -1,6 +1,16 @@
 import { resolveContentNegotiation, type ResolvedContentNegotiation } from './dispatch-content-negotiation.js';
 import { writeErrorResponse } from './dispatch-error-policy.js';
 import type { FrameworkRequest, FrameworkResponse, HandlerDescriptor } from '../types.js';
+/**
+ * Write success response.
+ *
+ * @param handler The handler.
+ * @param request The request.
+ * @param response The response.
+ * @param value The value.
+ * @param contentNegotiation The content negotiation.
+ * @returns The write success response result.
+ */
 export declare function writeSuccessResponse(handler: HandlerDescriptor, request: FrameworkRequest, response: FrameworkResponse, value: unknown, contentNegotiation: ResolvedContentNegotiation | undefined): Promise<void>;
 export { resolveContentNegotiation, writeErrorResponse };
 export type { ResolvedContentNegotiation };

package/dist/dispatch/dispatch-response-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-response-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAcrB,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,GACzD,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAC;AACzD,YAAY,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"dispatch-response-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAgErB;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,GACzD,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAC;AACzD,YAAY,EAAE,0BAA0B,EAAE,CAAC"}