@fluojs/serialization 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,151 @@
+# @fluojs/serialization
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo를 위한 클래스 기반 응답 직렬화 및 데코레이터 인지형 재귀 출력 가공 엔진입니다.
+
+`@fluojs/serialization`은 애플리케이션의 **출력 경계(Output Boundary)**를 담당합니다. 내부 클래스 인스턴스나 복잡한 객체 그래프를 데코레이터 규칙이 반영된 일반 응답 형태로 변환하는 선언적인 방법을 제공합니다. 이를 통해 API 응답에 의도한 데이터만 노출되도록 보장합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+  - [민감한 데이터 제외](#민감한-데이터-제외)
+  - [값 변환 (Transforming)](#값-변환-transforming)
+  - [순환 참조 처리](#순환-참조-처리)
+  - [HTTP 인터셉터와 함께 사용](#http-인터셉터와-함께-사용)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+pnpm add @fluojs/serialization
+```
+
+## 사용 시점
+
+- JSON 응답에 포함될 클래스 속성을 정밀하게 제어하고 싶을 때.
+- 비밀번호나 내부 ID와 같은 민감한 필드를 출력에서 숨겨야 할 때.
+- 직렬화 과정에서 속성 값을 변환해야 할 때 (예: 날짜 형식 지정, 내부 열거형 매핑).
+- 무한 루프를 유발할 수 있는 복잡한 객체 그래프를 안전하게 직렬화해야 할 때.
+
+## 빠른 시작
+
+DTO나 엔티티 클래스에 데코레이터를 적용하고 `serialize` 함수 또는 `SerializerInterceptor`를 사용합니다.
+
+```typescript
+import { Expose, Exclude, Transform, serialize } from '@fluojs/serialization';
+
+class UserEntity {
+  @Expose()
+  id: string = '';
+
+  @Expose()
+  @Transform((val) => val.toUpperCase())
+  username: string = '';
+
+  @Exclude()
+  passwordHash: string = '';
+
+  constructor(partial: Partial<UserEntity>) {
+    Object.assign(this, partial);
+  }
+}
+
+const user = new UserEntity({ id: '1', username: 'fluo', passwordHash: 'secret' });
+const result = serialize(user);
+
+console.log(result); 
+// 출력: { id: "1", username: "FLUO" }
+// passwordHash는 제외됩니다.
+```
+
+## 주요 패턴
+
+### 민감한 데이터 제외
+
+`@Exclude()`를 사용하여 특정 속성이 출력에 절대 나타나지 않도록 합니다. 클래스 레벨에서 `@Expose({ excludeExtraneous: true })`를 사용하면 명시적으로 허용된 필드만 포함하는 "화이트리스트" 전략을 구현할 수 있습니다.
+
+```typescript
+import { Expose, Exclude } from '@fluojs/serialization';
+
+@Expose({ excludeExtraneous: true })
+class SecureDto {
+  @Expose()
+  publicData: string = 'visible';
+
+  internalData: string = 'hidden'; // excludeExtraneous가 true이므로 숨겨짐
+}
+```
+
+### 값 변환 (Transforming)
+
+`@Transform()`을 사용하여 직렬화 중에 값을 수정합니다. 변환 함수는 현재 값을 인자로 받아 새로운 값을 반환해야 합니다.
+
+```typescript
+import { Transform } from '@fluojs/serialization';
+
+class ProductDto {
+  @Transform((price) => `$${price.toFixed(2)}`)
+  price: number = 0;
+}
+```
+
+### 순환 참조 처리
+
+fluo의 직렬화 엔진은 순환 참조를 자동으로 감지하고, 반복되는 참조에 대해 `undefined`를 반환하여 절단함으로써 무한 루프와 스택 오버플로를 방지하고 일반 응답 형태를 유지합니다.
+
+### 상속된 데코레이터 계약
+
+기반 클래스에 선언한 직렬화 메타데이터는 파생 DTO에도 상속됩니다. 공통 필드에 적용한 `@Expose()`, `@Exclude()`, `@Transform()` 규칙은 서브클래스 인스턴스를 직렬화할 때도 그대로 반영됩니다.
+
+### 일반 객체 안전성
+
+`serialize()`는 일반 객체와 null-prototype 레코드를 데코레이터가 붙은 클래스 인스턴스로 오인하지 않습니다. 사용자 정의 `constructor` 필드나 안전하지 않은 `constructor` 값을 가진 객체도 예외 없이 안전하게 순회합니다.
+
+### 비JSON leaf 값
+
+`serialize()`는 데코레이터 메타데이터를 적용하고 배열/일반 객체를 재귀적으로 순회하지만, 모든 leaf 값을 엄격한 JSON 타입으로 강제 변환하지는 않습니다. `Date`, `bigint`, 함수, `symbol` 같은 값은 `@Transform(...)`이나 최종 HTTP 응답 작성 전에 직접 정규화하지 않으면 그대로 통과할 수 있습니다.
+
+### HTTP 인터셉터와 함께 사용
+
+fluo HTTP 애플리케이션에서는 `SerializerInterceptor`를 사용하여 컨트롤러에서 나가는 모든 응답을 자동으로 직렬화할 수 있습니다.
+
+```typescript
+import { Controller, Get, UseInterceptors } from '@fluojs/http';
+import { SerializerInterceptor } from '@fluojs/serialization';
+
+@Controller('/users')
+@UseInterceptors(SerializerInterceptor)
+class UsersController {
+  @Get('/')
+  findAll() {
+    return [new UserEntity({ ... }), new UserEntity({ ... })];
+  }
+}
+```
+
+## 공개 API 개요
+
+### 데코레이터
+- `@Expose(options?)`: 포함할 속성을 표시합니다. 클래스에 사용하여 기본 동작을 설정할 수도 있습니다.
+- `@Exclude()`: 직렬화 중에 무시할 속성을 표시합니다.
+- `@Transform(fn)`: 속성에 대한 변환 함수를 등록합니다.
+
+### 엔진
+- `serialize(value)`: 객체/배열을 재귀적으로 순회하며 직렬화 규칙과 데코레이터를 적용합니다.
+- `SerializerInterceptor`: 핸들러의 반환 값에 대해 `serialize`를 호출하는 fluo HTTP 인터셉터입니다.
+
+## 관련 패키지
+
+- `@fluojs/http`: `SerializerInterceptor`를 통한 자동 출력 가공을 지원합니다.
+- `@fluojs/validation`: **입력** 측면(일반 객체를 클래스 인스턴스로 변환)을 담당하는 대응 패키지입니다.
+
+## 예제 소스
+
+- `packages/serialization/src/serialize.test.ts`: 다양한 직렬화 시나리오에 대한 상세 예제.
+- `packages/serialization/src/serializer-interceptor.test.ts`: HTTP 컨텍스트 내에서의 사용법.

package/README.md

@@ -0,0 +1,130 @@
+# @fluojs/serialization
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+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)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+pnpm add @fluojs/serialization
+```
+
+## When to Use
+
+- when you need output DTOs to expose only a controlled subset of fields
+- when sensitive values such as password hashes or internal identifiers must never leave the response boundary
+- when response data needs lightweight synchronous transforms during serialization
+- when you want an HTTP interceptor to apply the same serialization rules automatically
+
+## Quick Start
+
+```ts
+import { Exclude, Expose, Transform, serialize } from '@fluojs/serialization';
+
+class UserEntity {
+  @Expose()
+  id = '';
+
+  @Expose()
+  @Transform((value) => value.toUpperCase())
+  username = '';
+
+  @Exclude()
+  passwordHash = '';
+}
+
+const user = Object.assign(new UserEntity(), {
+  id: '1',
+  username: 'fluo',
+  passwordHash: 'secret',
+});
+
+console.log(serialize(user));
+// { id: '1', username: 'FLUO' }
+```
+
+## Common Patterns
+
+### Expose-only output DTOs
+
+```ts
+import { Expose } from '@fluojs/serialization';
+
+@Expose({ excludeExtraneous: true })
+class SecureDto {
+  @Expose()
+  publicData = 'visible';
+
+  internalData = 'hidden';
+}
+```
+
+### Value transforms
+
+```ts
+import { Transform } from '@fluojs/serialization';
+
+class ProductDto {
+  @Transform((price) => `$${price.toFixed(2)}`)
+  price = 0;
+}
+```
+
+### HTTP response shaping with an interceptor
+
+```ts
+import { Controller, Get, UseInterceptors } from '@fluojs/http';
+import { SerializerInterceptor } from '@fluojs/serialization';
+
+@Controller('/users')
+@UseInterceptors(SerializerInterceptor)
+class UsersController {
+  @Get('/')
+  findAll() {
+    return [new UserEntity()];
+  }
+}
+```
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+## Public API Overview
+
+- **Decorators**: `Expose`, `Exclude`, `Transform`
+- **Engine**: `serialize(value)`
+- **HTTP integration**: `SerializerInterceptor`
+
+## Related Packages
+
+- `@fluojs/http`: applies `SerializerInterceptor` to HTTP handlers
+- `@fluojs/validation`: handles input-side DTO materialization and validation
+
+## Example Sources
+
+- `packages/serialization/src/serialize.test.ts`
+- `packages/serialization/src/serializer-interceptor.test.ts`

package/dist/decorators/exclude.d.ts

@@ -0,0 +1,18 @@
+type StandardFieldDecoratorFn = <This, Value>(value: undefined, context: ClassFieldDecoratorContext<This, Value>) => void;
+type FieldDecoratorLike = StandardFieldDecoratorFn;
+/**
+ * Excludes the decorated field from serialized output.
+ *
+ * @returns A field decorator that marks the property as omitted during serialization.
+ *
+ * @example
+ * ```ts
+ * class UserEntity {
+ *   @Exclude()
+ *   passwordHash = '';
+ * }
+ * ```
+ */
+export declare function Exclude(): FieldDecoratorLike;
+export {};
+//# sourceMappingURL=exclude.d.ts.map

package/dist/decorators/exclude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclude.d.ts","sourceRoot":"","sources":["../../src/decorators/exclude.ts"],"names":[],"mappings":"AAIA,KAAK,wBAAwB,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;AAC1H,KAAK,kBAAkB,GAAG,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,IAAI,kBAAkB,CAS5C"}

package/dist/decorators/exclude.js

@@ -0,0 +1,23 @@
+import { updateFieldSerializationMetadata } from '../metadata.js';
+/**
+ * Excludes the decorated field from serialized output.
+ *
+ * @returns A field decorator that marks the property as omitted during serialization.
+ *
+ * @example
+ * ```ts
+ * class UserEntity {
+ *   @Exclude()
+ *   passwordHash = '';
+ * }
+ * ```
+ */
+export function Exclude() {
+  const decorator = (_value, context) => {
+    updateFieldSerializationMetadata(context.metadata, context.name, current => ({
+      ...current,
+      excluded: true
+    }));
+  };
+  return decorator;
+}

package/dist/decorators/expose.d.ts

@@ -0,0 +1,33 @@
+type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
+type StandardFieldDecoratorFn = <This, Value>(value: undefined, context: ClassFieldDecoratorContext<This, Value>) => void;
+type ClassOrFieldDecoratorLike = StandardClassDecoratorFn & StandardFieldDecoratorFn;
+/**
+ * Class-level options accepted by `@Expose(...)`.
+ */
+export interface ExposeClassOptions {
+    /**
+     * When enabled on a class, only fields marked with `@Expose()` are emitted.
+     */
+    excludeExtraneous?: boolean;
+}
+/**
+ * Marks a class or field as serializable output.
+ *
+ * - On classes, configures class-level serialization behavior.
+ * - On fields, marks the field as explicitly exposed.
+ *
+ * @param options Optional class-level serialization settings.
+ * @returns A decorator that updates serialization metadata on the class or field.
+ *
+ * @example
+ * ```ts
+ * @Expose({ excludeExtraneous: true })
+ * class UserDto {
+ *   @Expose()
+ *   id = '';
+ * }
+ * ```
+ */
+export declare function Expose(options?: ExposeClassOptions): ClassOrFieldDecoratorLike;
+export {};
+//# sourceMappingURL=expose.d.ts.map

package/dist/decorators/expose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expose.d.ts","sourceRoot":"","sources":["../../src/decorators/expose.ts"],"names":[],"mappings":"AAIA,KAAK,wBAAwB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC1F,KAAK,wBAAwB,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;AAG1H,KAAK,yBAAyB,GAAG,wBAAwB,GAAG,wBAAwB,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,yBAAyB,CAmB9E"}

package/dist/decorators/expose.js

@@ -0,0 +1,39 @@
+import { updateClassSerializationOptions, updateFieldSerializationMetadata } from '../metadata.js';
+
+/**
+ * Class-level options accepted by `@Expose(...)`.
+ */
+
+/**
+ * Marks a class or field as serializable output.
+ *
+ * - On classes, configures class-level serialization behavior.
+ * - On fields, marks the field as explicitly exposed.
+ *
+ * @param options Optional class-level serialization settings.
+ * @returns A decorator that updates serialization metadata on the class or field.
+ *
+ * @example
+ * ```ts
+ * @Expose({ excludeExtraneous: true })
+ * class UserDto {
+ *   @Expose()
+ *   id = '';
+ * }
+ * ```
+ */
+export function Expose(options) {
+  const decorator = (_value, context) => {
+    if (context.kind === 'class') {
+      updateClassSerializationOptions(context.metadata, {
+        excludeExtraneous: options?.excludeExtraneous
+      });
+      return;
+    }
+    updateFieldSerializationMetadata(context.metadata, context.name, current => ({
+      ...current,
+      exposed: true
+    }));
+  };
+  return decorator;
+}

package/dist/decorators/transform.d.ts

@@ -0,0 +1,20 @@
+import { type TransformFunction } from '../metadata.js';
+type StandardFieldDecoratorFn = <This, Value>(value: undefined, context: ClassFieldDecoratorContext<This, Value>) => void;
+type FieldDecoratorLike = StandardFieldDecoratorFn;
+/**
+ * Applies a synchronous transformation to the decorated field during serialization.
+ *
+ * @param transform Function that maps the raw field value to the serialized value.
+ * @returns A field decorator that appends the transform to the field metadata.
+ *
+ * @example
+ * ```ts
+ * class ProductDto {
+ *   @Transform((price) => `$${Number(price).toFixed(2)}`)
+ *   price = 0;
+ * }
+ * ```
+ */
+export declare function Transform(transform: TransformFunction): FieldDecoratorLike;
+export {};
+//# sourceMappingURL=transform.d.ts.map

package/dist/decorators/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/decorators/transform.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,iBAAiB,EAAoC,MAAM,gBAAgB,CAAC;AAE1F,KAAK,wBAAwB,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;AAC1H,KAAK,kBAAkB,GAAG,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,iBAAiB,GAAG,kBAAkB,CAS1E"}

package/dist/decorators/transform.js

@@ -0,0 +1,24 @@
+import { updateFieldSerializationMetadata } from '../metadata.js';
+/**
+ * Applies a synchronous transformation to the decorated field during serialization.
+ *
+ * @param transform Function that maps the raw field value to the serialized value.
+ * @returns A field decorator that appends the transform to the field metadata.
+ *
+ * @example
+ * ```ts
+ * class ProductDto {
+ *   @Transform((price) => `$${Number(price).toFixed(2)}`)
+ *   price = 0;
+ * }
+ * ```
+ */
+export function Transform(transform) {
+  const decorator = (_value, context) => {
+    updateFieldSerializationMetadata(context.metadata, context.name, current => ({
+      ...current,
+      transforms: [...(current?.transforms ?? []), transform]
+    }));
+  };
+  return decorator;
+}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,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';

package/dist/metadata.d.ts

@@ -0,0 +1,15 @@
+import { type MetadataPropertyKey } from '@fluojs/core';
+export type TransformFunction = (value: unknown) => unknown;
+export interface ClassSerializationOptions {
+    excludeExtraneous?: boolean;
+}
+export interface SerializationFieldMetadata {
+    excluded?: boolean;
+    exposed?: boolean;
+    transforms?: TransformFunction[];
+}
+export declare function updateClassSerializationOptions(metadata: unknown, partial: ClassSerializationOptions): void;
+export declare function updateFieldSerializationMetadata(metadata: unknown, propertyKey: MetadataPropertyKey, update: (current: SerializationFieldMetadata | undefined) => SerializationFieldMetadata): void;
+export declare function getClassSerializationOptions(constructor: Function): ClassSerializationOptions;
+export declare function getFieldSerializationMetadata(constructor: Function): Map<MetadataPropertyKey, SerializationFieldMetadata>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +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"}

package/dist/metadata.js

@@ -0,0 +1,79 @@
+import { metadataSymbol } from '@fluojs/core/internal';
+const standardSerializationClassMetadataKey = Symbol.for('fluo.standard.serialization.class');
+const standardSerializationFieldMetadataKey = Symbol.for('fluo.standard.serialization.field');
+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) {
+  const bag = getStandardMetadataBag(metadata);
+  const current = bag[standardSerializationFieldMetadataKey];
+  if (current) {
+    return current;
+  }
+  const created = new Map();
+  bag[standardSerializationFieldMetadataKey] = created;
+  return created;
+}
+function getClassMetadataObject(metadata) {
+  const bag = getStandardMetadataBag(metadata);
+  const current = bag[standardSerializationClassMetadataKey];
+  if (current) {
+    return current;
+  }
+  const created = {};
+  bag[standardSerializationClassMetadataKey] = created;
+  return created;
+}
+function getOwnMetadataBagFromConstructor(constructor) {
+  if (!Object.prototype.hasOwnProperty.call(constructor, metadataSymbol)) {
+    return undefined;
+  }
+  return constructor[metadataSymbol];
+}
+function getConstructorMetadataBags(constructor) {
+  const bags = [];
+  let current = constructor;
+  while (current && current !== Function.prototype) {
+    const bag = getOwnMetadataBagFromConstructor(current);
+    if (bag) {
+      bags.unshift(bag);
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return bags;
+}
+export function updateClassSerializationOptions(metadata, partial) {
+  Object.assign(getClassMetadataObject(metadata), partial);
+}
+export function updateFieldSerializationMetadata(metadata, propertyKey, update) {
+  const map = getFieldMetadataMap(metadata);
+  map.set(propertyKey, update(map.get(propertyKey)));
+}
+export function getClassSerializationOptions(constructor) {
+  return getConstructorMetadataBags(constructor).reduce((options, bag) => ({
+    ...options,
+    ...bag[standardSerializationClassMetadataKey]
+  }), {});
+}
+export function getFieldSerializationMetadata(constructor) {
+  const merged = new Map();
+  for (const bag of getConstructorMetadataBags(constructor)) {
+    const fieldMetadata = bag[standardSerializationFieldMetadataKey];
+    if (!fieldMetadata) {
+      continue;
+    }
+    for (const [propertyKey, metadata] of fieldMetadata.entries()) {
+      const current = merged.get(propertyKey);
+      merged.set(propertyKey, {
+        ...current,
+        ...metadata,
+        transforms: [...(current?.transforms ?? []), ...(metadata.transforms ?? [])]
+      });
+    }
+  }
+  return merged;
+}

package/dist/serialize.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Serializes class instances and object graphs into JSON-safe plain values.
+ *
+ * Serialization honors `@Expose()`, `@Exclude()`, and `@Transform()` metadata.
+ * Cycles and repeated references are handled without unbounded recursion.
+ *
+ * @typeParam T Input value type.
+ * @param value Value or object graph to serialize.
+ * @returns A plain JSON-safe structure ready for HTTP response writing.
+ *
+ * @example
+ * ```ts
+ * class UserEntity {
+ *   id = '1';
+ * }
+ *
+ * serialize(new UserEntity());
+ * ```
+ */
+export declare function serialize<T = unknown>(value: T): unknown;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +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"}

package/dist/serialize.js

@@ -0,0 +1,187 @@
+import { getClassSerializationOptions, getFieldSerializationMetadata } from './metadata.js';
+function isObjectLike(value) {
+  return typeof value === 'object' && value !== null;
+}
+function isPlainObject(value) {
+  if (!isObjectLike(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function getSerializableConstructor(value) {
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === null || prototype === Object.prototype) {
+    return undefined;
+  }
+  const constructor = Reflect.get(prototype, 'constructor');
+  return typeof constructor === 'function' ? constructor : undefined;
+}
+function applyTransforms(value, metadata) {
+  let transformed = value;
+  for (const transform of metadata.transforms ?? []) {
+    transformed = transform(transformed);
+  }
+  return transformed;
+}
+function assignSerializedProperty(target, propertyKey, value) {
+  if (propertyKey === '__proto__' || propertyKey === 'constructor' || propertyKey === 'prototype') {
+    Object.defineProperty(target, propertyKey, {
+      configurable: true,
+      enumerable: true,
+      value,
+      writable: true
+    });
+    return;
+  }
+  target[propertyKey] = value;
+}
+function resolveCandidateKeys(value, fieldMetadata, excludeExtraneous) {
+  if (excludeExtraneous) {
+    return [...fieldMetadata.entries()].filter(([, metadata]) => metadata.exposed === true).map(([propertyKey]) => propertyKey);
+  }
+  const keys = new Set([...Object.keys(value), ...Object.getOwnPropertySymbols(value)]);
+  for (const [propertyKey, metadata] of fieldMetadata) {
+    if (metadata.exposed === true) {
+      keys.add(propertyKey);
+    }
+  }
+  return [...keys];
+}
+function getCachedMetadata(constructor, context) {
+  const cached = context.metadataCache.get(constructor);
+  if (cached) {
+    return cached;
+  }
+  const next = {
+    classOptions: getClassSerializationOptions(constructor),
+    fieldMetadata: getFieldSerializationMetadata(constructor)
+  };
+  context.metadataCache.set(constructor, next);
+  return next;
+}
+function getCircularOrSharedValue(value, context) {
+  const cached = context.references.get(value);
+  if (!cached) {
+    return undefined;
+  }
+  if (cached.active) {
+    return undefined;
+  }
+  return cached.value;
+}
+function markSerializationStart(value, serialized, context) {
+  context.references.set(value, {
+    active: true,
+    value: serialized
+  });
+}
+function markSerializationComplete(value, context) {
+  const cached = context.references.get(value);
+  if (!cached) {
+    return;
+  }
+  cached.active = false;
+}
+function serializeWithTrackedReference(value, context, create, fill) {
+  const cachedValue = getCircularOrSharedValue(value, context);
+  if (context.references.has(value)) {
+    return cachedValue;
+  }
+  const serialized = create();
+  markSerializationStart(value, serialized, context);
+  try {
+    fill(serialized);
+    return serialized;
+  } finally {
+    markSerializationComplete(value, context);
+  }
+}
+function serializeClassInstance(value, context) {
+  const constructor = getSerializableConstructor(value);
+  if (!constructor) {
+    return serializeRecord(value, context);
+  }
+  const {
+    classOptions,
+    fieldMetadata
+  } = getCachedMetadata(constructor, context);
+  const hasMetadata = fieldMetadata.size > 0 || classOptions.excludeExtraneous === true;
+  if (!hasMetadata) {
+    return serializeRecord(value, context);
+  }
+  return serializeWithTrackedReference(value, context, () => ({}), serialized => {
+    const candidateKeys = resolveCandidateKeys(value, fieldMetadata, classOptions.excludeExtraneous === true);
+    for (const propertyKey of candidateKeys) {
+      const metadata = fieldMetadata.get(propertyKey);
+      if (metadata?.excluded) {
+        continue;
+      }
+      const raw = value[propertyKey];
+      if (raw === undefined && classOptions.excludeExtraneous === true && metadata?.exposed !== true) {
+        continue;
+      }
+      const transformed = metadata ? applyTransforms(raw, metadata) : raw;
+      assignSerializedProperty(serialized, propertyKey, serializeInternal(transformed, context));
+    }
+  });
+}
+function serializeRecord(value, context) {
+  const symbolKeys = Object.getOwnPropertySymbols(value).filter(key => Object.prototype.propertyIsEnumerable.call(value, key));
+  const keys = [...Object.keys(value), ...symbolKeys];
+  return serializeWithTrackedReference(value, context, () => ({}), serialized => {
+    for (const propertyKey of keys) {
+      const propertyValue = value[propertyKey];
+      assignSerializedProperty(serialized, propertyKey, serializeInternal(propertyValue, context));
+    }
+  });
+}
+function serializeInternal(value, context) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return serializeWithTrackedReference(value, context, () => [], serialized => {
+      for (const item of value) {
+        serialized.push(serializeInternal(item, context));
+      }
+    });
+  }
+  if (value instanceof Date) {
+    return value;
+  }
+  if (isObjectLike(value)) {
+    if (isPlainObject(value)) {
+      return serializeRecord(value, context);
+    }
+    return serializeClassInstance(value, context);
+  }
+  return value;
+}
+
+/**
+ * Serializes class instances and object graphs into JSON-safe plain values.
+ *
+ * Serialization honors `@Expose()`, `@Exclude()`, and `@Transform()` metadata.
+ * Cycles and repeated references are handled without unbounded recursion.
+ *
+ * @typeParam T Input value type.
+ * @param value Value or object graph to serialize.
+ * @returns A plain JSON-safe structure ready for HTTP response writing.
+ *
+ * @example
+ * ```ts
+ * class UserEntity {
+ *   id = '1';
+ * }
+ *
+ * serialize(new UserEntity());
+ * ```
+ */
+export function serialize(value) {
+  const context = {
+    metadataCache: new WeakMap(),
+    references: new WeakMap()
+  };
+  return serializeInternal(value, context);
+}

package/dist/serializer-interceptor.d.ts

@@ -0,0 +1,13 @@
+import type { CallHandler, Interceptor, InterceptorContext } from '@fluojs/http';
+/**
+ * HTTP interceptor that serializes handler results before response writing.
+ *
+ * @remarks
+ * Use this at the controller or route level when handlers return class instances
+ * and you want `@Expose()`, `@Exclude()`, and `@Transform()` metadata applied
+ * automatically.
+ */
+export declare class SerializerInterceptor implements Interceptor {
+    intercept(_context: InterceptorContext, next: CallHandler): Promise<unknown>;
+}
+//# sourceMappingURL=serializer-interceptor.d.ts.map

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

@@ -0,0 +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,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CAInF"}

package/dist/serializer-interceptor.js

@@ -0,0 +1,16 @@
+import { serialize } from './serialize.js';
+
+/**
+ * HTTP interceptor that serializes handler results before response writing.
+ *
+ * @remarks
+ * Use this at the controller or route level when handlers return class instances
+ * and you want `@Expose()`, `@Exclude()`, and `@Transform()` metadata applied
+ * automatically.
+ */
+export class SerializerInterceptor {
+  async intercept(_context, next) {
+    const value = await next.handle();
+    return serialize(value);
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fluojs/serialization",
+  "description": "Class-based response serialization and output shaping interceptors for Fluo.",
+  "keywords": [
+    "fluo",
+    "serialization",
+    "response",
+    "interceptor",
+    "output",
+    "transform"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/serialization"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}