@fluojs/serialization 1.0.0-beta.2 → 1.0.0-beta.4

package/README.ko.md

@@ -97,7 +97,7 @@ class ProductDto {
 
 ### 순환 참조 처리
 
-fluo의 직렬화 엔진은 순환 참조를 자동으로 감지하고, 반복되는 참조에 대해 `undefined`를 반환하여 절단함으로써 무한 루프와 스택 오버플로를 방지하고 일반 응답 형태를 유지합니다.
+fluo의 직렬화 엔진은 활성 순환 참조를 자동으로 감지하고 `undefined`로 절단하여 무한 루프와 스택 오버플로를 방지합니다. 이미 직렬화가 끝난 공유 참조는 삭제하지 않고 직렬화된 그래프 안에서 재사용합니다. 예를 들어 두 sibling 필드가 같은 원본 객체를 가리키면 두 직렬화 결과도 같은 직렬화 객체를 가리키며, 현재 직렬화 중인 객체를 다시 만나는 활성 cycle만 `undefined`로 절단됩니다.
 
 ### 상속된 데코레이터 계약
 
@@ -109,7 +109,7 @@ fluo의 직렬화 엔진은 순환 참조를 자동으로 감지하고, 반복
 
 ### 비JSON leaf 값
 
-`serialize()`는 데코레이터 메타데이터를 적용하고 배열/일반 객체를 재귀적으로 순회하지만, 모든 leaf 값을 엄격한 JSON 타입으로 강제 변환하지는 않습니다. `Date`, `bigint`, 함수, `symbol` 같은 값은 `@Transform(...)`이나 최종 HTTP 응답 작성 전에 직접 정규화하지 않으면 그대로 통과할 수 있습니다.
+`serialize()`는 데코레이터 메타데이터를 적용하고 배열/일반 객체를 재귀적으로 순회하지만, 모든 leaf 값을 엄격한 JSON 타입으로 강제 변환하지는 않습니다. `Date`, `Map`, `Set`, `URL`, `URLSearchParams`, `RegExp`, `Error`, `ArrayBuffer`, typed array, `WeakMap`, `WeakSet`, `Promise` 같은 opaque built-in은 DTO 같은 클래스 인스턴스로 펼치지 않고 그대로 통과합니다. `bigint`, 함수, `symbol` 같은 값도 `@Transform(...)`이나 최종 HTTP 응답 작성 전에 직접 정규화하지 않으면 그대로 통과할 수 있습니다.
 
 ### HTTP 인터셉터와 함께 사용
 

package/README.md

@@ -101,7 +101,7 @@ 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
 
@@ -113,7 +113,7 @@ Serialization metadata declared on a base class is inherited by derived DTOs. `@
 
 ### 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
 

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;AAiED,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;AA6DD;;;;;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,4 +1,17 @@
-import { metadataSymbol } from '@fluojs/core/internal';
+import { getOwnStandardConstructorMetadataBag, metadataSymbol } 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');
 function getStandardMetadataBag(metadata) {
@@ -29,10 +42,7 @@ function getClassMetadataObject(metadata) {
   return created;
 }
 function getOwnMetadataBagFromConstructor(constructor) {
-  if (!Object.prototype.hasOwnProperty.call(constructor, metadataSymbol)) {
-    return undefined;
-  }
-  return constructor[metadataSymbol];
+  return getOwnStandardConstructorMetadataBag(constructor);
 }
 function getConstructorMetadataBags(constructor) {
   const bags = [];
@@ -46,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.2",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/http": "^1.0.0-beta.1"
+    "@fluojs/core": "^1.0.0-beta.3",
+    "@fluojs/http": "^1.0.0-beta.9"
   },
   "devDependencies": {
     "vitest": "^3.2.4"