@fluojs/serialization 1.0.4 → 1.0.5

package/README.ko.md

@@ -70,6 +70,8 @@ class SecureDto {
 }
 ```
 
+`ExposeClassOptions`는 `Expose(...)`가 받는 class-level option을 표현하는 export 타입입니다. DTO가 field-level `@Expose()` metadata가 있는 field만 내보내야 할 때 `excludeExtraneous: true`를 사용하세요.
+
 ### 값 변환
 
 ```ts
@@ -86,7 +88,7 @@ class ProductDto {
 ### HTTP 인터셉터와 함께 사용
 
 ```ts
-import { Controller, Get, UseInterceptors } from '@fluojs/http';
+import { Controller, Get, type RequestContext, UseInterceptors } from '@fluojs/http';
 import { SerializerInterceptor } from '@fluojs/serialization';
 
 @Controller('/users')
@@ -96,10 +98,21 @@ class UsersController {
   findAll() {
     return [new UserEntity()];
   }
+
+  @Get('/export.csv')
+  async exportCsv(_input: undefined, context: RequestContext) {
+    context.response.setHeader('Content-Type', 'text/csv; charset=utf-8');
+    await context.response.send('id,username\n1,fluo');
+  }
 }
 ```
 
-`SerializerInterceptor`는 일반 HTTP 응답 writer가 아직 소유한 값만 직렬화합니다. 핸들러나 응답 헬퍼가 SSE 스트림처럼 `RequestContext.response`를 직접 커밋한 경우, 인터셉터는 해당 핸들러 소유 값을 그대로 반환하여 request pipeline의 응답 소유권을 보존합니다.
+두 route는 서로 다른 응답 소유자를 사용합니다.
+
+- **Framework-managed response**: `findAll()`은 `RequestContext.response`가 아직 commit되지 않은 상태에서 반환합니다. `SerializerInterceptor`가 반환된 DTO를 직렬화한 뒤 runtime response writer가 결과를 commit합니다.
+- **Handler-owned response**: `exportCsv()`는 최종 payload를 `RequestContext.response.send(...)`로 직접 씁니다. `send(...)`, `redirect(...)`, 또는 수동 streaming helper가 response를 commit하면 `SerializerInterceptor`는 `serialize(...)`를 건너뛰고 `next.handle()`에서 받은 값을 그대로 반환합니다. 이 보장은 `SerializerInterceptor`에만 해당하며, 다른 interceptor는 chain 결과를 계속 변환할 수 있습니다. 이와 별개로 dispatcher는 commit된 response를 확인하고 두 번째 success-response write를 건너뜁니다.
+
+직접 쓰는 payload는 최종 결과로 취급하세요. 필요한 field filtering이나 encoding을 commit 전에 적용해야 합니다. Handler/runtime response ownership이 commit된 뒤에는 serialization이 응답을 후처리할 수 없습니다.
 
 ### 순환 참조 처리
 
@@ -125,8 +138,8 @@ Decorated metadata가 없는 class instance도 재귀적으로 순회하므로,
 
 - **데코레이터**: `Expose`, `Exclude`, `Transform`
 - **엔진**: `serialize(value)`는 class instance, 배열, plain object, mixed graph를 재귀적으로 순회하며, 직접 transform하지 않은 opaque built-in 및 non-JSON leaf 값은 보존합니다.
-- **HTTP 통합**: `SerializerInterceptor`는 아직 commit되지 않은 handler 결과를 직렬화하고, response가 이미 commit된 뒤에는 handler 소유 값을 그대로 반환합니다.
-- **타입**: `TransformFunction`은 `Transform(...)`에 전달하는 callback 타입으로 root entrypoint에서 export됩니다.
+- **HTTP 통합**: `SerializerInterceptor`는 아직 commit되지 않은 handler 결과를 직렬화합니다. Response가 commit된 뒤에는 `next.handle()`에서 받은 값을 그대로 반환하지만, 다른 interceptor는 chain 결과를 계속 변환할 수 있습니다.
+- **타입**: `ExposeClassOptions`는 class-level `Expose(...)` option 타입으로 root entrypoint에서 export되며, `TransformFunction`은 `Transform(...)`에 전달하는 callback 타입으로 export됩니다.
 
 `Expose`는 class와 field에 적용할 수 있습니다. `Exclude`와 `Transform`은 field에 적용합니다.
 

package/README.md

@@ -70,6 +70,8 @@ class SecureDto {
 }
 ```
 
+`ExposeClassOptions` is the exported class-level options type accepted by `Expose(...)`. Use `excludeExtraneous: true` when a DTO should emit only fields with field-level `@Expose()` metadata.
+
 ### Value transforms
 
 ```ts
@@ -86,7 +88,7 @@ When the same field is decorated in a base class and a derived class, transforms
 ### HTTP response shaping with an interceptor
 
 ```ts
-import { Controller, Get, UseInterceptors } from '@fluojs/http';
+import { Controller, Get, type RequestContext, UseInterceptors } from '@fluojs/http';
 import { SerializerInterceptor } from '@fluojs/serialization';
 
 @Controller('/users')
@@ -96,10 +98,21 @@ class UsersController {
   findAll() {
     return [new UserEntity()];
   }
+
+  @Get('/export.csv')
+  async exportCsv(_input: undefined, context: RequestContext) {
+    context.response.setHeader('Content-Type', 'text/csv; charset=utf-8');
+    await context.response.send('id,username\n1,fluo');
+  }
 }
 ```
 
-`SerializerInterceptor` only serializes values that still belong to the normal HTTP response writer. If a handler or response helper commits `RequestContext.response` directly, such as an SSE stream, the interceptor returns that handler-owned value unchanged so the request pipeline preserves response ownership.
+The two routes use different response owners:
+
+- **Framework-managed response**: `findAll()` returns while `RequestContext.response` is still uncommitted. `SerializerInterceptor` serializes the returned DTOs, then the runtime response writer commits the result.
+- **Handler-owned response**: `exportCsv()` writes the final payload through `RequestContext.response.send(...)`. Once `send(...)`, `redirect(...)`, or a manual streaming helper commits the response, `SerializerInterceptor` bypasses `serialize(...)` and returns the value it received from `next.handle()` unchanged. This guarantee is specific to `SerializerInterceptor`; other interceptors may still transform the chain result. Independently, the dispatcher sees the committed response and skips a second success-response write.
+
+Treat a directly written payload as final: apply any required field filtering or encoding before the commit. Serialization cannot post-process a response after handler/runtime response ownership has been committed.
 
 ### Cycle-safe serialization
 
@@ -125,8 +138,8 @@ Undecorated class instances are still traversed recursively, so decorated nested
 
 - **Decorators**: `Expose`, `Exclude`, `Transform`
 - **Engine**: `serialize(value)` recursively walks class instances, arrays, plain objects, and mixed graphs while preserving opaque built-ins and non-JSON leaf values unless you transform them
-- **HTTP integration**: `SerializerInterceptor` serializes uncommitted handler results and returns handler-owned values unchanged after the response has already been committed
-- **Types**: `TransformFunction` is exported from the root entrypoint for callbacks passed to `Transform(...)`
+- **HTTP integration**: `SerializerInterceptor` serializes uncommitted handler results; after the response is committed, it returns the value it received from `next.handle()` unchanged, although other interceptors may still transform the chain result
+- **Types**: `ExposeClassOptions` is exported from the root entrypoint for class-level `Expose(...)` options, and `TransformFunction` is exported for callbacks passed to `Transform(...)`
 
 `Expose` can be applied to classes and fields. `Exclude` and `Transform` apply to fields.
 

package/dist/metadata.js

@@ -1,4 +1,4 @@
-import { getOwnStandardConstructorMetadataBag } from '@fluojs/core/internal';
+import { getOwnConstructorRequestPipelineMetadataBag } from '@fluojs/core/request-pipeline';
 
 /**
  * Defines the transform function type.
@@ -41,7 +41,7 @@ function getClassMetadataObject(metadata) {
   return created;
 }
 function getOwnMetadataBagFromConstructor(constructor) {
-  return getOwnStandardConstructorMetadataBag(constructor);
+  return getOwnConstructorRequestPipelineMetadataBag(constructor);
 }
 function getConstructorMetadataBags(constructor) {
   const bags = [];

package/package.json

@@ -9,7 +9,7 @@
     "output",
     "transform"
   ],
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/http": "^1.1.0"
+    "@fluojs/core": "^1.1.0",
+    "@fluojs/http": "^2.0.1"
   },
   "devDependencies": {
     "vitest": "^3.2.4"