@fluojs/serialization 1.0.2 → 1.0.4

package/README.ko.md

@@ -103,7 +103,7 @@ class UsersController {
 
 ### 순환 참조 처리
 
-fluo의 직렬화 엔진은 활성 순환 참조를 자동으로 감지하고 `undefined`로 절단하여 무한 루프와 스택 오버플로를 방지합니다. 이미 직렬화가 끝난 공유 참조는 삭제하지 않고 직렬화된 그래프 안에서 재사용합니다. 예를 들어 두 sibling 필드가 같은 원본 객체를 가리키면 두 직렬화 결과도 같은 직렬화 객체를 가리키며, 현재 직렬화 중인 객체를 다시 만나는 활성 cycle만 `undefined`로 절단됩니다.
+fluo의 직렬화 엔진은 활성 순환 참조를 자동으로 감지하고 `undefined`로 절단하여 무한 루프와 스택 오버플로를 방지합니다. 같은 reference tracker가 class instance, plain object, 배열, mixed object-array graph 전체에서 공유됩니다. 자기 자신을 참조하는 배열과 object-array cycle은 활성 back edge에서 절단되고, 이미 직렬화가 끝난 공유 참조는 삭제하지 않고 직렬화된 그래프 안에서 재사용합니다. 예를 들어 두 sibling 필드 또는 객체 필드와 배열 항목이 같은 원본 객체를 가리키면 두 직렬화 결과도 같은 직렬화 객체를 가리키며, 현재 직렬화 중인 값을 다시 만나는 활성 cycle만 `undefined`로 절단됩니다.
 
 ### 상속된 데코레이터 계약
 
@@ -124,8 +124,9 @@ Decorated metadata가 없는 class instance도 재귀적으로 순회하므로,
 ## 공개 API 개요
 
 - **데코레이터**: `Expose`, `Exclude`, `Transform`
-- **엔진**: `serialize(value)`
-- **HTTP 통합**: `SerializerInterceptor`
+- **엔진**: `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됩니다.
 
 `Expose`는 class와 field에 적용할 수 있습니다. `Exclude`와 `Transform`은 field에 적용합니다.
 

package/README.md

@@ -103,7 +103,7 @@ class UsersController {
 
 ### Cycle-safe serialization
 
-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`.
+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. The same reference tracker is shared across class instances, plain objects, arrays, and mixed object-array graphs. Self-referential arrays and object-array cycles are cut at the active back edge, while completed shared references are reused in the serialized graph rather than dropped: if two sibling fields, or an object field and an array entry, point at the same source object, both serialized fields point at the same serialized object. Only a value that is encountered again while it is already being serialized is cut to `undefined`.
 
 ### Inherited decorator contracts
 
@@ -124,8 +124,9 @@ Undecorated class instances are still traversed recursively, so decorated nested
 ## Public API Overview
 
 - **Decorators**: `Expose`, `Exclude`, `Transform`
-- **Engine**: `serialize(value)`
-- **HTTP integration**: `SerializerInterceptor`
+- **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(...)`
 
 `Expose` can be applied to classes and fields. `Exclude` and `Transform` apply to fields.
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './decorators/exclude.js';
 export * from './decorators/expose.js';
 export * from './decorators/transform.js';
+export type { TransformFunction } from './metadata.js';
 export * from './serialize.js';
 export * from './serializer-interceptor.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ export * from './decorators/exclude.js';
 export * from './decorators/expose.js';
 export * from './decorators/transform.js';
 export * from './serialize.js';
-export * from './serializer-interceptor.js';
+export * from './serializer-interceptor.js';
+export {};

package/dist/metadata.d.ts

@@ -1,4 +1,4 @@
-import { type MetadataPropertyKey } from '@fluojs/core';
+import type { MetadataPropertyKey } from '@fluojs/core';
 /**
  * Defines the transform function type.
  */

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;;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"}
+{"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"}

package/dist/metadata.js

@@ -1,4 +1,4 @@
-import { ensureMetadataSymbol, getOwnStandardConstructorMetadataBag } from '@fluojs/core/internal';
+import { getOwnStandardConstructorMetadataBag } from '@fluojs/core/internal';
 
 /**
  * Defines the transform function type.
@@ -14,7 +14,6 @@ import { ensureMetadataSymbol, getOwnStandardConstructorMetadataBag } from '@flu
 
 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).');
@@ -86,10 +85,11 @@ export function updateFieldSerializationMetadata(metadata, propertyKey, update)
  * @returns The get class serialization options result.
  */
 export function getClassSerializationOptions(constructor) {
-  return getConstructorMetadataBags(constructor).reduce((options, bag) => ({
-    ...options,
-    ...bag[standardSerializationClassMetadataKey]
-  }), {});
+  const options = {};
+  for (const bag of getConstructorMetadataBags(constructor)) {
+    Object.assign(options, bag[standardSerializationClassMetadataKey]);
+  }
+  return options;
 }
 
 /**

package/dist/serialize.d.ts

@@ -1,8 +1,11 @@
 /**
- * Serializes class instances and object graphs into plain response-shaped values.
+ * Serializes class instances, arrays, plain records, and mixed object graphs
+ * into plain response-shaped values.
  *
  * Serialization honors `@Expose()`, `@Exclude()`, and `@Transform()` metadata.
- * Cycles and repeated references are handled without unbounded recursion.
+ * Cycles and repeated references are handled without unbounded recursion across
+ * both object and array boundaries. Active cycles are cut to `undefined`, while
+ * completed shared references reuse the previously serialized value.
  * 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.

package/dist/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAwQA;;;;;;;;;;;;;;;;;;;GAmBG;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":"AAwQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAOxD"}

package/dist/serialize.js

@@ -166,10 +166,13 @@ function serializeInternal(value, context) {
 }
 
 /**
- * Serializes class instances and object graphs into plain response-shaped values.
+ * Serializes class instances, arrays, plain records, and mixed object graphs
+ * into plain response-shaped values.
  *
  * Serialization honors `@Expose()`, `@Exclude()`, and `@Transform()` metadata.
- * Cycles and repeated references are handled without unbounded recursion.
+ * Cycles and repeated references are handled without unbounded recursion across
+ * both object and array boundaries. Active cycles are cut to `undefined`, while
+ * completed shared references reuse the previously serialized value.
  * 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.

package/dist/serializer-interceptor.d.ts

@@ -5,7 +5,9 @@ import type { CallHandler, Interceptor, InterceptorContext } from '@fluojs/http'
  * @remarks
  * Use this at the controller or route level when handlers return class instances
  * and you want `@Expose()`, `@Exclude()`, and `@Transform()` metadata applied
- * automatically.
+ * automatically. If the handler already committed `RequestContext.response`,
+ * the interceptor returns the handler-owned value unchanged so streaming and
+ * manually written responses keep their response ownership.
  */
 export declare class SerializerInterceptor implements Interceptor {
     intercept(context: InterceptorContext, next: CallHandler): Promise<unknown>;

package/dist/serializer-interceptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer-interceptor.d.ts","sourceRoot":"","sources":["../src/serializer-interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIjF;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,WAAW;IACjD,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CASlF"}
+{"version":3,"file":"serializer-interceptor.d.ts","sourceRoot":"","sources":["../src/serializer-interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIjF;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,YAAW,WAAW;IACjD,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CASlF"}

package/dist/serializer-interceptor.js

@@ -6,7 +6,9 @@ import { serialize } from './serialize.js';
  * @remarks
  * Use this at the controller or route level when handlers return class instances
  * and you want `@Expose()`, `@Exclude()`, and `@Transform()` metadata applied
- * automatically.
+ * automatically. If the handler already committed `RequestContext.response`,
+ * the interceptor returns the handler-owned value unchanged so streaming and
+ * manually written responses keep their response ownership.
  */
 export class SerializerInterceptor {
   async intercept(context, next) {

package/package.json

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