@fluojs/serialization 1.0.0-beta.3 → 1.0.0-beta.5

package/README.ko.md

@@ -4,18 +4,12 @@
 
 fluo를 위한 클래스 기반 응답 직렬화 및 데코레이터 인지형 재귀 출력 가공 엔진입니다.
 
-`@fluojs/serialization`은 애플리케이션의 **출력 경계(Output Boundary)**를 담당합니다. 내부 클래스 인스턴스나 복잡한 객체 그래프를 데코레이터 규칙이 반영된 일반 응답 형태로 변환하는 선언적인 방법을 제공합니다. 이를 통해 API 응답에 의도한 데이터만 노출되도록 보장합니다.
-
 ## 목차
 
 - [설치](#설치)
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
-  - [민감한 데이터 제외](#민감한-데이터-제외)
-  - [값 변환 (Transforming)](#값-변환-transforming)
-  - [순환 참조 처리](#순환-참조-처리)
-  - [HTTP 인터셉터와 함께 사용](#http-인터셉터와-함께-사용)
 - [공개 API 개요](#공개-api-개요)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -28,94 +22,70 @@ pnpm add @fluojs/serialization
 
 ## 사용 시점
 
-- JSON 응답에 포함될 클래스 속성을 정밀하게 제어하고 싶을 때.
-- 비밀번호나 내부 ID와 같은 민감한 필드를 출력에서 숨겨야 할 때.
-- 직렬화 과정에서 속성 값을 변환해야 할 때 (예: 날짜 형식 지정, 내부 열거형 매핑).
-- 무한 루프를 유발할 수 있는 복잡한 객체 그래프를 안전하게 직렬화해야 할 때.
+- output DTO가 제어된 일부 필드만 노출해야 할 때
+- password hash나 내부 identifier 같은 민감한 값이 response boundary를 벗어나면 안 될 때
+- response data가 serialization 중 lightweight synchronous transform을 거쳐야 할 때
+- HTTP interceptor가 같은 serialization rule을 자동으로 적용하게 하고 싶을 때
 
 ## 빠른 시작
 
-DTO나 엔티티 클래스에 데코레이터를 적용하고 `serialize` 함수 또는 `SerializerInterceptor`를 사용합니다.
-
-```typescript
+```ts
 import { Expose, Exclude, Transform, serialize } from '@fluojs/serialization';
 
 class UserEntity {
   @Expose()
-  id: string = '';
+  id = '';
 
   @Expose()
-  @Transform((val) => val.toUpperCase())
-  username: string = '';
+  @Transform((value) => value.toUpperCase())
+  username = '';
 
   @Exclude()
-  passwordHash: string = '';
-
-  constructor(partial: Partial<UserEntity>) {
-    Object.assign(this, partial);
-  }
+  passwordHash = '';
 }
 
-const user = new UserEntity({ id: '1', username: 'fluo', passwordHash: 'secret' });
-const result = serialize(user);
+const user = Object.assign(new UserEntity(), {
+  id: '1',
+  username: 'fluo',
+  passwordHash: 'secret',
+});
 
-console.log(result); 
-// 출력: { id: "1", username: "FLUO" }
-// passwordHash는 제외됩니다.
+console.log(serialize(user));
+// { id: '1', username: 'FLUO' }
 ```
 
 ## 주요 패턴
 
-### 민감한 데이터 제외
-
-`@Exclude()`를 사용하여 특정 속성이 출력에 절대 나타나지 않도록 합니다. 클래스 레벨에서 `@Expose({ excludeExtraneous: true })`를 사용하면 명시적으로 허용된 필드만 포함하는 "화이트리스트" 전략을 구현할 수 있습니다.
+### 노출 전용 출력 DTO
 
-```typescript
-import { Expose, Exclude } from '@fluojs/serialization';
+```ts
+import { Expose } from '@fluojs/serialization';
 
 @Expose({ excludeExtraneous: true })
 class SecureDto {
   @Expose()
-  publicData: string = 'visible';
+  publicData = 'visible';
 
-  internalData: string = 'hidden'; // excludeExtraneous가 true이므로 숨겨짐
+  internalData = 'hidden';
 }
 ```
 
-### 값 변환 (Transforming)
+### 값 변환
 
-`@Transform()`을 사용하여 직렬화 중에 값을 수정합니다. 변환 함수는 현재 값을 인자로 받아 새로운 값을 반환해야 합니다.
-
-```typescript
+```ts
 import { Transform } from '@fluojs/serialization';
 
 class ProductDto {
   @Transform((price) => `$${price.toFixed(2)}`)
-  price: number = 0;
+  price = 0;
 }
 ```
 
-### 순환 참조 처리
-
-fluo의 직렬화 엔진은 순환 참조를 자동으로 감지하고, 반복되는 참조에 대해 `undefined`를 반환하여 절단함으로써 무한 루프와 스택 오버플로를 방지하고 일반 응답 형태를 유지합니다.
-
-### 상속된 데코레이터 계약
-
-기반 클래스에 선언한 직렬화 메타데이터는 파생 DTO에도 상속됩니다. 공통 필드에 적용한 `@Expose()`, `@Exclude()`, `@Transform()` 규칙은 서브클래스 인스턴스를 직렬화할 때도 그대로 반영됩니다.
-
-### 일반 객체 안전성
-
-`serialize()`는 일반 객체와 null-prototype 레코드를 데코레이터가 붙은 클래스 인스턴스로 오인하지 않습니다. 사용자 정의 `constructor` 필드나 안전하지 않은 `constructor` 값을 가진 객체도 예외 없이 안전하게 순회합니다.
-
-### 비JSON leaf 값
-
-`serialize()`는 데코레이터 메타데이터를 적용하고 배열/일반 객체를 재귀적으로 순회하지만, 모든 leaf 값을 엄격한 JSON 타입으로 강제 변환하지는 않습니다. `Date`, `bigint`, 함수, `symbol` 같은 값은 `@Transform(...)`이나 최종 HTTP 응답 작성 전에 직접 정규화하지 않으면 그대로 통과할 수 있습니다.
+같은 필드가 base class와 derived class 모두에서 decorate되면 transform은 base에서 derived 순서로 실행됩니다.
 
 ### HTTP 인터셉터와 함께 사용
 
-fluo HTTP 애플리케이션에서는 `SerializerInterceptor`를 사용하여 컨트롤러에서 나가는 모든 응답을 자동으로 직렬화할 수 있습니다.
-
-```typescript
+```ts
 import { Controller, Get, UseInterceptors } from '@fluojs/http';
 import { SerializerInterceptor } from '@fluojs/serialization';
 
@@ -124,30 +94,45 @@ import { SerializerInterceptor } from '@fluojs/serialization';
 class UsersController {
   @Get('/')
   findAll() {
-    return [new UserEntity({ ... }), new UserEntity({ ... })];
+    return [new UserEntity()];
   }
 }
 ```
 
 `SerializerInterceptor`는 일반 HTTP 응답 writer가 아직 소유한 값만 직렬화합니다. 핸들러나 응답 헬퍼가 SSE 스트림처럼 `RequestContext.response`를 직접 커밋한 경우, 인터셉터는 해당 핸들러 소유 값을 그대로 반환하여 request pipeline의 응답 소유권을 보존합니다.
 
+### 순환 참조 처리
+
+fluo의 직렬화 엔진은 활성 순환 참조를 자동으로 감지하고 `undefined`로 절단하여 무한 루프와 스택 오버플로를 방지합니다. 이미 직렬화가 끝난 공유 참조는 삭제하지 않고 직렬화된 그래프 안에서 재사용합니다. 예를 들어 두 sibling 필드가 같은 원본 객체를 가리키면 두 직렬화 결과도 같은 직렬화 객체를 가리키며, 현재 직렬화 중인 객체를 다시 만나는 활성 cycle만 `undefined`로 절단됩니다.
+
+### 상속된 데코레이터 계약
+
+기반 클래스에 선언한 직렬화 메타데이터는 파생 DTO에도 상속됩니다. 공통 필드에 적용한 `@Expose()`, `@Exclude()`, `@Transform()` 규칙은 서브클래스 인스턴스를 직렬화할 때도 그대로 반영됩니다.
+
+Decorated metadata가 없는 class instance도 재귀적으로 순회하므로, parent object에 serialization metadata가 없어도 decorated nested descendant는 반영됩니다.
+
+### 일반 객체 안전성
+
+`serialize()`는 일반 객체와 null-prototype 레코드를 데코레이터가 붙은 클래스 인스턴스로 오인하지 않습니다. Enumerable symbol key도 직렬화하며, own `__proto__`, `constructor`, `prototype` key는 prototype mutation이 아니라 data로 취급합니다. 사용자 정의 `constructor` 필드나 안전하지 않은 `constructor` 값을 가진 객체도 예외 없이 안전하게 순회합니다.
+
+### 비JSON leaf 값
+
+`serialize()`는 데코레이터 메타데이터를 적용하고 배열/일반 객체를 재귀적으로 순회하지만, 모든 leaf 값을 엄격한 JSON 타입으로 강제 변환하지는 않습니다. `Date`, `Map`, `Set`, `URL`, `URLSearchParams`, `RegExp`, `Error`, `ArrayBuffer`, typed array, `WeakMap`, `WeakSet`, `Promise` 같은 opaque built-in은 DTO 같은 클래스 인스턴스로 펼치지 않고 그대로 통과합니다. `bigint`, 함수, `symbol` 같은 값도 `@Transform(...)`이나 최종 HTTP 응답 작성 전에 직접 정규화하지 않으면 그대로 통과할 수 있습니다.
+
 ## 공개 API 개요
 
-### 데코레이터
-- `@Expose(options?)`: 포함할 속성을 표시합니다. 클래스에 사용하여 기본 동작을 설정할 수도 있습니다.
-- `@Exclude()`: 직렬화 중에 무시할 속성을 표시합니다.
-- `@Transform(fn)`: 속성에 대한 변환 함수를 등록합니다.
+- **데코레이터**: `Expose`, `Exclude`, `Transform`
+- **엔진**: `serialize(value)`
+- **HTTP 통합**: `SerializerInterceptor`
 
-### 엔진
-- `serialize(value)`: 객체/배열을 재귀적으로 순회하며 직렬화 규칙과 데코레이터를 적용합니다.
-- `SerializerInterceptor`: 핸들러의 반환 값에 대해 `serialize`를 호출하는 fluo HTTP 인터셉터입니다.
+`Expose`는 class와 field에 적용할 수 있습니다. `Exclude`와 `Transform`은 field에 적용합니다.
 
 ## 관련 패키지
 
-- `@fluojs/http`: `SerializerInterceptor`를 통한 자동 출력 가공을 지원합니다.
-- `@fluojs/validation`: **입력** 측면(일반 객체를 클래스 인스턴스로 변환)을 담당하는 대응 패키지입니다.
+- `@fluojs/http`: HTTP handler에 `SerializerInterceptor`를 적용합니다.
+- `@fluojs/validation`: input-side DTO materialization과 validation을 담당합니다.
 
 ## 예제 소스
 
-- `packages/serialization/src/serialize.test.ts`: 다양한 직렬화 시나리오에 대한 상세 예제.
-- `packages/serialization/src/serializer-interceptor.test.ts`: HTTP 컨텍스트 내에서의 사용법.
+- `packages/serialization/src/serialize.test.ts`
+- `packages/serialization/src/serializer-interceptor.test.ts`

package/README.md

@@ -81,6 +81,8 @@ 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.
+
 ### HTTP response shaping with an interceptor
 
 ```ts
@@ -101,19 +103,21 @@ class UsersController {
 
 ### Cycle-safe serialization
 
-The serializer cuts cyclic references safely instead of recursing forever, so complex object graphs can still be turned into plain response-shaped objects without unbounded recursion.
+The serializer cuts active cyclic references safely instead of recursing forever, so complex object graphs can still be turned into plain response-shaped objects without unbounded recursion. Completed shared references are reused in the serialized graph rather than dropped: if two sibling fields point at the same source object, both serialized fields point at the same serialized object. Only an object that is encountered again while it is already being serialized is cut to `undefined`.
 
 ### 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.
 
+Undecorated class instances are still traversed recursively, so decorated nested descendants are respected even when the parent object has no serialization metadata.
+
 ### Plain-object safety
 
-`serialize()` treats plain objects and null-prototype records as data containers, not decorated class instances. Objects with custom or unsafe `constructor` fields are walked safely without throwing.
+`serialize()` treats plain objects and null-prototype records as data containers, not decorated class instances. Enumerable symbol keys are serialized, own `__proto__`, `constructor`, and `prototype` keys are treated as data rather than prototype mutations, and objects with custom or unsafe `constructor` fields are walked safely without throwing.
 
 ### Non-JSON leaf values
 
-`serialize()` applies decorator metadata and recursively walks arrays/plain objects, but it does not coerce every leaf into strict JSON types. Values such as `Date`, `bigint`, functions, and symbols can pass through unchanged unless you normalize them with `@Transform(...)` or before writing the final HTTP response.
+`serialize()` applies decorator metadata and recursively walks arrays/plain objects, but it does not coerce every leaf into strict JSON types. Opaque built-ins such as `Date`, `Map`, `Set`, `URL`, `URLSearchParams`, `RegExp`, `Error`, `ArrayBuffer`, typed arrays, `WeakMap`, `WeakSet`, and `Promise` pass through unchanged instead of being flattened as DTO-like class instances. Values such as `bigint`, functions, and symbols can also pass through unchanged unless you normalize them with `@Transform(...)` or before writing the final HTTP response.
 
 ## Public API Overview
 
@@ -121,6 +125,8 @@ Serialization metadata declared on a base class is inherited by derived DTOs. `@
 - **Engine**: `serialize(value)`
 - **HTTP integration**: `SerializerInterceptor`
 
+`Expose` can be applied to classes and fields. `Exclude` and `Transform` apply to fields.
+
 ## Related Packages
 
 - `@fluojs/http`: applies `SerializerInterceptor` to HTTP handlers

package/dist/metadata.d.ts

@@ -1,15 +1,49 @@
 import { type MetadataPropertyKey } from '@fluojs/core';
+/**
+ * Defines the transform function type.
+ */
 export type TransformFunction = (value: unknown) => unknown;
+/**
+ * Describes the class serialization options contract.
+ */
 export interface ClassSerializationOptions {
     excludeExtraneous?: boolean;
 }
+/**
+ * Describes the serialization field metadata contract.
+ */
 export interface SerializationFieldMetadata {
     excluded?: boolean;
     exposed?: boolean;
     transforms?: TransformFunction[];
 }
+/**
+ * Update class serialization options.
+ *
+ * @param metadata The metadata.
+ * @param partial The partial.
+ */
 export declare function updateClassSerializationOptions(metadata: unknown, partial: ClassSerializationOptions): void;
+/**
+ * Update field serialization metadata.
+ *
+ * @param metadata The metadata.
+ * @param propertyKey The property key.
+ * @param update The update.
+ */
 export declare function updateFieldSerializationMetadata(metadata: unknown, propertyKey: MetadataPropertyKey, update: (current: SerializationFieldMetadata | undefined) => SerializationFieldMetadata): void;
+/**
+ * Get class serialization options.
+ *
+ * @param constructor The constructor.
+ * @returns The get class serialization options result.
+ */
 export declare function getClassSerializationOptions(constructor: Function): ClassSerializationOptions;
+/**
+ * Get field serialization metadata.
+ *
+ * @param constructor The constructor.
+ * @returns The get field serialization metadata result.
+ */
 export declare function getFieldSerializationMetadata(constructor: Function): Map<MetadataPropertyKey, SerializationFieldMetadata>;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAKxD,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE5D,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAClC;AA6DD,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAE3G;AAED,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,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,QAAQ,GAAG,yBAAyB,CAK7F;AAED,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,EAAE,KAAK,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;AA8DD;;;;;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,CAK7F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,QAAQ,GAAG,GAAG,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAuBzH"}

package/dist/metadata.js

@@ -1,11 +1,24 @@
-import { getOwnStandardConstructorMetadataBag, metadataSymbol } from '@fluojs/core/internal';
+import { ensureMetadataSymbol, getOwnStandardConstructorMetadataBag } from '@fluojs/core/internal';
+
+/**
+ * Defines the transform function type.
+ */
+
+/**
+ * Describes the class serialization options contract.
+ */
+
+/**
+ * Describes the serialization field metadata contract.
+ */
+
 const standardSerializationClassMetadataKey = Symbol.for('fluo.standard.serialization.class');
 const standardSerializationFieldMetadataKey = Symbol.for('fluo.standard.serialization.field');
+ensureMetadataSymbol();
 function getStandardMetadataBag(metadata) {
   if (metadata === null || metadata === undefined) {
     throw new Error('Decorator metadata is not available. Ensure your environment supports TC39 decorator metadata (Stage 3).');
   }
-  void metadataSymbol;
   return metadata;
 }
 function getFieldMetadataMap(metadata) {
@@ -43,19 +56,48 @@ function getConstructorMetadataBags(constructor) {
   }
   return bags;
 }
+
+/**
+ * Update class serialization options.
+ *
+ * @param metadata The metadata.
+ * @param partial The partial.
+ */
 export function updateClassSerializationOptions(metadata, partial) {
   Object.assign(getClassMetadataObject(metadata), partial);
 }
+
+/**
+ * Update field serialization metadata.
+ *
+ * @param metadata The metadata.
+ * @param propertyKey The property key.
+ * @param update The update.
+ */
 export function updateFieldSerializationMetadata(metadata, propertyKey, update) {
   const map = getFieldMetadataMap(metadata);
   map.set(propertyKey, update(map.get(propertyKey)));
 }
+
+/**
+ * Get class serialization options.
+ *
+ * @param constructor The constructor.
+ * @returns The get class serialization options result.
+ */
 export function getClassSerializationOptions(constructor) {
   return getConstructorMetadataBags(constructor).reduce((options, bag) => ({
     ...options,
     ...bag[standardSerializationClassMetadataKey]
   }), {});
 }
+
+/**
+ * Get field serialization metadata.
+ *
+ * @param constructor The constructor.
+ * @returns The get field serialization metadata result.
+ */
 export function getFieldSerializationMetadata(constructor) {
   const merged = new Map();
   for (const bag of getConstructorMetadataBags(constructor)) {

package/dist/serialize.d.ts

@@ -1,12 +1,13 @@
 /**
- * Serializes class instances and object graphs into JSON-safe plain values.
+ * Serializes class instances and object graphs into plain response-shaped values.
  *
  * Serialization honors `@Expose()`, `@Exclude()`, and `@Transform()` metadata.
  * Cycles and repeated references are handled without unbounded recursion.
+ * Opaque built-ins and non-JSON leaf values such as `Date`, `Map`, `Set`, `URL`, `Error`, `bigint`, functions, and symbols pass through unchanged unless you normalize them before or during serialization.
  *
  * @typeParam T Input value type.
  * @param value Value or object graph to serialize.
- * @returns A plain JSON-safe structure ready for HTTP response writing.
+ * @returns A plain recursively serialized structure whose opaque objects and non-JSON leaf values are preserved unless transformed.
  *
  * @example
  * ```ts

package/dist/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAiPA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAOxD"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAkQA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAOxD"}

package/dist/serialize.js

@@ -9,6 +9,9 @@ function isPlainObject(value) {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
+function isOpaqueObject(value) {
+  return value instanceof Date || value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet || value instanceof URL || value instanceof URLSearchParams || value instanceof RegExp || value instanceof Error || value instanceof ArrayBuffer || ArrayBuffer.isView(value) || value instanceof Promise;
+}
 function getSerializableConstructor(value) {
   const prototype = Object.getPrototypeOf(value);
   if (prototype === null || prototype === Object.prototype) {
@@ -147,10 +150,10 @@ function serializeInternal(value, context) {
       }
     });
   }
-  if (value instanceof Date) {
-    return value;
-  }
   if (isObjectLike(value)) {
+    if (isOpaqueObject(value)) {
+      return value;
+    }
     if (isPlainObject(value)) {
       return serializeRecord(value, context);
     }
@@ -160,14 +163,15 @@ function serializeInternal(value, context) {
 }
 
 /**
- * Serializes class instances and object graphs into JSON-safe plain values.
+ * Serializes class instances and object graphs into plain response-shaped values.
  *
  * Serialization honors `@Expose()`, `@Exclude()`, and `@Transform()` metadata.
  * Cycles and repeated references are handled without unbounded recursion.
+ * Opaque built-ins and non-JSON leaf values such as `Date`, `Map`, `Set`, `URL`, `Error`, `bigint`, functions, and symbols pass through unchanged unless you normalize them before or during serialization.
  *
  * @typeParam T Input value type.
  * @param value Value or object graph to serialize.
- * @returns A plain JSON-safe structure ready for HTTP response writing.
+ * @returns A plain recursively serialized structure whose opaque objects and non-JSON leaf values are preserved unless transformed.
  *
  * @example
  * ```ts

package/package.json

@@ -9,7 +9,7 @@
     "output",
     "transform"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.2",
-    "@fluojs/http": "^1.0.0-beta.2"
+    "@fluojs/core": "^1.0.0-beta.4",
+    "@fluojs/http": "^1.0.0-beta.10"
   },
   "devDependencies": {
     "vitest": "^3.2.4"