@fluojs/http 1.0.0-beta.1 → 1.0.0-beta.10

package/README.ko.md

@@ -10,6 +10,7 @@
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
+- [요청 정리와 런타임 이식성](#요청-정리와-런타임-이식성)
 - [공개 API](#공개-api)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -112,20 +113,50 @@ stream(_input: undefined, ctx: RequestContext) {
 }
 ```
 
+### Versioning
+
+`createHandlerMapping(...)`은 `VersioningType`과 `versioning` option을 통해 URI, header, media-type, custom versioning strategy를 지원합니다. Route registration은 exact/static match를 fallback보다 앞에 두고, 동등하게 정규화된 route는 registration order를 보존합니다.
+
+### Request context helper
+
+Framework integration이 명시적인 request context boundary나 typed per-request storage가 필요할 때 `runWithRequestContext(...)`, `assertRequestContext()`, `createRequestContext(...)`, `createContextKey(...)`, `getContextValue(...)`, `setContextValue(...)`를 사용합니다.
+
+### Fast-path observability
+
+Dispatcher는 adapter와 diagnostics를 위해 `FAST_PATH_ELIGIBILITY_SYMBOL`, `FAST_PATH_STATS_SYMBOL`, `formatFastPathStats(...)`, `getDispatcherFastPathStats(...)`로 fast-path observability를 노출합니다.
+
+### Bun decorator bundling compatibility
+
+Fluo의 HTTP 데코레이터는 TC39 표준 데코레이터이며, runtime 또는 compiler가 표준 decorator context를 제공하면 계속 `context.metadata`를 통해 metadata를 기록합니다. Bun이 legacy TypeScript decorator transform으로 애플리케이션을 번들링하는 경우에도 controller, route, DTO binding, guard/interceptor, header, redirect, versioning, status, request DTO, `@Produces(...)` metadata를 Fluo 내부 metadata store에 기록하여 생성된 Bun bundle의 route mapping 동작을 보존합니다.
+
+이 호환 경로는 Bun bundle output을 위한 실행 fallback입니다. 애플리케이션 소스는 계속 Fluo 표준 데코레이터를 사용해야 하며, `emitDecoratorMetadata`를 켜거나 `reflect-metadata`에 의존해서는 안 됩니다.
+
+## 요청 정리와 런타임 이식성
+
+디스패처는 활성 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를 제거합니다.
+
 ## 공개 API
 
-- **라우팅 데코레이터**: `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `All`
-- **바인딩 데코레이터**: `FromBody`, `FromQuery`, `FromPath`, `FromHeader`, `FromCookie`, `RequestDto`
-- **실행 데코레이터**: `UseGuards`, `UseInterceptors`, `HttpCode`, `Version`, `Header`, `Redirect`
+- **라우팅 데코레이터**: `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `All`, `Options`, `Head`
+- **바인딩 데코레이터**: `FromBody`, `FromQuery`, `FromPath`, `FromHeader`, `FromCookie`, `RequestDto`, `Optional`, `Convert`
+- **실행 데코레이터**: `UseGuards`, `UseInterceptors`, `HttpCode`, `Version`, `Header`, `Redirect`, `Produces`
 - **핵심 런타임 타입**: `RequestContext`, `FrameworkRequest`, `FrameworkResponse`, `SseResponse`
-- **예외**: `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `InternalServerErrorException`, `PayloadTooLargeException`
-- **헬퍼**: `createHandlerMapping`, `createDispatcher`, `createCorsMiddleware`, `createRateLimitMiddleware`, `getCurrentRequestContext`
+- **Adapter API**: `HttpApplicationAdapter`, `createNoopHttpApplicationAdapter`, `createServerBackedHttpAdapterRealtimeCapability`, `createUnsupportedHttpAdapterRealtimeCapability`, `createFetchStyleHttpAdapterRealtimeCapability`
+- **예외와 오류**: `HttpException`, `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `ConflictException`, `NotAcceptableException`, `TooManyRequestsException`, `InternalServerErrorException`, `PayloadTooLargeException`, `createErrorResponse`, `RouteConflictError`, `InvalidRoutePathError`, `HandlerNotFoundError`, `RequestAbortedError`
+- **헬퍼**: `createHandlerMapping`, `createDispatcher`, `forRoutes`, `normalizeRoutePattern`, `matchRoutePattern`, `isMiddlewareRouteConfig`, `createCorrelationMiddleware`, `createCorsMiddleware`, `createRateLimitMiddleware`, `createSecurityHeadersMiddleware`, `runWithRequestContext`, `getCurrentRequestContext`, `assertRequestContext`, `createRequestContext`, `createContextKey`, `getContextValue`, `setContextValue`, `encodeSseComment`, `encodeSseMessage`
+- **Option type**: `CorsOptions`, `RateLimitOptions`, `RateLimitStore`, `SecurityHeadersOptions`, `SseSendOptions`
 
 ## 내부 서브경로 (`@fluojs/http/internal`)
 
 `./internal` 서브경로는 플랫폼 어댑터와 핵심 런타임에서 사용하는 저수준 유틸리티만 내보냅니다. 이들은 변경될 수 있으며 일반적인 애플리케이션 코드에서 사용해서는 안 됩니다.
 
 - `DefaultBinder`: 런타임 부트스트랩 경로에서 사용하는 기본 DTO/요청 바인더.
+- `bindRawRequestNativeRouteHandoff(...)` / `attachFrameworkRequestNativeRouteHandoff(...)`: public dispatcher API를 넓히지 않고 의미 보존이 가능한 native route match를 재사용하기 위한 내부 adapter/runtime 헬퍼.
+- `consumeRawRequestNativeRouteHandoff(...)` / `readFrameworkRequestNativeRouteHandoff(...)`: native route handoff를 읽거나 소비하기 위한 내부 helper.
+- 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

@@ -10,6 +10,7 @@ The HTTP execution layer that turns route metadata into a request pipeline with
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
+- [Request Cleanup and Portability](#request-cleanup-and-portability)
 - [Public API](#public-api)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -114,20 +115,50 @@ stream(_input: undefined, ctx: RequestContext) {
 }
 ```
 
+### Versioning
+
+`createHandlerMapping(...)` supports URI, header, media-type, and custom versioning strategies through `VersioningType` and the `versioning` option. Route registration keeps exact/static matches ahead of fallbacks while preserving registration order for equivalent normalized routes.
+
+### Request context helpers
+
+Use `runWithRequestContext(...)`, `assertRequestContext()`, `createRequestContext(...)`, `createContextKey(...)`, `getContextValue(...)`, and `setContextValue(...)` when framework integrations need explicit request context boundaries or typed per-request storage.
+
+### Fast-path observability
+
+The dispatcher exposes fast-path observability for adapters and diagnostics through `FAST_PATH_ELIGIBILITY_SYMBOL`, `FAST_PATH_STATS_SYMBOL`, `formatFastPathStats(...)`, and `getDispatcherFastPathStats(...)`.
+
+### Bun decorator bundling compatibility
+
+Fluo's HTTP decorators are standard TC39 decorators and continue to record metadata through `context.metadata` when the runtime or compiler provides the standard decorator context. When Bun bundles an application through its legacy TypeScript decorator transform, the same controller, route, DTO binding, guard/interceptor, header, redirect, versioning, status, request DTO, and `@Produces(...)` metadata is recorded through Fluo's internal metadata stores so generated Bun bundles preserve route mapping behavior.
+
+This compatibility path is an execution fallback for Bun bundle output; application source should still use Fluo's standard decorators and should not enable `emitDecoratorMetadata` or rely on `reflect-metadata`.
+
+## Request Cleanup and Portability
+
+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.
+
 ## Public API
 
-- **Routing decorators**: `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `All`
-- **Binding decorators**: `FromBody`, `FromQuery`, `FromPath`, `FromHeader`, `FromCookie`, `RequestDto`
-- **Execution decorators**: `UseGuards`, `UseInterceptors`, `HttpCode`, `Version`, `Header`, `Redirect`
+- **Routing decorators**: `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `All`, `Options`, `Head`
+- **Binding decorators**: `FromBody`, `FromQuery`, `FromPath`, `FromHeader`, `FromCookie`, `RequestDto`, `Optional`, `Convert`
+- **Execution decorators**: `UseGuards`, `UseInterceptors`, `HttpCode`, `Version`, `Header`, `Redirect`, `Produces`
 - **Core runtime types**: `RequestContext`, `FrameworkRequest`, `FrameworkResponse`, `SseResponse`
-- **Exceptions**: `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `InternalServerErrorException`, `PayloadTooLargeException`
-- **Helpers**: `createHandlerMapping`, `createDispatcher`, `createCorsMiddleware`, `createRateLimitMiddleware`, `getCurrentRequestContext`
+- **Adapter API**: `HttpApplicationAdapter`, `createNoopHttpApplicationAdapter`, `createServerBackedHttpAdapterRealtimeCapability`, `createUnsupportedHttpAdapterRealtimeCapability`, `createFetchStyleHttpAdapterRealtimeCapability`
+- **Exceptions and errors**: `HttpException`, `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `ConflictException`, `NotAcceptableException`, `TooManyRequestsException`, `InternalServerErrorException`, `PayloadTooLargeException`, `createErrorResponse`, `RouteConflictError`, `InvalidRoutePathError`, `HandlerNotFoundError`, `RequestAbortedError`
+- **Helpers**: `createHandlerMapping`, `createDispatcher`, `forRoutes`, `normalizeRoutePattern`, `matchRoutePattern`, `isMiddlewareRouteConfig`, `createCorrelationMiddleware`, `createCorsMiddleware`, `createRateLimitMiddleware`, `createSecurityHeadersMiddleware`, `runWithRequestContext`, `getCurrentRequestContext`, `assertRequestContext`, `createRequestContext`, `createContextKey`, `getContextValue`, `setContextValue`, `encodeSseComment`, `encodeSseMessage`
+- **Option types**: `CorsOptions`, `RateLimitOptions`, `RateLimitStore`, `SecurityHeadersOptions`, `SseSendOptions`
 
 ## Internal Subpath (`@fluojs/http/internal`)
 
 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.
+- `consumeRawRequestNativeRouteHandoff(...)` / `readFrameworkRequestNativeRouteHandoff(...)`: Internal helpers for reading or consuming native route handoffs.
+- 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;AAkDhI;;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;CAuGjF"}

package/dist/adapters/binding.js

@@ -1,8 +1,9 @@
 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']);
+const NO_CONVERTERS = [];
 function isPlainObject(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -10,44 +11,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 +50,10 @@ function validateBodyKeys(request, bodyKeys) {
     });
   }
 }
+
+/**
+ * Represents the default converter.
+ */
 export class DefaultConverter {
   convert(value, _target) {
     return value;
@@ -131,47 +98,79 @@ 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 request = context.requestContext.request;
     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);
+    if (request.body !== undefined && request.body !== null) {
+      validateBodyKeys(request, plan.bodyKeys);
+    }
     const details = [];
-    for (const entry of schema) {
-      const rawValue = readSourceValue(context.requestContext.request, entry.metadata.source, entry.propertyKey, entry.metadata.key);
+    if (this.converters.length === 0 && !plan.hasFieldConverters) {
+      for (const entry of plan.entries) {
+        const rawValue = entry.read(request);
+        if (rawValue === undefined) {
+          if (entry.optional) {
+            continue;
+          }
+          details.push(toInputErrorDetail({
+            code: 'MISSING_FIELD',
+            field: entry.fieldName,
+            message: `Missing required ${entry.source} field ${entry.sourceKey}.`,
+            source: entry.source
+          }));
+          continue;
+        }
+        value[entry.propertyKey] = rawValue;
+      }
+      if (details.length > 0) {
+        throw new BadRequestException('Request binding failed.', {
+          details
+        });
+      }
+      return value;
+    }
+    const converterCache = new Map();
+    const globalConverters = this.converters.length === 0 ? NO_CONVERTERS : (await Promise.all(this.converters.map(converter => resolveConverter(converter, context, converterCache)))).filter(converter => Boolean(converter));
+    for (const entry of plan.entries) {
+      const rawValue = entry.read(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);
-      if (fieldConverter) {
-        convertedValue = await fieldConverter.convert(convertedValue, target);
+      if (entry.converter !== undefined) {
+        const fieldConverter = await resolveConverter(entry.converter, context, converterCache);
+        if (fieldConverter) {
+          convertedValue = await fieldConverter.convert(convertedValue, target);
+        }
       }
       value[entry.propertyKey] = convertedValue;
     }

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

@@ -0,0 +1,22 @@
+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 hasFieldConverters: boolean;
+    readonly needsValidation: boolean;
+    readonly propertyKeys: readonly MetadataPropertyKey[];
+    readonly toValidationValue: (value: unknown) => unknown;
+}
+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,EAKL,KAAK,uBAAuB,EAE7B,MAAM,uBAAuB,CAAC;AAE/B,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,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACzD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,sBAAsB,CA4ClF"}

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

@@ -0,0 +1,86 @@
+import { getClassValidationRules, getDtoBindingSchema, getDtoValidationSchema } 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;
+  }
+}
+function identityValidationValue(value) {
+  return value;
+}
+function createValidationValueFilter(propertyKeys) {
+  return value => {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    const source = value;
+    const filtered = Object.create(Object.getPrototypeOf(value));
+    for (const propertyKey of propertyKeys) {
+      if (Object.hasOwn(source, propertyKey)) {
+        filtered[propertyKey] = source[propertyKey];
+      }
+    }
+    return filtered;
+  };
+}
+function isDtoAwareValidationRule(rule) {
+  return rule.kind === 'custom' || rule.kind === 'validateIf';
+}
+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 propertyKeys = entries.map(entry => entry.propertyKey);
+  const boundPropertyKeys = new Set(propertyKeys);
+  const validationSchema = getDtoValidationSchema(dto);
+  const validationPropertyKeys = validationSchema.map(entry => entry.propertyKey);
+  const hasClassValidationRules = getClassValidationRules(dto).length > 0;
+  const hasDtoAwareValidationRules = validationSchema.some(entry => entry.rules.some(rule => isDtoAwareValidationRule(rule)));
+  const needsValidation = hasClassValidationRules || validationPropertyKeys.length > 0;
+  const requiresValidationFilter = hasClassValidationRules || hasDtoAwareValidationRules || validationPropertyKeys.some(propertyKey => !boundPropertyKeys.has(propertyKey));
+  const next = {
+    bodyKeys: new Set(entries.filter(entry => entry.source === 'body').map(entry => entry.sourceKey)),
+    entries,
+    hasFieldConverters: entries.some(entry => entry.converter !== undefined),
+    needsValidation,
+    propertyKeys,
+    toValidationValue: requiresValidationFilter ? createValidationValueFilter(propertyKeys) : identityValidationValue
+  };
+  dtoBindingPlanCache.set(dto, next);
+  return next;
+}

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

@@ -1,9 +1,11 @@
 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;
-    private filterUnboundRequestDtoFields;
     validate(value: unknown, target: Constructor): Promise<void>;
     materialize<T>(value: unknown, target: Constructor<T>): Promise<T>;
 }

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;IAMnC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB5D,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) {
@@ -9,23 +13,13 @@ export class HttpDtoValidationAdapter {
       details: error.issues.map(issue => toInputErrorDetail(issue))
     });
   }
-  filterUnboundRequestDtoFields(value, target) {
-    if (typeof value !== 'object' || value === null) {
-      return value;
-    }
-    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];
-      }
-    }
-    return filtered;
-  }
   async validate(value, target) {
     try {
-      const filteredValue = this.filterUnboundRequestDtoFields(value, target);
-      await this.validator.validate(filteredValue, target);
+      const plan = getCompiledDtoBindingPlan(target);
+      if (!plan.needsValidation) {
+        return;
+      }
+      await this.validator.validate(plan.toValidationValue(value), target);
     } catch (error) {
       if (error instanceof DtoValidationError) {
         this.throwBadRequestForValidationError(error);