@fluojs/validation 1.0.0-beta.3 → 1.0.0

package/README.ko.md

@@ -26,6 +26,7 @@ pnpm add @fluojs/validation
 - 컨트롤러나 서비스에서 ad hoc parsing 대신 class 기반 검증 규칙을 쓰고 싶을 때
 - `PickType`, `PartialType`, `IntersectionType` 같은 metadata-preserving mapped DTO helper가 필요할 때
 - `@ValidateClass(...)`로 Zod나 Valibot 같은 Standard Schema validator를 붙이고 싶을 때
+- `@fluojs/i18n/validation`으로 명시적으로 localize할 수 있는 안정적인 validation issue code와 path가 필요할 때
 
 ## 빠른 시작
 
@@ -64,10 +65,17 @@ try {
 - **`materialize<T>(value, target)`**: **입력 처리**에 가장 적합합니다. plain 객체를 받아 대상 클래스의 인스턴스를 생성하고, 값을 복사하며, 중첩된 DTO를 재귀적으로 처리한 후 모든 검증 규칙을 실행합니다.
 - **`validate(instance, target)`**: **기존 루트 객체 확인**에 적합합니다. 이미 생성된 루트 값에 대해 검증 규칙을 실행하며, plain 객체인 `@ValidateNested(...)` 값은 중첩 DTO 규칙을 실행하기 위해 임시로 실체화할 수 있습니다. 이 임시 실체화는 호출자가 넘긴 속성 값을 대체하지 않습니다.
 
+`validate()`는 문자열, 배열, `null`, `undefined` 같은 잘못된 루트 값을 field 또는
+class rule이 실행되기 전에 deterministic `DtoValidationError`로 거부합니다. 이미
+생성된 대상 DTO 인스턴스와 plain 루트 객체는 허용하므로 request-pipeline binder가
+준비한 DTO payload를 scalar coercion 없이 검증할 수 있습니다.
+
 `materialize()`는 plain 입력 객체의 안전한 own enumerable 속성을 복사하고,
 DTO 바인딩 메타데이터를 적용한 뒤 `@ValidateNested(...)` 필드를 재귀적으로
 실체화합니다. 어떤 요청 소스를 선택하고 스칼라 값을 변환할지는 transport 또는
 binder가 검증 전에 담당한다는 request-pipeline 계약을 유지합니다.
+선언된 중첩 DTO의 인스턴스인 기존 중첩 값은 그대로 보존하고, plain 중첩 값만
+해당 필드 또는 collection entry 단위로 실체화합니다.
 `materialize()`에 넘기는 루트 값은 plain 객체이거나 대상 DTO 인스턴스여야 합니다.
 문자열, 배열, `null` 같은 잘못된 루트 값은 대상 DTO 생성자나 필드 initializer가
 실행되기 전에 거부됩니다.
@@ -89,6 +97,8 @@ type ValidationIssue = {
 사용합니다. HTTP 바인딩에서 온 규칙은 `source`를 붙이며, standalone validation이나
 Standard Schema 이슈에서는 값이 없을 수 있습니다.
 
+`@fluojs/validation`은 항상 기존 human-readable `message` 값을 방출합니다. Localized message가 필요한 애플리케이션은 validation 실패 후 `@fluojs/i18n/validation`에 opt-in할 수 있습니다. 이 통합은 validator 실행을 바꾸거나 이 패키지를 HTTP locale resolution에 결합하지 않고 `source`, `field`, `code`를 translation key로 매핑합니다.
+
 ### Mapped DTO 헬퍼
 
 ```ts
@@ -124,10 +134,12 @@ class RestrictedUserDto {
 ### 중첩 검증
 
 `@ValidateNested(...)`는 객체 필드, 배열, `Set`, `Map`을 지원합니다. 중첩 DTO path는 validation issue에서 dot/index 표기법을 사용하며, cycle은 안전하게 감지되고 shared reference는 허용됩니다.
+중첩 타입을 지연 해석해야 할 때는 DTO 클래스 자체나 `() => ChildDto`, `function resolveChildDto() { return ChildDto; }` 같은 lazy constructor factory를 전달할 수 있습니다.
 
 ### 암묵적 scalar coercion 없음
 
 `materialize()`는 의도적으로 엄격합니다. Transport가 `'42'`를 넘기고 DTO가 `number`를 기대한다면, transport나 binding layer가 먼저 변환해야 합니다.
+`@IsLatitude()`, `@IsLongitude()`를 포함한 numeric validator는 numeric string을 이미 변환된 number처럼 취급하지 않고 DTO의 numeric 값을 검증합니다.
 
 ## 공개 API
 
@@ -145,6 +157,7 @@ class RestrictedUserDto {
 ## 관련 패키지
 
 - `@fluojs/http`: request data를 bind한 뒤 이 패키지로 검증합니다.
+- `@fluojs/i18n`: opt-in localized validation issue message를 위한 `@fluojs/i18n/validation`을 제공합니다.
 - `@fluojs/serialization`: response side에서 output DTO를 가공합니다.
 - `@fluojs/core`: validation decorator가 사용하는 metadata primitive를 제공합니다.
 

package/README.md

@@ -26,6 +26,7 @@ pnpm add @fluojs/validation
 - when you want class-based validation rules instead of ad hoc parsing in controllers and services
 - when you need metadata-preserving mapped DTO helpers such as `PickType`, `PartialType`, and `IntersectionType`
 - when you want to attach Standard Schema validators such as Zod or Valibot through `@ValidateClass(...)`
+- when you want stable validation issue codes and paths that can be localized explicitly through `@fluojs/i18n/validation`
 
 ## Quick Start
 
@@ -66,10 +67,19 @@ try {
   temporarily materialize plain nested `@ValidateNested(...)` values to run their
   nested DTO rules without replacing the caller's properties
 
+`validate()` rejects malformed roots such as strings, arrays, `null`, and
+`undefined` with a deterministic `DtoValidationError` before field or class rules
+run. It accepts already-created target DTO instances and plain root objects so
+request-pipeline binders can validate their prepared DTO payloads without scalar
+coercion.
+
 `materialize()` copies safe own enumerable properties from plain input objects,
 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.
+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.
 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.
@@ -91,6 +101,8 @@ Nested DTOs use dot paths and collection indexes, such as `address.city` or
 `items[0].name`. HTTP bindings attach `source` when the rule came from request
 metadata; standalone validation and Standard Schema issues may leave it unset.
 
+`@fluojs/validation` always emits its normal human-readable `message` values. Applications that need localized messages can opt into `@fluojs/i18n/validation` after validation fails. That integration maps `source`, `field`, and `code` to translation keys without changing validator execution or coupling this package to HTTP locale resolution.
+
 ### Mapped DTO helpers
 
 ```ts
@@ -126,10 +138,12 @@ class RestrictedUserDto {
 ### 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.
+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
 
 `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.
 
 ## Public API
 
@@ -147,6 +161,7 @@ class RestrictedUserDto {
 ## Related Packages
 
 - `@fluojs/http`: binds request data, then uses this package to validate it
+- `@fluojs/i18n`: exposes `@fluojs/i18n/validation` for opt-in localized validation issue messages
 - `@fluojs/serialization`: shapes output DTOs on the response side
 - `@fluojs/core`: provides the metadata primitives used by validation decorators
 

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EAEZ,MAAM,cAAc,CAAC;AAatB,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,YAAY,CAAC;AAgxB7D;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAczE"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EAEZ,MAAM,cAAc,CAAC;AAatB,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,YAAY,CAAC;AAsyB7D;;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"}

package/dist/validation.js

@@ -1,8 +1,11 @@
 import validator from 'validator';
 import { getClassValidationRules, getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/internal';
 import { DtoValidationError } from './errors.js';
+function isClassConstructor(dto) {
+  return typeof dto === 'function' && Function.prototype.toString.call(dto).startsWith('class ');
+}
 function resolveNestedDto(dto) {
-  if (typeof dto === 'function' && 'prototype' in dto && dto.prototype) {
+  if (isClassConstructor(dto)) {
     return dto;
   }
   return dto();
@@ -283,7 +286,7 @@ const RULE_HANDLERS = {
   validatorjs: {
     defaultCode: 'INVALID_FIELD',
     describe: field => `${field} is invalid.`,
-    validate: (rule, value) => typeof value === 'string' && runValidatorJs(rule, value)
+    validate: (rule, value) => runValidatorJs(rule, value)
   },
   arrayContains: {
     defaultCode: 'ARRAY_CONTAINS',
@@ -399,6 +402,15 @@ function describeValidator(rule, field) {
   };
 }
 function runValidatorJs(rule, value) {
+  if (rule.validator === 'latitude') {
+    return typeof value === 'number' && Number.isFinite(value) && value >= -90 && value <= 90;
+  }
+  if (rule.validator === 'longitude') {
+    return typeof value === 'number' && Number.isFinite(value) && value >= -180 && value <= 180;
+  }
+  if (typeof value !== 'string') {
+    return false;
+  }
   switch (rule.validator) {
     case 'alpha':
       return validator.isAlpha(value);
@@ -470,16 +482,6 @@ function runValidatorJs(rule, value) {
       return validator.isUUID(value, rule.args?.[0]);
     case 'iso8601':
       return validator.isISO8601(value);
-    case 'latitude':
-      {
-        const number = Number(value);
-        return !Number.isNaN(number) && number >= -90 && number <= 90;
-      }
-    case 'longitude':
-      {
-        const number = Number(value);
-        return !Number.isNaN(number) && number >= -180 && number <= 180;
-      }
     case 'latLong':
       return validator.isLatLong(value);
     default:
@@ -500,6 +502,12 @@ function buildInvalidRootIssue() {
     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];
 }
@@ -646,14 +654,13 @@ async function collectValidationIssuesInternal(target, value, context, traversal
  */
 export class DefaultValidator {
   async validate(value, target) {
+    assertValidRootValue(value, target);
     const issues = await collectValidationIssues(target, value);
     if (issues.length === 0) return;
     throw new DtoValidationError('Validation failed.', issues);
   }
   async materialize(value, target) {
-    if (!(value instanceof target) && !isPlainObject(value)) {
-      throw new DtoValidationError('Validation failed.', [buildInvalidRootIssue()]);
-    }
+    assertValidRootValue(value, target);
     const instance = createNestedDtoInstance(target, value, {
       active: new WeakSet()
     });

package/package.json

@@ -9,7 +9,7 @@
     "decorators",
     "schema"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -42,7 +42,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "validator": "^13.15.26",
-    "@fluojs/core": "^1.0.0-beta.4"
+    "@fluojs/core": "^1.0.0"
   },
   "devDependencies": {
     "@types/validator": "^13.15.10",