@fluojs/validation 1.0.5 → 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,12 +76,39 @@ class rule이 실행되기 전에 deterministic `DtoValidationError`로 거부
 DTO 바인딩 메타데이터를 적용한 뒤 `@ValidateNested(...)` 필드를 재귀적으로
 실체화합니다. 어떤 요청 소스를 선택하고 스칼라 값을 변환할지는 transport 또는
 binder가 검증 전에 담당한다는 request-pipeline 계약을 유지합니다.
+Plain 입력 객체를 materialize할 때 안전한 추가 own enumerable 속성은 기본적으로 유지됩니다. `__proto__`, `constructor`,
+`prototype` 같은 위험한 key와 inherited 또는 non-enumerable 속성만 제외합니다.
+세 번째 `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 인스턴스여야 합니다.
 문자열, 배열, `null` 같은 잘못된 루트 값은 대상 DTO 생성자나 필드 initializer가
 실행되기 전에 거부됩니다.
 
+### 누락 값과 validation group
+
+일반 field validator는 `null`과 `undefined`를 모두 건너뜁니다. 두 값 중 하나라도
+누락된 필수 field로 실패해야 한다면 `@IsDefined()`를 추가하세요. Optional 계약을
+명시하고 해당 field의 다른 validator를 short-circuit하려면 `@IsOptional()`을
+사용할 수 있습니다.
+
+Validation group은 지원되는 실행 surface가 아닙니다. Decorator option에는
+class-validator 스타일의 `groups` 또는 `always`가 없고, `validate()`와
+`materialize()`도 group 선택을 받지 않습니다. Group 기반 실행을 가정하지 말고
+별도 DTO, mapped DTO helper, `@ValidateIf(...)`, 명시적 class-level validation으로
+workflow 차이를 모델링하세요.
+
+### DTO 상속
+
+Derived DTO는 base DTO의 field-level 및 class-level validation rule을 상속합니다.
+Derived DTO에 validation decorator를 추가하면 derived DTO가 소유하는 metadata가
+생성되며 base DTO의 검증 동작은 바뀌지 않습니다. Mapped DTO helper가 반환한 class를
+확장할 때도 같은 격리가 유지됩니다.
+
 ### 검증 이슈 형태
 
 `DtoValidationError.issues`는 request-pipeline 오류 상세에 사용하는 안정적인 DTO입니다.
@@ -118,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가 없는 검증 결과는 성공으로 처리합니다.
@@ -136,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 버전으로
@@ -146,6 +188,7 @@ IPv6 모두 허용" 계약을 명시하고 싶을 때 사용할 수 있습니다
 ### 중첩 검증
 
 `@ValidateNested(...)`는 객체 필드, 배열, `Set`, `Map`을 지원합니다. 중첩 DTO path는 validation issue에서 dot/index 표기법을 사용하며, cycle은 안전하게 감지되고 shared reference는 허용됩니다.
+Array, `Set`, `Map` member는 자동으로 검증되고 실체화되므로 nested collection 순회를 활성화하기 위해 `each: true`를 지정할 필요가 없습니다. 기존 DTO를 위해 이 option은 계속 허용됩니다.
 중첩 타입을 지연 해석해야 할 때는 DTO 클래스 자체나 `() => ChildDto`, `function resolveChildDto() { return ChildDto; }` 같은 lazy constructor factory를 전달할 수 있습니다.
 
 ### 암묵적 scalar coercion 없음
@@ -153,9 +196,12 @@ IPv6 모두 허용" 계약을 명시하고 싶을 때 사용할 수 있습니다
 `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,6 +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 by default; only dangerous keys such as
+`__proto__`, `constructor`, and `prototype`, plus inherited or non-enumerable
+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.
@@ -84,6 +94,26 @@ The root value passed to `materialize()` must already be a plain object or an
 instance of the target DTO; malformed roots such as strings, arrays, and `null`
 are rejected before the target DTO constructor or field initializers run.
 
+### Missing values and validation groups
+
+Ordinary field validators skip both `null` and `undefined`. Add `@IsDefined()`
+when either value must fail as a missing required field. `@IsOptional()` remains
+useful when the optional contract should be explicit and should short-circuit the
+other validators on that field.
+
+Validation groups are not a supported execution surface. Decorator options do
+not include class-validator-style `groups` or `always`, and `validate()` /
+`materialize()` do not accept a group selection. Model different workflows with
+separate DTOs, mapped DTO helpers, `@ValidateIf(...)`, or explicit class-level
+validation instead of assuming group-based execution.
+
+### DTO inheritance
+
+Derived DTOs inherit field-level and class-level validation rules from their base
+DTO. Adding validation decorators to the derived DTO creates derived-owned
+metadata and does not change how the base DTO validates. The same isolation holds
+when extending a class returned by a mapped DTO helper.
+
 ### Validation issue shape
 
 `DtoValidationError.issues` is a stable DTO for request-pipeline error details:
@@ -122,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.
@@ -140,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
@@ -150,6 +193,7 @@ contract explicitly while still using the same runtime behavior as `@IsIP()`.
 ### Nested validation
 
 `@ValidateNested(...)` supports object fields, arrays, `Set`, and `Map`. Nested DTO paths use dot/index notation in validation issues, cycles are detected safely, and shared references are allowed.
+Array, `Set`, and `Map` members are validated and materialized automatically; `each: true` is not required to enable nested collection traversal. The option remains accepted for existing DTOs.
 Pass either a DTO class or a lazy constructor factory such as `() => ChildDto` or `function resolveChildDto() { return ChildDto; }` when nested types need deferred resolution.
 
 ### No implicit scalar coercion
@@ -157,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`