@fluojs/validation 1.0.6 → 2.0.0

package/README.ko.md

@@ -2,6 +2,8 @@
 
 <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를 위한 입력값 검증 데코레이터, Mapped DTO 헬퍼 및 검증 엔진입니다.
 
 ## 목차
@@ -74,11 +76,13 @@ class rule이 실행되기 전에 deterministic `DtoValidationError`로 거부
 DTO 바인딩 메타데이터를 적용한 뒤 `@ValidateNested(...)` 필드를 재귀적으로
 실체화합니다. 어떤 요청 소스를 선택하고 스칼라 값을 변환할지는 transport 또는
 binder가 검증 전에 담당한다는 request-pipeline 계약을 유지합니다.
-Plain 입력 객체를 materialize할 때 안전한 추가 own enumerable 속성은 유지됩니다. `__proto__`, `constructor`,
+Plain 입력 객체를 materialize할 때 안전한 추가 own enumerable 속성은 기본적으로 유지됩니다. `__proto__`, `constructor`,
 `prototype` 같은 위험한 key와 inherited 또는 non-enumerable 속성만 제외합니다.
-이는 `ValidationPipe` 스타일의 whitelist 또는 `forbidNonWhitelisted` 경계가
-아닙니다. 애플리케이션에 해당 정책이 필요하면 materialization 전에 추가 입력을
-명시적으로 shaping하거나 거부해야 합니다.
+세 번째 `materialize()` 인자로 `{ undeclaredProperties: 'reject' }`를 전달하면
+초기화된 DTO field, validation 또는 binding metadata field, binding alias로 선언되지
+않은 안전한 enumerable 속성을 거부합니다. 이 정책은 plain nested DTO 값에도
+재귀적으로 적용되며 입력을 조용히 제거하지 않고 `UNDECLARED_PROPERTY` issue를
+보고합니다. 기존 DTO instance는 undeclared-property 경계로 검사하지 않습니다.
 선언된 중첩 DTO의 인스턴스인 기존 중첩 값은 그대로 보존하고, plain 중첩 값만
 해당 필드 또는 collection entry 단위로 실체화합니다.
 `materialize()`에 넘기는 루트 값은 plain 객체이거나 대상 DTO 인스턴스여야 합니다.
@@ -143,6 +147,11 @@ validation 및 binding metadata를 보존합니다. `PickType`, `OmitType`,
 `PartialType`은 생략되었거나 optional이 된 필드에 의존할 수 있는 base
 class-level validator를 derived DTO로 전달하지 않습니다.
 
+`IntersectionType(...)` source가 같은 property에 서로 다른
+`@ValidateNested(...)` target을 선언하면 모든 nested rule이 보존되고 검증됩니다.
+공유 property의 plain value는 초기 실체화 중 plain 상태로 유지되므로 각 nested
+target이 해당 value를 독립적으로 실체화하고 검증할 수 있습니다.
+
 ### Standard Schema 지원
 
 Standard Schema adapter는 유효하지 않은 입력을 명시적인 issue로 보고해야 합니다. issue가 없는 검증 결과는 성공으로 처리합니다.
@@ -161,6 +170,14 @@ class RestrictedUserDto {
 
 `ValidateClass(...)`는 custom class-level validator도 받을 수 있습니다. `Validate(...)`는 built-in decorator만으로 부족할 때 custom field-level validator를 붙이고, `ValidateIf(...)`는 predicate가 false를 반환하면 dependent validator를 short-circuit합니다.
 
+### Custom field 검증
+
+`Validate(callback)`는 callback을 `(value, context)`로 호출합니다. `context.dto`는
+포함하는 DTO이고, `context.propertyKey`는 decorator가 적용된 field key입니다.
+
+`@IsObject()`는 null-prototype record를 포함한 plain object만 허용합니다. Class
+instance, `Date`, `Map`, `Set` 값은 거부합니다.
+
 ### 네트워크 검증기
 
 `@IsIP()`는 기본적으로 IPv4와 IPv6 문자열을 모두 검증합니다. 한 IP 버전으로
@@ -179,9 +196,12 @@ Array, `Set`, `Map` member는 자동으로 검증되고 실체화되므로 neste
 `materialize()`는 의도적으로 엄격합니다. Transport가 `'42'`를 넘기고 DTO가 `number`를 기대한다면, transport나 binding layer가 먼저 변환해야 합니다.
 `@IsLatitude()`, `@IsLongitude()`를 포함한 numeric validator는 numeric string을 이미 변환된 number처럼 취급하지 않고 DTO의 numeric 값을 검증합니다.
 
+`@IsEnum(...)`은 선언된 enum 값만 허용합니다. 숫자형 TypeScript enum에서 생성된
+reverse-map 멤버 이름은 값이 아니므로 거부됩니다.
+
 ## 공개 API
 
-- **검증 엔진**: `DefaultValidator`, `DtoValidationError`, `ValidationIssue`, `Validator`
+- **검증 엔진**: `DefaultValidator`, `DtoValidationError`, `MaterializeOptions`, `ValidationIssue`, `Validator`
 - **핵심 데코레이터**: `IsString`, `IsNumber`, `IsBoolean`, `IsDate`, `IsArray`, `IsObject`, `IsEnum`, `IsInt`, `IsDefined`, `IsOptional`, `ValidateNested`, `ValidateIf`, `Validate`, `ValidateClass`
 - **존재 및 비교 데코레이터**: `IsEmpty`, `IsNotEmpty`, `Equals`, `NotEquals`, `IsIn`, `IsNotIn`
 - **문자열 및 네트워크 데코레이터**: `IsEmail`, `IsUrl`, `IsUUID`, `IsIP`, `IsAlpha`, `IsAlphanumeric`, `IsAscii`, `IsBase64`, `IsBooleanString`, `IsDataURI`, `IsDateString`, `IsDecimal`, `IsFQDN`, `IsHexColor`, `IsHexadecimal`, `IsJSON`, `IsJWT`, `IsLocale`, `IsLowercase`, `IsMagnetURI`, `IsMimeType`, `IsMongoId`, `IsNumberString`, `IsPort`, `IsRFC3339`, `IsSemVer`, `IsUppercase`, `IsISO8601`, `Matches`, `Length`, `MinLength`, `MaxLength`, `Contains`, `NotContains`

package/README.md

@@ -2,6 +2,8 @@
 
 <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.
+
 Input-side validation decorators, mapped DTO helpers, and the validation engine for fluo.
 
 ## Table of Contents
@@ -77,11 +79,14 @@ coercion.
 applies DTO binding metadata, and recursively hydrates `@ValidateNested(...)`
 fields. It preserves the request-pipeline contract that transports or binders own
 source selection and scalar conversion before validation runs.
-When materializing a plain input object, safe extra own enumerable properties are retained; only dangerous keys such as
+When materializing a plain input object, safe extra own enumerable properties are retained by default; only dangerous keys such as
 `__proto__`, `constructor`, and `prototype`, plus inherited or non-enumerable
-properties, are excluded. This is not a `ValidationPipe`-style whitelist or
-`forbidNonWhitelisted` boundary. Shape or reject extra input explicitly before
-materialization when an application requires that policy.
+properties, are excluded. Pass `{ undeclaredProperties: 'reject' }` as the third
+`materialize()` argument to reject safe enumerable properties that are not
+initialized DTO fields, validation or binding metadata fields, or binding aliases.
+The policy applies recursively to plain nested DTO values and reports
+`UNDECLARED_PROPERTY` issues instead of silently stripping input. Existing DTO
+instances are not an undeclared-property boundary.
 Existing nested values that are already instances of the declared nested DTO are
 preserved; plain nested values are hydrated only for the affected nested field or
 collection entry.
@@ -147,6 +152,11 @@ the documented subclassing pattern shown above. `PickType`, `OmitType`, and
 `PartialType` do not carry base class-level validators onto derived DTOs because
 those validators can depend on fields that were omitted or made optional.
 
+When `IntersectionType(...)` sources declare different `@ValidateNested(...)`
+targets for the same property, every nested rule is preserved and validated.
+Plain values for that shared property remain plain during the initial hydration
+so each nested target can materialize and validate the value independently.
+
 ### Standard Schema support
 
 Standard Schema adapters are expected to report invalid input through explicit issues. Validation results without issues are treated as successful.
@@ -165,6 +175,14 @@ class RestrictedUserDto {
 
 `ValidateClass(...)` also accepts custom class-level validators. `Validate(...)` attaches custom field-level validators when built-in decorators are not enough, and `ValidateIf(...)` short-circuits dependent validators when its predicate returns false.
 
+### Custom field validation
+
+`Validate(callback)` invokes `callback(value, context)`. `context.dto` is the
+containing DTO, and `context.propertyKey` is the decorated field key.
+
+`@IsObject()` accepts only plain objects, including null-prototype records. It
+rejects class instances, `Date`, `Map`, and `Set` values.
+
 ### Network validators
 
 `@IsIP()` validates IPv4 and IPv6 strings by default. Pass `@IsIP('4')` or
@@ -183,9 +201,12 @@ Pass either a DTO class or a lazy constructor factory such as `() => ChildDto` o
 `materialize()` is intentionally strict. If a transport gives you `'42'` and your DTO expects `number`, the transport or binding layer must convert it first.
 Numeric validators, including `@IsLatitude()` and `@IsLongitude()`, validate numeric DTO values without treating numeric strings as already-converted numbers.
 
+`@IsEnum(...)` accepts declared enum values. For numeric TypeScript enums, generated
+reverse-map member names are not values and are rejected.
+
 ## Public API
 
-- **Validator engine**: `DefaultValidator`, `DtoValidationError`, `ValidationIssue`, `Validator`
+- **Validator engine**: `DefaultValidator`, `DtoValidationError`, `MaterializeOptions`, `ValidationIssue`, `Validator`
 - **Core decorators**: `IsString`, `IsNumber`, `IsBoolean`, `IsDate`, `IsArray`, `IsObject`, `IsEnum`, `IsInt`, `IsDefined`, `IsOptional`, `ValidateNested`, `ValidateIf`, `Validate`, `ValidateClass`
 - **Presence and comparison decorators**: `IsEmpty`, `IsNotEmpty`, `Equals`, `NotEquals`, `IsIn`, `IsNotIn`
 - **String and network decorators**: `IsEmail`, `IsUrl`, `IsUUID`, `IsIP`, `IsAlpha`, `IsAlphanumeric`, `IsAscii`, `IsBase64`, `IsBooleanString`, `IsDataURI`, `IsDateString`, `IsDecimal`, `IsFQDN`, `IsHexColor`, `IsHexadecimal`, `IsJSON`, `IsJWT`, `IsLocale`, `IsLowercase`, `IsMagnetURI`, `IsMimeType`, `IsMongoId`, `IsNumberString`, `IsPort`, `IsRFC3339`, `IsSemVer`, `IsUppercase`, `IsISO8601`, `Matches`, `Length`, `MinLength`, `MaxLength`, `Contains`, `NotContains`

package/dist/decorators.d.ts

@@ -109,7 +109,8 @@ export declare const IsDate: (options?: ValidationDecoratorOptions) => FieldDeco
  */
 export declare const IsArray: (options?: ValidationDecoratorOptions) => FieldDecoratorFn;
 /**
- * Validates that the decorated field is an object value.
+ * Validates that the decorated field is a plain object value, including a null-prototype record.
+ * Class instances, `Date`, `Map`, and `Set` values are rejected.
  *
  * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an object validation rule.
@@ -562,7 +563,8 @@ export declare function ArrayUnique(selectorOrOptions?: ((value: unknown) => unk
 /**
  * Registers a custom field-level validation function.
  *
- * @param validate Custom validator callback invoked with `(dto, value)`.
+ * @param validate Custom validator callback invoked with `(value, context)`, where `context.dto`
+ * is the containing DTO and `context.propertyKey` is the decorated field key.
  * @param options Optional custom-validator metadata (`message`, `code`, `source`, `each`).
  * @returns A field decorator that registers a custom validation rule.
  */

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"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"}

package/dist/decorators.js

@@ -1,5 +1,6 @@
 import { createArrayValidationDecorator, createFlagValidationDecorator, createValidationDecorator, createValidationOptionsWithConfigDecorator, createValidatorJsDecorator } from './internal/decorator-factories.js';
 import { appendStandardClassValidationRule } from './internal/decorator-metadata.js';
+import { normalizeEnumValues } from './internal/enum-values.js';
 import { createClassValidatorFromStandardSchema, isStandardSchemaLike } from './standard-schema.js';
 function resolveClassValidator(validate) {
   if (!isStandardSchemaLike(validate)) {
@@ -169,7 +170,8 @@ export const IsArray = createFlagValidationDecorator(options => ({
   ...options
 }));
 /**
- * Validates that the decorated field is an object value.
+ * Validates that the decorated field is a plain object value, including a null-prototype record.
+ * Class instances, `Date`, `Map`, and `Set` values are rejected.
  *
  * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an object validation rule.
@@ -217,7 +219,7 @@ export const IsNegative = createFlagValidationDecorator(options => ({
  * @returns A field decorator that registers an enum-membership rule.
  */
 export function IsEnum(values, options) {
-  const normalized = Array.isArray(values) ? values : Object.values(values);
+  const normalized = normalizeEnumValues(values);
   return createValidationDecorator(() => ({
     kind: 'enum',
     values: normalized,
@@ -770,7 +772,8 @@ export function ArrayUnique(selectorOrOptions, options) {
 /**
  * Registers a custom field-level validation function.
  *
- * @param validate Custom validator callback invoked with `(dto, value)`.
+ * @param validate Custom validator callback invoked with `(value, context)`, where `context.dto`
+ * is the containing DTO and `context.propertyKey` is the decorated field key.
  * @param options Optional custom-validator metadata (`message`, `code`, `source`, `each`).
  * @returns A field decorator that registers a custom validation rule.
  */

package/dist/internal/dto-materialization.d.ts

@@ -0,0 +1,45 @@
+import type { Constructor } from '@fluojs/core';
+import type { MaterializeOptions } from '../types.js';
+/**
+ * Carries invocation-local DTO traversal state across materialization and validation.
+ */
+export interface NestedTraversalContext {
+    readonly active: WeakSet<object>;
+    readonly declaredNestedKeys?: WeakMap<object, ReadonlySet<PropertyKey>>;
+    readonly hydrateExistingInstances?: boolean;
+    readonly undeclaredProperties?: MaterializeOptions['undeclaredProperties'];
+    readonly materialized?: WeakMap<object, WeakMap<Constructor, object>>;
+}
+/**
+ * Enters a traversal value when it is not already active.
+ *
+ * @param value Candidate traversal value.
+ * @param context Invocation-local traversal state.
+ * @returns Whether traversal may continue for the value.
+ */
+export declare function enterTraversal(value: unknown, context?: NestedTraversalContext): boolean;
+/**
+ * Releases a traversal value after materialization or validation completes.
+ *
+ * @param value Traversal value to release.
+ * @param context Invocation-local traversal state.
+ */
+export declare function exitTraversal(value: unknown, context?: NestedTraversalContext): void;
+/**
+ * Creates or reuses a nested DTO instance for a raw value.
+ *
+ * @param target Nested DTO constructor.
+ * @param rawValue Raw nested value.
+ * @param context Invocation-local traversal state.
+ * @param fieldPrefix Parent path used for undeclared-property issues.
+ * @returns The materialized DTO value or the original unsupported value.
+ */
+export declare function createNestedDtoInstance<T>(target: Constructor<T>, rawValue: unknown, context?: NestedTraversalContext, fieldPrefix?: string): T;
+/**
+ * Asserts that a root value can be validated as the requested DTO.
+ *
+ * @param value Root value to validate.
+ * @param target Requested DTO constructor.
+ */
+export declare function assertValidRootValue(value: unknown, target: Constructor): void;
+//# sourceMappingURL=dto-materialization.d.ts.map

package/dist/internal/dto-materialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto-materialization.d.ts","sourceRoot":"","sources":["../../src/internal/dto-materialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,aAAa,CAAC;AAUvE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;IACxE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;IAC3E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;CACvE;AAwED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAWxF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAUpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,QAAQ,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,sBAAsB,EAChC,WAAW,CAAC,EAAE,MAAM,GACnB,CAAC,CA4FH;AAyDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAM9E"}

package/dist/internal/dto-materialization.js

@@ -0,0 +1,204 @@
+import { DtoValidationError } from '../errors.js';
+import { getCachedDtoMetadata } from './dto-metadata-cache.js';
+import { assignSafeOwnEnumerableProperties, getIterableValues, isPlainObject, isSafeOwnEnumerableProperty } from './object-utils.js';
+import { joinFieldPath } from './validation-issues.js';
+
+/**
+ * Carries invocation-local DTO traversal state across materialization and validation.
+ */
+
+const materializationCycleTarget = class {};
+function getMaterializedInstance(rawValue, target, context) {
+  return context?.materialized?.get(rawValue)?.get(target);
+}
+function rememberMaterializedInstance(rawValue, target, instance, context) {
+  if (!context?.materialized) {
+    return;
+  }
+  let instancesByTarget = context.materialized.get(rawValue);
+  if (!instancesByTarget) {
+    instancesByTarget = new WeakMap();
+    context.materialized.set(rawValue, instancesByTarget);
+  }
+  instancesByTarget.set(target, instance);
+}
+function canMaterialize(value, target) {
+  return value instanceof target || isPlainObject(value);
+}
+function collectDeclaredKeys(instance, target) {
+  const metadata = getCachedDtoMetadata(target);
+  return new Set([...Reflect.ownKeys(instance), ...metadata.mergedPropertyKeys, ...Array.from(metadata.bindingMap.values()).flatMap(binding => binding.key === undefined ? [] : [binding.key])]);
+}
+function rememberConflictingNestedKeys(value, targets, context) {
+  if (!context?.declaredNestedKeys) {
+    return;
+  }
+  const declaredKeys = new Set();
+  for (const target of targets) {
+    for (const key of collectDeclaredKeys(new target(), target)) {
+      declaredKeys.add(key);
+    }
+  }
+  for (const entry of getIterableValues(value) ?? [value]) {
+    if (isPlainObject(entry)) {
+      context.declaredNestedKeys.set(entry, declaredKeys);
+    }
+  }
+}
+
+/**
+ * Enters a traversal value when it is not already active.
+ *
+ * @param value Candidate traversal value.
+ * @param context Invocation-local traversal state.
+ * @returns Whether traversal may continue for the value.
+ */
+export function enterTraversal(value, context) {
+  if (!context || typeof value !== 'object' || value === null) {
+    return true;
+  }
+  if (context.active.has(value)) {
+    return false;
+  }
+  context.active.add(value);
+  return true;
+}
+
+/**
+ * Releases a traversal value after materialization or validation completes.
+ *
+ * @param value Traversal value to release.
+ * @param context Invocation-local traversal state.
+ */
+export function exitTraversal(value, context) {
+  if (!context || typeof value !== 'object' || value === null) {
+    return;
+  }
+  if (context.materialized?.get(value)?.has(materializationCycleTarget)) {
+    return;
+  }
+  context.active.delete(value);
+}
+
+/**
+ * Creates or reuses a nested DTO instance for a raw value.
+ *
+ * @param target Nested DTO constructor.
+ * @param rawValue Raw nested value.
+ * @param context Invocation-local traversal state.
+ * @param fieldPrefix Parent path used for undeclared-property issues.
+ * @returns The materialized DTO value or the original unsupported value.
+ */
+export function createNestedDtoInstance(target, rawValue, context, fieldPrefix) {
+  if (rawValue instanceof target && context?.hydrateExistingInstances !== true) {
+    return rawValue;
+  }
+  if (!canMaterialize(rawValue, target)) {
+    return rawValue;
+  }
+  const rawObject = rawValue;
+  const rememberedInstance = getMaterializedInstance(rawObject, target, context);
+  if (rememberedInstance) {
+    return rememberedInstance;
+  }
+  if (context?.active.has(rawObject)) {
+    rememberMaterializedInstance(rawObject, materializationCycleTarget, rawObject, context);
+    return rawValue;
+  }
+  const instance = rawValue instanceof target ? rawValue : new target();
+  rememberMaterializedInstance(rawObject, target, instance, context);
+  if (!enterTraversal(rawValue, context)) {
+    return rawValue;
+  }
+  try {
+    const metadata = getCachedDtoMetadata(target);
+    if (isPlainObject(rawValue)) {
+      if (context?.undeclaredProperties === 'reject') {
+        const declaredKeys = collectDeclaredKeys(instance, target);
+        const declaredNestedKeys = context.declaredNestedKeys?.get(rawValue);
+        if (declaredNestedKeys) {
+          for (const key of declaredNestedKeys) {
+            declaredKeys.add(key);
+          }
+        }
+        const issues = Reflect.ownKeys(rawValue).filter(key => isSafeOwnEnumerableProperty(rawValue, key) && !declaredKeys.has(key)).map(key => {
+          const field = fieldPrefix ? joinFieldPath(fieldPrefix, String(key)) : String(key);
+          return {
+            code: 'UNDECLARED_PROPERTY',
+            field,
+            message: `${field} is not declared by the DTO.`
+          };
+        });
+        if (issues.length > 0) {
+          throw new DtoValidationError('Validation failed.', issues);
+        }
+      }
+      assignSafeOwnEnumerableProperties(instance, rawValue);
+      for (const propertyKey of metadata.mergedPropertyKeys) {
+        const sourceKey = metadata.bindingMap.get(propertyKey)?.key;
+        if (!sourceKey) continue;
+        instance[propertyKey] = rawValue[sourceKey];
+      }
+    }
+    for (const nestedEntry of metadata.nestedDtoTransforms) {
+      const nestedTargets = metadata.nestedDtoTransforms.filter(candidate => candidate.propertyKey === nestedEntry.propertyKey).map(candidate => candidate.target);
+      const hasConflictingTarget = nestedTargets.some(candidate => candidate !== nestedEntry.target);
+      if (hasConflictingTarget) {
+        rememberConflictingNestedKeys(instance[nestedEntry.propertyKey], nestedTargets, context);
+        continue;
+      }
+      const currentValue = instance[nestedEntry.propertyKey];
+      if (currentValue === undefined || currentValue === null) {
+        continue;
+      }
+      const fieldPath = fieldPrefix ? joinFieldPath(fieldPrefix, String(nestedEntry.propertyKey)) : String(nestedEntry.propertyKey);
+      instance[nestedEntry.propertyKey] = transformNestedCollectionValue(currentValue, nestedEntry.target, context, fieldPath);
+    }
+    return instance;
+  } finally {
+    exitTraversal(rawValue, context);
+  }
+}
+function transformNestedValue(value, target, context, fieldPrefix) {
+  if (value === undefined || value === null) {
+    return value;
+  }
+  if (value instanceof target && context?.hydrateExistingInstances !== true) {
+    return value;
+  }
+  if (!(value instanceof target) && !isPlainObject(value)) {
+    return value;
+  }
+  return createNestedDtoInstance(target, value, context, fieldPrefix);
+}
+function transformNestedCollectionValue(value, target, context, fieldPrefix) {
+  if (Array.isArray(value)) {
+    return value.map((item, index) => transformNestedValue(item, target, context, `${fieldPrefix}[${String(index)}]`));
+  }
+  if (value instanceof Set) {
+    return new Set(Array.from(value.values(), (item, index) => transformNestedValue(item, target, context, `${fieldPrefix}[${String(index)}]`)));
+  }
+  if (value instanceof Map) {
+    return new Map(Array.from(value.entries(), ([key, item], index) => [key, transformNestedValue(item, target, context, `${fieldPrefix}[${String(index)}]`)]));
+  }
+  return transformNestedValue(value, target, context, fieldPrefix);
+}
+function buildInvalidRootIssue() {
+  return {
+    code: 'INVALID_DTO',
+    message: 'DTO root value must be a plain object.'
+  };
+}
+
+/**
+ * Asserts that a root value can be validated as the requested DTO.
+ *
+ * @param value Root value to validate.
+ * @param target Requested DTO constructor.
+ */
+export function assertValidRootValue(value, target) {
+  if (value instanceof target || isPlainObject(value)) {
+    return;
+  }
+  throw new DtoValidationError('Validation failed.', [buildInvalidRootIssue()]);
+}

package/dist/internal/dto-metadata-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto-metadata-cache.d.ts","sourceRoot":"","sources":["../../src/internal/dto-metadata-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EACL,KAAK,uBAAuB,EAE5B,uBAAuB,EAEvB,sBAAsB,EACvB,MAAM,+BAA+B,CAAC;AAMvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,GAAG,WAAW,CAMpF;AAED,KAAK,mBAAmB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,GAAG,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;IAC9D,oBAAoB,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;IACjE,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,kBAAkB,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7C,mBAAmB,EAAE,SAAS;QAC5B,WAAW,EAAE,mBAAmB,CAAC;QACjC,MAAM,EAAE,WAAW,CAAC;KACrB,EAAE,CAAC;CACL;AA+BD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAyB3E"}
+{"version":3,"file":"dto-metadata-cache.d.ts","sourceRoot":"","sources":["../../src/internal/dto-metadata-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EACL,KAAK,uBAAuB,EAC5B,uBAAuB,EAEvB,sBAAsB,EACvB,MAAM,+BAA+B,CAAC;AAMvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,GAAG,WAAW,CAMpF;AAED,KAAK,mBAAmB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,GAAG,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;IAC9D,oBAAoB,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;IACjE,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,kBAAkB,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC7C,mBAAmB,EAAE,SAAS;QAC5B,WAAW,EAAE,mBAAmB,CAAC;QACjC,MAAM,EAAE,WAAW,CAAC;KACrB,EAAE,CAAC;CACL;AA6BD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAyB3E"}

package/dist/internal/dto-metadata-cache.js

@@ -15,14 +15,15 @@ function getDtoBindingMap(target) {
 function collectNestedDtoTransforms(dtoValidationSchema) {
   const nestedEntries = [];
   for (const entry of dtoValidationSchema) {
-    const nestedRule = entry.rules.find(rule => rule.kind === 'nested');
-    if (!nestedRule) {
-      continue;
+    for (const rule of entry.rules) {
+      if (rule.kind !== 'nested') {
+        continue;
+      }
+      nestedEntries.push({
+        propertyKey: entry.propertyKey,
+        target: resolveNestedDto(rule.dto)
+      });
     }
-    nestedEntries.push({
-      propertyKey: entry.propertyKey,
-      target: resolveNestedDto(nestedRule.dto)
-    });
   }
   return nestedEntries;
 }

package/dist/internal/enum-values.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeEnumValues(values: Record<string, unknown> | readonly unknown[]): readonly unknown[];
+//# sourceMappingURL=enum-values.d.ts.map

package/dist/internal/enum-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-values.d.ts","sourceRoot":"","sources":["../../src/internal/enum-values.ts"],"names":[],"mappings":"AAAA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAuB5G"}

package/dist/internal/enum-values.js

@@ -0,0 +1,16 @@
+export function normalizeEnumValues(values) {
+  if (Array.isArray(values)) {
+    return values;
+  }
+  const entries = Object.entries(values);
+  const ownMembers = new Map(entries);
+  const normalized = new Set();
+  for (const [key, value] of entries) {
+    const numericValue = Number(key);
+    const hasForwardMember = typeof value === 'string' && ownMembers.has(value);
+    const forwardValue = typeof value === 'string' ? ownMembers.get(value) : undefined;
+    const isReverseEntry = typeof value === 'string' && key === String(numericValue) && (typeof forwardValue === 'number' && key === String(forwardValue) || value === '__proto__' && !hasForwardMember && Number.isFinite(numericValue));
+    normalized.add(isReverseEntry ? numericValue : value);
+  }
+  return [...normalized];
+}

package/dist/internal/object-utils.d.ts

@@ -1,4 +1,30 @@
+/**
+ * Returns collection members for supported nested collection values.
+ *
+ * @param value Candidate collection value.
+ * @returns Collection members, or `undefined` for unsupported values.
+ */
 export declare function getIterableValues(value: unknown): unknown[] | undefined;
+/**
+ * Identifies plain records accepted at DTO boundaries.
+ *
+ * @param value Candidate record value.
+ * @returns Whether the value has an object or null prototype.
+ */
 export declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * Identifies an enumerable own property that is safe to copy onto a DTO.
+ *
+ * @param source Source object.
+ * @param key Candidate property key.
+ * @returns Whether the property is own, enumerable, and not prototype-sensitive.
+ */
+export declare function isSafeOwnEnumerableProperty(source: object, key: PropertyKey): boolean;
+/**
+ * Copies safe enumerable own properties between records.
+ *
+ * @param target Destination record.
+ * @param source Source record.
+ */
 export declare function assignSafeOwnEnumerableProperties(target: Record<PropertyKey, unknown>, source: Record<PropertyKey, unknown>): void;
 //# sourceMappingURL=object-utils.d.ts.map

package/dist/internal/object-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object-utils.d.ts","sourceRoot":"","sources":["../../src/internal/object-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,GAAG,SAAS,CAKvE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAOnF;AAID,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,EACpC,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,GACnC,IAAI,CAYN"}
+{"version":3,"file":"object-utils.d.ts","sourceRoot":"","sources":["../../src/internal/object-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,GAAG,SAAS,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAOnF;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAGrF;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,EACpC,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,GACnC,IAAI,CAQN"}

package/dist/internal/object-utils.js

@@ -1,9 +1,22 @@
+/**
+ * Returns collection members for supported nested collection values.
+ *
+ * @param value Candidate collection value.
+ * @returns Collection members, or `undefined` for unsupported values.
+ */
 export function getIterableValues(value) {
   if (Array.isArray(value)) return value;
   if (value instanceof Set) return Array.from(value.values());
   if (value instanceof Map) return Array.from(value.values());
   return undefined;
 }
+
+/**
+ * Identifies plain records accepted at DTO boundaries.
+ *
+ * @param value Candidate record value.
+ * @returns Whether the value has an object or null prototype.
+ */
 export function isPlainObject(value) {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return false;
@@ -12,12 +25,27 @@ export function isPlainObject(value) {
   return prototype === Object.prototype || prototype === null;
 }
 const dangerousKeys = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Identifies an enumerable own property that is safe to copy onto a DTO.
+ *
+ * @param source Source object.
+ * @param key Candidate property key.
+ * @returns Whether the property is own, enumerable, and not prototype-sensitive.
+ */
+export function isSafeOwnEnumerableProperty(source, key) {
+  return !(typeof key === 'string' && dangerousKeys.has(key)) && Object.prototype.propertyIsEnumerable.call(source, key);
+}
+
+/**
+ * Copies safe enumerable own properties between records.
+ *
+ * @param target Destination record.
+ * @param source Source record.
+ */
 export function assignSafeOwnEnumerableProperties(target, source) {
   for (const key of Reflect.ownKeys(source)) {
-    if (typeof key === 'string' && dangerousKeys.has(key)) {
-      continue;
-    }
-    if (!Object.prototype.propertyIsEnumerable.call(source, key)) {
+    if (!isSafeOwnEnumerableProperty(source, key)) {
       continue;
     }
     target[key] = source[key];

package/dist/internal/validation-issues.d.ts

@@ -0,0 +1,13 @@
+import type { ValidationRuleResult } from '@fluojs/core/request-pipeline';
+import type { ValidationIssue } from '../types.js';
+export declare function normalizeResult(result: ValidationRuleResult, field: string | undefined, source: ValidationIssue['source'], fallback: {
+    readonly code: string;
+    readonly message: string;
+}): ValidationIssue[];
+export declare function joinFieldPath(parent: string, child?: string): string;
+export declare function prefixIssues(issues: readonly ValidationIssue[], fieldPrefix: string, source: ValidationIssue['source']): ValidationIssue[];
+export declare function buildIssue(fallback: {
+    readonly code: string;
+    readonly message: string;
+}, field: string, source: ValidationIssue['source']): ValidationIssue;
+//# sourceMappingURL=validation-issues.d.ts.map

package/dist/internal/validation-issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-issues.d.ts","sourceRoot":"","sources":["../../src/internal/validation-issues.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA2B,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAEnG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAenD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,EACjC,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5D,eAAe,EAAE,CAcnB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAChC,eAAe,EAAE,CAEnB;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC7D,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAChC,eAAe,CAOjB"}

package/dist/internal/validation-issues.js

@@ -0,0 +1,44 @@
+function normalizeIssue(issue, field, source) {
+  return {
+    code: issue.code,
+    field: issue.field ?? field,
+    message: issue.message,
+    source: issue.source ?? source
+  };
+}
+export function normalizeResult(result, field, source, fallback) {
+  if (result === undefined || result === true) {
+    return [];
+  }
+  if (result === false) {
+    return [{
+      code: fallback.code,
+      field,
+      message: fallback.message,
+      source
+    }];
+  }
+  if (Array.isArray(result)) {
+    return result.map(issue => normalizeIssue(issue, field, source));
+  }
+  return [normalizeIssue(result, field, source)];
+}
+export function joinFieldPath(parent, child) {
+  if (!child) return parent;
+  return child.startsWith('[') ? `${parent}${child}` : `${parent}.${child}`;
+}
+export function prefixIssues(issues, fieldPrefix, source) {
+  return issues.map(issue => ({
+    ...issue,
+    field: joinFieldPath(fieldPrefix, issue.field),
+    source: issue.source ?? source
+  }));
+}
+export function buildIssue(fallback, field, source) {
+  return {
+    code: fallback.code,
+    field,
+    message: fallback.message,
+    source
+  };
+}

package/dist/types.d.ts

@@ -12,6 +12,11 @@ export interface ValidationIssue {
     /** Optional metadata source that produced this rule. */
     source?: MetadataSource;
 }
+/** Controls DTO materialization behavior. */
+export interface MaterializeOptions {
+    /** Policy for safe own enumerable input properties not declared by the DTO. */
+    readonly undeclaredProperties?: 'preserve' | 'reject';
+}
 /**
  * Validation engine contract used by HTTP binding and app-level validation flows.
  */
@@ -22,7 +27,13 @@ export interface Validator {
      * without replacing the caller's properties.
      */
     validate(value: unknown, target: Constructor): MaybePromise<void>;
-    /** Materializes and validates a value into a typed DTO instance. */
-    materialize<T>(value: unknown, target: Constructor<T>): MaybePromise<T>;
+    /**
+     * Materializes and validates a value into a typed DTO instance.
+     *
+     * @param value Root value to materialize.
+     * @param target Requested DTO constructor.
+     * @param options Optional materialization policy.
+     */
+    materialize<T>(value: unknown, target: Constructor<T>, options?: MaterializeOptions): MaybePromise<T>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClE,oEAAoE;IACpE,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;CACzE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;CACvG"}

package/dist/validation.d.ts

@@ -1,10 +1,10 @@
 import type { Constructor } from '@fluojs/core';
-import type { Validator } from './types.js';
+import type { MaterializeOptions, Validator } from './types.js';
 /**
  * Represents the default validator.
  */
 export declare class DefaultValidator implements Validator {
     validate(value: unknown, target: Constructor): Promise<void>;
-    materialize<T>(value: unknown, target: Constructor<T>): Promise<T>;
+    materialize<T>(value: unknown, target: Constructor<T>, options?: MaterializeOptions): Promise<T>;
 }
 //# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEZ,MAAM,cAAc,CAAC;AAOtB,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,YAAY,CAAC;AAga7D;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAYzE"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEZ,MAAM,cAAc,CAAC;AAetB,OAAO,KAAK,EAAE,kBAAkB,EAAmB,SAAS,EAAE,MAAM,YAAY,CAAC;AA+OjF;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,CAAC,CAAC;CAqB3G"}

package/dist/validation.js

@@ -1,120 +1,12 @@
 import { DtoValidationError } from './errors.js';
+import { assertValidRootValue, createNestedDtoInstance, enterTraversal, exitTraversal } from './internal/dto-materialization.js';
 import { getCachedDtoMetadata, resolveNestedDto } from './internal/dto-metadata-cache.js';
-import { assignSafeOwnEnumerableProperties, getIterableValues, isPlainObject } from './internal/object-utils.js';
+import { getIterableValues, isPlainObject } from './internal/object-utils.js';
 import { getRuleHandler } from './internal/rule-handlers.js';
+import { buildIssue, joinFieldPath, normalizeResult, prefixIssues } from './internal/validation-issues.js';
 function toFieldName(propertyKey) {
   return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
 }
-function normalizeIssue(issue, field, source) {
-  return {
-    code: issue.code,
-    field: issue.field ?? field,
-    message: issue.message,
-    source: issue.source ?? source
-  };
-}
-function normalizeResult(result, field, source, fallback) {
-  if (result === undefined || result === true) {
-    return [];
-  }
-  if (result === false) {
-    return [{
-      code: fallback.code,
-      field,
-      message: fallback.message,
-      source
-    }];
-  }
-  if (Array.isArray(result)) {
-    return result.map(issue => normalizeIssue(issue, field, source));
-  }
-  return [normalizeIssue(result, field, source)];
-}
-function joinFieldPath(parent, child) {
-  if (!child) return parent;
-  return child.startsWith('[') ? `${parent}${child}` : `${parent}.${child}`;
-}
-function prefixIssues(issues, fieldPrefix, source) {
-  return issues.map(issue => ({
-    ...issue,
-    field: joinFieldPath(fieldPrefix, issue.field),
-    source: issue.source ?? source
-  }));
-}
-function enterTraversal(value, context) {
-  if (!context || typeof value !== 'object' || value === null) {
-    return true;
-  }
-  if (context.active.has(value)) {
-    return false;
-  }
-  context.active.add(value);
-  return true;
-}
-function exitTraversal(value, context) {
-  if (!context || typeof value !== 'object' || value === null) {
-    return;
-  }
-  context.active.delete(value);
-}
-function createNestedDtoInstance(target, rawValue, context) {
-  if (rawValue instanceof target) {
-    return rawValue;
-  }
-  if (!isPlainObject(rawValue)) {
-    return rawValue;
-  }
-  const instance = new target();
-  if (!enterTraversal(rawValue, context)) {
-    return rawValue;
-  }
-  try {
-    assignSafeOwnEnumerableProperties(instance, rawValue);
-    const metadata = getCachedDtoMetadata(target);
-    applyBindingValues(instance, rawValue, metadata.mergedPropertyKeys, metadata.bindingMap);
-    for (const nestedEntry of metadata.nestedDtoTransforms) {
-      const currentValue = instance[nestedEntry.propertyKey];
-      if (currentValue === undefined || currentValue === null) {
-        continue;
-      }
-      instance[nestedEntry.propertyKey] = transformNestedCollectionValue(currentValue, nestedEntry.target, context);
-    }
-    return instance;
-  } finally {
-    exitTraversal(rawValue, context);
-  }
-}
-function materializeNestedDtoValue(target, rawValue, context) {
-  if (rawValue instanceof target) {
-    return rawValue;
-  }
-  if (!isPlainObject(rawValue)) {
-    return rawValue;
-  }
-  return createNestedDtoInstance(target, rawValue, context);
-}
-function applyBindingValues(instance, rawValue, keys, bindingMap) {
-  for (const propertyKey of keys) {
-    const sourceKey = bindingMap.get(propertyKey)?.key;
-    if (!sourceKey) continue;
-    instance[propertyKey] = rawValue[sourceKey];
-  }
-}
-function transformNestedValue(value, target, context) {
-  return value === undefined || value === null ? value : materializeNestedDtoValue(target, value, context);
-}
-function transformNestedCollectionValue(value, target, context) {
-  if (Array.isArray(value)) {
-    return value.map(item => transformNestedValue(item, target, context));
-  }
-  if (value instanceof Set) {
-    return new Set(Array.from(value.values(), item => transformNestedValue(item, target, context)));
-  }
-  if (value instanceof Map) {
-    return new Map(Array.from(value.entries(), ([key, item]) => [key, transformNestedValue(item, target, context)]));
-  }
-  return transformNestedValue(value, target, context);
-}
 function describeValidator(rule, field) {
   const handler = getRuleHandler(rule);
   return {
@@ -122,31 +14,11 @@ function describeValidator(rule, field) {
     message: rule.message ?? handler.describe(field, rule)
   };
 }
-function buildIssue(fallback, field, source) {
-  return {
-    code: fallback.code,
-    field,
-    message: fallback.message,
-    source
-  };
-}
-function buildInvalidRootIssue() {
-  return {
-    code: 'INVALID_DTO',
-    message: 'DTO root value must be a plain object.'
-  };
-}
-function assertValidRootValue(value, target) {
-  if (value instanceof target || isPlainObject(value)) {
-    return;
-  }
-  throw new DtoValidationError('Validation failed.', [buildInvalidRootIssue()]);
-}
 function getRuleValues(value) {
   return getIterableValues(value) ?? [value];
 }
 function shouldSkipRuleForMissingValue(rule, value) {
-  return (value === undefined || value === null) && rule.kind !== 'defined' && rule.kind !== 'notEmpty' && rule.kind !== 'empty';
+  return (value === undefined || value === null) && rule.kind !== 'defined' && rule.kind !== 'empty';
 }
 async function evaluateCustomRule(rule, value, dto, propertyKey, fieldPath, source, fallback) {
   if (!rule.each) {
@@ -192,7 +64,7 @@ async function validateNestedRule(rule, value, fieldPath, inheritedSource, conte
       issues.push(buildIssue(describeValidator(rule, nestedPath), nestedPath, inheritedSource));
       continue;
     }
-    const nestedDto = createNestedDtoInstance(resolvedDto, entry, context);
+    const nestedDto = createNestedDtoInstance(resolvedDto, entry, context, nestedPath);
     const shouldTrackEntry = trackedEntry && !(entry instanceof resolvedDto) ? enterTraversal(trackedEntry, context) : false;
     try {
       issues.push(...(await collectValidationIssuesInternal(resolvedDto, nestedDto, {
@@ -230,10 +102,10 @@ async function evaluateRule(rule, value, dto, propertyKey, fieldPath, source, co
   return [];
 }
 async function applyPropertyRules(rules, value, dto, propertyKey, fieldPath, source, context) {
-  const conditionallySkip = await shouldConditionallySkip(rules, dto, value);
   if (rules.some(rule => rule.kind === 'optional') && (value === undefined || value === null)) {
     return [];
   }
+  const conditionallySkip = await shouldConditionallySkip(rules, dto, value);
   const issues = [];
   for (const rule of rules) {
     if (rule.kind === 'validateIf' || rule.kind === 'optional') continue;
@@ -295,12 +167,19 @@ export class DefaultValidator {
     if (issues.length === 0) return;
     throw new DtoValidationError('Validation failed.', issues);
   }
-  async materialize(value, target) {
+  async materialize(value, target, options = {}) {
     assertValidRootValue(value, target);
-    const instance = createNestedDtoInstance(target, value, {
-      active: new WeakSet()
-    });
-    const issues = await collectValidationIssues(target, instance);
+    const traversal = {
+      active: new WeakSet(),
+      hydrateExistingInstances: true,
+      undeclaredProperties: options.undeclaredProperties ?? 'preserve',
+      materialized: new WeakMap(),
+      ...(options.undeclaredProperties === 'reject' ? {
+        declaredNestedKeys: new WeakMap()
+      } : {})
+    };
+    const instance = createNestedDtoInstance(target, value, traversal);
+    const issues = await collectValidationIssuesInternal(target, instance, {}, traversal);
     if (issues.length > 0) {
       throw new DtoValidationError('Validation failed.', issues);
     }

package/package.json

@@ -9,7 +9,7 @@
     "decorators",
     "schema"
   ],
-  "version": "1.0.6",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/validation"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -42,13 +42,13 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "validator": "^13.15.26",
-    "@fluojs/core": "^1.1.0"
+    "@fluojs/core": "^2.0.0"
   },
   "devDependencies": {
     "@types/validator": "^13.15.10",
     "arktype": "^2.2.0",
     "valibot": "^1.0.0",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.11",
     "zod": "^4.1.11"
   },
   "scripts": {