@fluojs/serialization 1.0.5 → 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
@@ -84,6 +99,7 @@ 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 인터셉터와 함께 사용
 
@@ -121,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는 계속 적용됩니다.
 

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
@@ -84,6 +99,7 @@ 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
 
@@ -121,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.
 

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

@@ -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 = {};
@@ -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.5",
+  "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.1.0",
-    "@fluojs/http": "^2.0.1"
+    "@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",