@fluojs/serialization 1.0.4 → 2.0.0

package/README.ko.md

@@ -2,12 +2,15 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
+Node.js 지원 범위는 `>=24.0.0 <27`입니다. 업그레이드 절차는 [Node.js 지원 및 마이그레이션](../../docs/reference/node-support.ko.md)을 참조하세요.
+
 fluo를 위한 클래스 기반 응답 직렬화 및 데코레이터 인지형 재귀 출력 가공 엔진입니다.
 
 ## 목차
 
 - [설치](#설치)
 - [사용 시점](#사용-시점)
+- [데코레이터 메타데이터 사전 로드](#데코레이터-메타데이터-사전-로드)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
 - [공개 API 개요](#공개-api-개요)
@@ -27,6 +30,18 @@ pnpm add @fluojs/serialization
 - response data가 serialization 중 lightweight synchronous transform을 거쳐야 할 때
 - HTTP interceptor가 같은 serialization rule을 자동으로 적용하게 하고 싶을 때
 
+## 데코레이터 메타데이터 사전 로드
+
+`@fluojs/serialization`은 import side effect로 `Symbol.metadata`를 설치하지 않습니다. 대상 runtime이 이를 기본 제공하지 않는다면 `@Expose()`, `@Exclude()`, `@Transform()`으로 decorate한 클래스를 평가하는 module을 import하기 전에 설치하세요.
+
+```ts
+// preload.ts — 이 파일을 애플리케이션 entrypoint로 설정합니다.
+import { ensureMetadataSymbol } from '@fluojs/core';
+
+ensureMetadataSymbol();
+await import('./bootstrap.js');
+```
+
 ## 빠른 시작
 
 ```ts
@@ -70,6 +85,8 @@ class SecureDto {
 }
 ```
 
+`ExposeClassOptions`는 `Expose(...)`가 받는 class-level option을 표현하는 export 타입입니다. DTO가 field-level `@Expose()` metadata가 있는 field만 내보내야 할 때 `excludeExtraneous: true`를 사용하세요.
+
 ### 값 변환
 
 ```ts
@@ -82,11 +99,12 @@ class ProductDto {
 ```
 
 같은 필드가 base class와 derived class 모두에서 decorate되면 transform은 base에서 derived 순서로 실행됩니다.
+`TransformFunction`은 동기식 `(value: unknown) => unknown` callback입니다. 현재 field value만 전달받으므로 async 작업이나 DTO, property metadata, serialization context 접근이 아니라 value-only transform에 사용하세요.
 
 ### 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 +114,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이 응답을 후처리할 수 없습니다.
 
 ### 순환 참조 처리
 
@@ -108,6 +137,7 @@ fluo의 직렬화 엔진은 활성 순환 참조를 자동으로 감지하고 `u
 ### 상속된 데코레이터 계약
 
 기반 클래스에 선언한 직렬화 메타데이터는 파생 DTO에도 상속됩니다. 공통 필드에 적용한 `@Expose()`, `@Exclude()`, `@Transform()` 규칙은 서브클래스 인스턴스를 직렬화할 때도 그대로 반영됩니다.
+파생 클래스의 데코레이터 갱신은 해당 클래스만 소유하므로 field나 class option을 override해도 base DTO나 sibling DTO의 이후 직렬화는 바뀌지 않습니다.
 
 Class-level `excludeExtraneous`도 일반 상속 규칙을 따릅니다. 파생 클래스에 option 없는 `@Expose()`를 붙여도 가장 가까운 상속 설정이 유지되므로, expose-only 기반 DTO는 subclass에서도 expose-only 상태를 유지합니다. 일반 enumerable field를 다시 포함하려는 의도가 있을 때만 파생 클래스에 `@Expose({ excludeExtraneous: false })`를 명시하세요. 이 경우에도 상속된 field-level `@Exclude()` metadata는 계속 적용됩니다.
 
@@ -125,8 +155,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

@@ -2,12 +2,15 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
+Node.js support is `>=24.0.0 <27`. See [Node.js support and migration](../../docs/reference/node-support.md) before upgrading.
+
 Class-based response serialization and output shaping for fluo with decorator-aware recursive object walking.
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [When to Use](#when-to-use)
+- [Decorator Metadata Preload](#decorator-metadata-preload)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
 - [Public API Overview](#public-api-overview)
@@ -27,6 +30,18 @@ pnpm add @fluojs/serialization
 - when response data needs lightweight synchronous transforms during serialization
 - when you want an HTTP interceptor to apply the same serialization rules automatically
 
+## Decorator Metadata Preload
+
+`@fluojs/serialization` does not install `Symbol.metadata` as an import side effect. When your target runtime does not provide it natively, install it before importing any module that evaluates classes decorated with `@Expose()`, `@Exclude()`, or `@Transform()`:
+
+```ts
+// preload.ts — configure this as the application entrypoint
+import { ensureMetadataSymbol } from '@fluojs/core';
+
+ensureMetadataSymbol();
+await import('./bootstrap.js');
+```
+
 ## Quick Start
 
 ```ts
@@ -70,6 +85,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
@@ -82,11 +99,12 @@ class ProductDto {
 ```
 
 When the same field is decorated in a base class and a derived class, transforms run in declaration order from base to derived.
+`TransformFunction` is a synchronous `(value: unknown) => unknown` callback: it receives only the current field value, so use it for value-only transforms rather than async work or access to the DTO, property metadata, or serialization context.
 
 ### 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 +114,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
 
@@ -108,6 +137,7 @@ The serializer cuts active cyclic references safely instead of recursing forever
 ### Inherited decorator contracts
 
 Serialization metadata declared on a base class is inherited by derived DTOs. `@Expose()`, `@Exclude()`, and `@Transform()` rules applied to shared base fields still take effect when you serialize subclass instances.
+Derived decorators own their metadata updates, so overriding a field or class option never changes the later serialization of the base DTO or a sibling DTO.
 
 Class-level `excludeExtraneous` also follows normal inheritance. A derived class with `@Expose()` and no options keeps the nearest inherited setting, so an expose-only base DTO remains expose-only in subclasses. Use `@Expose({ excludeExtraneous: false })` on the derived class only when you intentionally want to re-enable ordinary enumerable fields while still honoring inherited field-level `@Exclude()` metadata.
 
@@ -125,8 +155,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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAKxD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAClC;AA4DD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAE3G;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,OAAO,EACjB,WAAW,EAAE,mBAAmB,EAChC,MAAM,EAAE,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,KAAK,0BAA0B,GACtF,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,QAAQ,GAAG,yBAAyB,CAQ7F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,QAAQ,GAAG,GAAG,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAuBzH"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAKxD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAClC;AA4DD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAE3G;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,OAAO,EACjB,WAAW,EAAE,mBAAmB,EAChC,MAAM,EAAE,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,KAAK,0BAA0B,GACtF,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,QAAQ,GAAG,yBAAyB,CAU7F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,QAAQ,GAAG,GAAG,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CA2BzH"}

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.
@@ -23,7 +23,7 @@ function getStandardMetadataBag(metadata) {
 function getFieldMetadataMap(metadata) {
   const bag = getStandardMetadataBag(metadata);
   const current = bag[standardSerializationFieldMetadataKey];
-  if (current) {
+  if (current && Object.hasOwn(bag, standardSerializationFieldMetadataKey)) {
     return current;
   }
   const created = new Map();
@@ -33,7 +33,7 @@ function getFieldMetadataMap(metadata) {
 function getClassMetadataObject(metadata) {
   const bag = getStandardMetadataBag(metadata);
   const current = bag[standardSerializationClassMetadataKey];
-  if (current) {
+  if (current && Object.hasOwn(bag, standardSerializationClassMetadataKey)) {
     return current;
   }
   const created = {};
@@ -41,7 +41,7 @@ function getClassMetadataObject(metadata) {
   return created;
 }
 function getOwnMetadataBagFromConstructor(constructor) {
-  return getOwnStandardConstructorMetadataBag(constructor);
+  return getOwnConstructorRequestPipelineMetadataBag(constructor);
 }
 function getConstructorMetadataBags(constructor) {
   const bags = [];
@@ -87,7 +87,9 @@ export function updateFieldSerializationMetadata(metadata, propertyKey, update)
 export function getClassSerializationOptions(constructor) {
   const options = {};
   for (const bag of getConstructorMetadataBags(constructor)) {
-    Object.assign(options, bag[standardSerializationClassMetadataKey]);
+    if (Object.hasOwn(bag, standardSerializationClassMetadataKey)) {
+      Object.assign(options, bag[standardSerializationClassMetadataKey]);
+    }
   }
   return options;
 }
@@ -101,6 +103,9 @@ export function getClassSerializationOptions(constructor) {
 export function getFieldSerializationMetadata(constructor) {
   const merged = new Map();
   for (const bag of getConstructorMetadataBags(constructor)) {
+    if (!Object.hasOwn(bag, standardSerializationFieldMetadataKey)) {
+      continue;
+    }
     const fieldMetadata = bag[standardSerializationFieldMetadataKey];
     if (!fieldMetadata) {
       continue;

package/package.json

@@ -9,7 +9,7 @@
     "output",
     "transform"
   ],
-  "version": "1.0.4",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/serialization"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -36,11 +36,11 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/http": "^1.1.0"
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/http": "^3.0.0"
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",