koatty_validation 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.6.1](https://github.com/koatty/koatty_validation/compare/v1.6.0...v1.6.1) (2025-10-23)
+
 ## [1.6.0](https://github.com/koatty/koatty_validation/compare/v1.5.0...v1.6.0) (2025-10-22)
 
 

package/README.md

@@ -36,10 +36,16 @@ export class Controller {
         // 业务逻辑
     }
 
-    // DTO 验证
+    // DTO 验证 - 异步模式（默认，适用于 Koatty 框架）
     @Validated()
     TestDto(user: UserDTO) {
-        // 自动验证 UserDTO
+        // 框架会在异步获取参数后自动验证 UserDTO
+    }
+    
+    // DTO 验证 - 同步模式（适用于参数已准备好的场景）
+    @Validated(false)
+    TestDtoSync(user: UserDTO) {
+        // 方法执行前立即验证 UserDTO
     }
 }
 
@@ -101,11 +107,107 @@ export class UserDTO {
 
 ```typescript
 @Valid(rule, options)   // 参数验证
-@Validated()           // DTO验证
+@Validated()           // DTO验证 (默认异步模式)
+@Validated(true)       // DTO验证 (异步模式)
+@Validated(false)      // DTO验证 (同步模式)
 @Expose()             // 暴露属性
 @IsDefined()          // 已定义（Expose别名）
 ```
 
+## 🎭 Validated 装饰器
+
+`@Validated` 装饰器支持同步和异步两种验证模式，以适应不同的应用场景。
+
+### 异步模式（默认）
+
+适用于 **Koatty 框架**中，控制器方法的参数需要异步获取的场景。
+
+```typescript
+import { Validated, checkValidated } from 'koatty_validation';
+
+class UserController {
+  // 默认异步模式
+  @Validated()
+  async register(user: UserDTO) {
+    // 框架流程：
+    // 1. 框架接收 HTTP 请求
+    // 2. 框架异步解析请求体，构造 UserDTO 实例
+    // 3. 框架检测到 @Validated() 元数据
+    // 4. 框架调用 checkValidated() 验证参数
+    // 5. 验证通过后调用此方法
+    return { success: true };
+  }
+  
+  // 显式指定异步模式
+  @Validated(true)
+  async update(id: number, user: UserDTO) {
+    return { success: true };
+  }
+}
+```
+
+**异步模式特点：**
+- ✅ 装饰器保存验证元数据到 IOC 容器
+- ✅ 由框架在异步获取参数后执行验证
+- ✅ 适用于参数值需要异步获取的场景
+- ✅ 是 Koatty 框架的推荐模式
+
+### 同步模式
+
+适用于**单元测试**或参数值已经准备好的场景。
+
+```typescript
+class UserService {
+  // 同步模式 - 立即验证
+  @Validated(false)
+  async createUser(user: UserDTO) {
+    // 方法执行前已经完成验证
+    return { success: true };
+  }
+  
+  // 适用于多个参数的场景
+  @Validated(false)
+  async updateUser(id: number, user: UserDTO) {
+    // 只验证类类型参数（UserDTO），基础类型（number）不验证
+    return { success: true };
+  }
+}
+```
+
+**同步模式特点：**
+- ✅ 装饰器包装原方法，在调用时立即执行验证
+- ✅ 适用于单元测试场景
+- ✅ 适用于参数已准备好的场景
+- ✅ 验证失败立即抛出错误
+
+### 手动调用 checkValidated
+
+在框架拦截器或中间件中，可以手动调用 `checkValidated` 函数：
+
+```typescript
+import { checkValidated } from 'koatty_validation';
+
+async function validateInMiddleware(args: any[], paramTypes: any[]) {
+  try {
+    const { validatedArgs, validationTargets } = await checkValidated(args, paramTypes);
+    console.log('验证通过');
+    return validationTargets;
+  } catch (error) {
+    console.error('验证失败:', error);
+    throw error;
+  }
+}
+```
+
+### 选择合适的模式
+
+| 场景 | 推荐模式 | 原因 |
+|------|---------|------|
+| Koatty 框架控制器 | 异步 `@Validated()` | 参数需要异步获取 |
+| 单元测试 | 同步 `@Validated(false)` | 参数已准备好，立即验证 |
+| 独立服务/工具 | 同步 `@Validated(false)` | 不依赖框架，立即验证 |
+| 框架拦截器 | 手动 `checkValidated()` | 完全控制验证时机 |
+
 ## 🔧 自定义装饰器
 
 ### 使用装饰器工厂创建自定义验证器
@@ -310,6 +412,7 @@ const validatedData = await ClassValidator.valid(UserSchema, rawData, true);
 - [基础用法示例](./examples/basic-usage.ts)
 - [自定义装饰器示例](./examples/custom-decorators-example.ts)
 - [完整使用示例](./examples/usage-example.ts)
+- [Validated 异步/同步模式示例](./examples/validated-async-sync-example.ts)
 
 ## 🔍 可用验证函数
 

package/dist/README.md

@@ -36,10 +36,16 @@ export class Controller {
         // 业务逻辑
     }
 
-    // DTO 验证
+    // DTO 验证 - 异步模式（默认，适用于 Koatty 框架）
     @Validated()
     TestDto(user: UserDTO) {
-        // 自动验证 UserDTO
+        // 框架会在异步获取参数后自动验证 UserDTO
+    }
+    
+    // DTO 验证 - 同步模式（适用于参数已准备好的场景）
+    @Validated(false)
+    TestDtoSync(user: UserDTO) {
+        // 方法执行前立即验证 UserDTO
     }
 }
 
@@ -101,11 +107,107 @@ export class UserDTO {
 
 ```typescript
 @Valid(rule, options)   // 参数验证
-@Validated()           // DTO验证
+@Validated()           // DTO验证 (默认异步模式)
+@Validated(true)       // DTO验证 (异步模式)
+@Validated(false)      // DTO验证 (同步模式)
 @Expose()             // 暴露属性
 @IsDefined()          // 已定义（Expose别名）
 ```
 
+## 🎭 Validated 装饰器
+
+`@Validated` 装饰器支持同步和异步两种验证模式，以适应不同的应用场景。
+
+### 异步模式（默认）
+
+适用于 **Koatty 框架**中，控制器方法的参数需要异步获取的场景。
+
+```typescript
+import { Validated, checkValidated } from 'koatty_validation';
+
+class UserController {
+  // 默认异步模式
+  @Validated()
+  async register(user: UserDTO) {
+    // 框架流程：
+    // 1. 框架接收 HTTP 请求
+    // 2. 框架异步解析请求体，构造 UserDTO 实例
+    // 3. 框架检测到 @Validated() 元数据
+    // 4. 框架调用 checkValidated() 验证参数
+    // 5. 验证通过后调用此方法
+    return { success: true };
+  }
+  
+  // 显式指定异步模式
+  @Validated(true)
+  async update(id: number, user: UserDTO) {
+    return { success: true };
+  }
+}
+```
+
+**异步模式特点：**
+- ✅ 装饰器保存验证元数据到 IOC 容器
+- ✅ 由框架在异步获取参数后执行验证
+- ✅ 适用于参数值需要异步获取的场景
+- ✅ 是 Koatty 框架的推荐模式
+
+### 同步模式
+
+适用于**单元测试**或参数值已经准备好的场景。
+
+```typescript
+class UserService {
+  // 同步模式 - 立即验证
+  @Validated(false)
+  async createUser(user: UserDTO) {
+    // 方法执行前已经完成验证
+    return { success: true };
+  }
+  
+  // 适用于多个参数的场景
+  @Validated(false)
+  async updateUser(id: number, user: UserDTO) {
+    // 只验证类类型参数（UserDTO），基础类型（number）不验证
+    return { success: true };
+  }
+}
+```
+
+**同步模式特点：**
+- ✅ 装饰器包装原方法，在调用时立即执行验证
+- ✅ 适用于单元测试场景
+- ✅ 适用于参数已准备好的场景
+- ✅ 验证失败立即抛出错误
+
+### 手动调用 checkValidated
+
+在框架拦截器或中间件中，可以手动调用 `checkValidated` 函数：
+
+```typescript
+import { checkValidated } from 'koatty_validation';
+
+async function validateInMiddleware(args: any[], paramTypes: any[]) {
+  try {
+    const { validatedArgs, validationTargets } = await checkValidated(args, paramTypes);
+    console.log('验证通过');
+    return validationTargets;
+  } catch (error) {
+    console.error('验证失败:', error);
+    throw error;
+  }
+}
+```
+
+### 选择合适的模式
+
+| 场景 | 推荐模式 | 原因 |
+|------|---------|------|
+| Koatty 框架控制器 | 异步 `@Validated()` | 参数需要异步获取 |
+| 单元测试 | 同步 `@Validated(false)` | 参数已准备好，立即验证 |
+| 独立服务/工具 | 同步 `@Validated(false)` | 不依赖框架，立即验证 |
+| 框架拦截器 | 手动 `checkValidated()` | 完全控制验证时机 |
+
 ## 🔧 自定义装饰器
 
 ### 使用装饰器工厂创建自定义验证器
@@ -310,6 +412,7 @@ const validatedData = await ClassValidator.valid(UserSchema, rawData, true);
 - [基础用法示例](./examples/basic-usage.ts)
 - [自定义装饰器示例](./examples/custom-decorators-example.ts)
 - [完整使用示例](./examples/usage-example.ts)
+- [Validated 异步/同步模式示例](./examples/validated-async-sync-example.ts)
 
 ## 🔍 可用验证函数
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-10-23 01:25:11
+* @Date: 2025-10-23 20:54:44
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
@@ -14,7 +14,7 @@ import { ValidationOptions } from 'class-validator';
 export declare function cached(validator: string, ttl?: number): (target: any, propertyName: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 
 /**
- * 缓存配置选项
+ * Cache configuration options
  */
 export declare interface CacheOptions {
     max?: number;
@@ -32,6 +32,17 @@ export declare interface CacheOptions {
  */
 export declare function checkParamsType(value: any, type: string): any;
 
+/**
+ * Synchronous validation function - Executes the actual validation logic
+ * @param args Method parameters
+ * @param paramTypes Parameter type metadata
+ * @returns Validated parameters and validation targets
+ */
+export declare function checkValidated(args: any[], paramTypes: any[]): Promise<{
+    validatedArgs: any[];
+    validationTargets: any[];
+}>;
+
 /**
  * ClassValidator for manual
  */
@@ -71,37 +82,37 @@ export declare function convertDtoParamsType(clazz: any, cls: any): any;
 export declare function convertParamsType(param: any, type: string): any;
 
 /**
- * 创建带参数的验证装饰器
- * @param name 装饰器名称
- * @param validator 验证函数
- * @param defaultMessage 默认错误信息
- * @returns 装饰器工厂函数
+ * Create parameterized validation decorator
+ * @param name Decorator name
+ * @param validator Validation function
+ * @param defaultMessage Default error message
+ * @returns Decorator factory function
  */
 export declare function createParameterizedDecorator(name: string, validator: ValidatorFunction, defaultMessage?: string): (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 创建简单验证装饰器（不需要额外参数）
- * @param name 装饰器名称
- * @param validator 验证函数
- * @param defaultMessage 默认错误信息
- * @returns 装饰器函数
+ * Create simple validation decorator (no additional parameters required)
+ * @param name Decorator name
+ * @param validator Validation function
+ * @param defaultMessage Default error message
+ * @returns Decorator function
  */
 export declare function createSimpleDecorator(name: string, validator: ValidatorFunction, defaultMessage?: string): (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 创建验证装饰器的工厂函数
- * @param options 装饰器配置选项
- * @returns 装饰器工厂函数
+ * Factory function to create validation decorators
+ * @param options Decorator configuration options
+ * @returns Decorator factory function
  */
 export declare function createValidationDecorator(options: DecoratorOptions): (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 创建验证错误
+ * Create validation error
  */
 export declare function createValidationError(field: string, value: any, constraint: string, customMessage?: string, context?: Record<string, any>): ValidationErrorDetail;
 
 /**
- * 批量创建验证错误
+ * Create validation errors in batch
  */
 export declare function createValidationErrors(errors: Array<{
     field: string;
@@ -112,7 +123,7 @@ export declare function createValidationErrors(errors: Array<{
 }>): KoattyValidationError;
 
 /**
- * 装饰器选项
+ * Decorator options
  */
 export declare interface DecoratorOptions {
     name: string;
@@ -126,7 +137,7 @@ export declare const ENABLE_VALIDATED = "ENABLE_VALIDATED";
 export declare const Equals: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 错误信息国际化
+ * Error message internationalization
  */
 export declare const ERROR_MESSAGES: {
     readonly zh: {
@@ -182,31 +193,31 @@ export declare const ERROR_MESSAGES: {
 };
 
 /**
- * 全局错误信息格式化器实例
+ * Global error message formatter instance
  */
 export declare const errorFormatter: ErrorMessageFormatter;
 
 /**
- * 错误信息格式化器
+ * Error message formatter
  */
 export declare class ErrorMessageFormatter {
     constructor(language?: SupportedLanguage);
     /**
-     * 设置语言
+     * Set language
      */
     setLanguage(language: SupportedLanguage): void;
     /**
-     * 格式化错误消息
+     * Format error message
      */
     formatMessage(constraint: string, field: string, value?: any, context?: Record<string, any>): string;
     /**
-     * 格式化值用于消息显示
+     * Format value for message display
      * @private
      */
 }
 
 /**
- * 标记属性为可导出
+ * Mark property as exportable
  */
 export declare function Expose(): PropertyDecorator;
 
@@ -272,7 +283,7 @@ export declare const Gt: (...args: any[]) => (object: Object, propertyName: stri
 export declare const Gte: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 哈希算法类型
+ * Hash algorithm type
  */
 export declare type HashAlgorithm = "md4" | "md5" | "sha1" | "sha256" | "sha384" | "sha512" | "ripemd128" | "ripemd160" | "tiger128" | "tiger160" | "tiger192" | "crc32" | "crc32b";
 
@@ -281,20 +292,20 @@ export declare const IsCnName: (...args: any[]) => (object: Object, propertyName
 export declare const IsDate: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Expose的别名
+ * Alias for Expose
  */
 export declare function IsDefined(): PropertyDecorator;
 
 export declare function IsEmail(options?: IsEmailOptions, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
 
 /**
- * koatty_validation 类型定义
+ * koatty_validation type definitions
  * @author richen
  * @copyright Copyright (c) - <richenlin(at)gmail.com>
  * @license MIT
  */
 /**
- * 邮箱验证选项
+ * Email validation options
  */
 export declare interface IsEmailOptions {
     allow_display_name?: boolean;
@@ -324,7 +335,7 @@ export declare const IsPlateNumber: (...args: any[]) => (object: Object, propert
 export declare function IsUrl(options?: IsURLOptions, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
 
 /**
- * URL验证选项
+ * URL validation options
  */
 export declare interface IsURLOptions {
     protocols?: string[];
@@ -343,7 +354,7 @@ export declare interface IsURLOptions {
 export declare const IsZipCode: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 增强的验证错误类
+ * Enhanced validation error class
  */
 export declare class KoattyValidationError extends Error {
     readonly errors: ValidationErrorDetail[];
@@ -351,15 +362,15 @@ export declare class KoattyValidationError extends Error {
     readonly timestamp: Date;
     constructor(errors: ValidationErrorDetail[], message?: string);
     /**
-     * 获取第一个错误信息
+     * Get the first error message
      */
     getFirstError(): ValidationErrorDetail | undefined;
     /**
-     * 获取指定字段的错误
+     * Get errors for a specific field
      */
     getFieldErrors(field: string): ValidationErrorDetail[];
     /**
-     * 转换为JSON格式
+     * Convert to JSON format
      */
     toJSON(): {
         name: string;
@@ -375,28 +386,28 @@ export declare const Lt: (...args: any[]) => (object: Object, propertyName: stri
 export declare const Lte: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * 元数据缓存
+ * Metadata cache
  */
 declare class MetadataCache {
     static getInstance(): MetadataCache;
     /**
-     * 获取类的元数据缓存
+     * Get metadata cache for a class
      */
     getClassCache(target: Function): Map<string, any>;
     /**
-     * 缓存元数据
+     * Cache metadata
      */
     setMetadata(target: Function, key: string, value: any): void;
     /**
-     * 获取缓存的元数据
+     * Get cached metadata
      */
     getMetadata(target: Function, key: string): any;
     /**
-     * 检查是否已缓存
+     * Check if metadata is cached
      */
     hasMetadata(target: Function, key: string): boolean;
     /**
-     * 清空指定类的缓存
+     * Clear cache for a specific class
      */
     clearClassCache(target: Function): void;
 }
@@ -410,7 +421,7 @@ export declare const PARAM_CHECK_KEY = "PARAM_CHECK_KEY";
 export declare const PARAM_RULE_KEY = "PARAM_RULE_KEY";
 
 /**
- * 参数类型键常量
+ * Parameter type key constant
  */
 export declare const PARAM_TYPE_KEY = "PARAM_TYPE_KEY";
 
@@ -524,21 +535,21 @@ declare class RegexCache {
 export declare const regexCache: RegexCache;
 
 /**
- * 设置全局语言
+ * Set global language
  */
 export declare function setValidationLanguage(language: SupportedLanguage): void;
 
 /**
- * 改进的错误处理机制
+ * Improved error handling mechanism
  * @author richen
  */
 /**
- * 支持的语言
+ * Supported languages
  */
 export declare type SupportedLanguage = 'zh' | 'en';
 
 /**
- * 参数验证装饰器
+ * Parameter validation decorator
  */
 export declare function Valid(rule: ValidRules | ValidRules[] | Function, options?: string | ValidOtpions): ParameterDecorator;
 
@@ -564,13 +575,16 @@ declare class ValidateClass {
 }
 
 /**
- * 方法验证装饰器
- * 自动验证方法参数中的 DTO 对象
+ * Method validation decorator
+ * Automatically validates DTO objects in method parameters
+ * @param isAsync Whether to use async validation mode, default is true
+ *   - true: Async mode, validation is handled by IOC container in the framework (suitable for scenarios where parameter values need to be obtained asynchronously)
+ *   - false: Sync mode, validation is performed immediately when the method is called (suitable for scenarios where parameter values are already prepared)
  */
-export declare function Validated(): MethodDecorator;
+export declare function Validated(isAsync?: boolean): MethodDecorator;
 
 /**
- * 验证结果缓存
+ * Validation result cache
  */
 declare class ValidationCache {
     constructor(options?: CacheOptions);
@@ -623,7 +637,7 @@ declare class ValidationCache {
 export declare const validationCache: ValidationCache;
 
 /**
- * 验证错误详情
+ * Validation error details
  */
 export declare interface ValidationErrorDetail {
     field: string;
@@ -634,7 +648,7 @@ export declare interface ValidationErrorDetail {
 }
 
 /**
- * 验证函数类型定义
+ * Validator function type definition
  */
 export declare type ValidatorFunction = (value: any, ...args: any[]) => boolean;
 
@@ -736,7 +750,7 @@ export declare const ValidFuncs: {
 };
 
 /**
- * 验证选项
+ * Validation options
  */
 export declare type ValidOtpions = {
     message: string;