koatty_validation 1.6.0 → 1.6.3

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /*!
 * @Author: richen
-* @Date: 2025-10-23 01:25:11
+* @Date: 2026-01-28 12:40:19
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
 import { CountryCode } from 'libphonenumber-js';
-import { ValidationOptions } from 'class-validator';
+import { ValidationOptions as ValidationOptions_2 } from 'class-validator';
 
 /**
  * 缓存装饰器 - 用于缓存验证函数结果
@@ -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;
@@ -109,10 +120,10 @@ export declare function createValidationErrors(errors: Array<{
     constraint: string;
     message?: string;
     context?: Record<string, any>;
-}>): KoattyValidationError;
+}>, separator?: string): 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;
+export declare function IsEmail(options?: IsEmailOptions | ValidationOptions_2, validationOptions?: ValidationOptions_2): (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;
@@ -303,13 +314,13 @@ export declare interface IsEmailOptions {
     require_tld?: boolean;
 }
 
-export declare function IsHash(algorithm: HashAlgorithm, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
+export declare function IsHash(algorithm: HashAlgorithm, validationOptions?: ValidationOptions_2): (object: Object, propertyName: string) => void;
 
 export declare const IsIdNumber: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 export declare const IsIn: (...args: any[]) => (object: Object, propertyName: string) => void;
 
-export declare function IsIP(version?: any, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
+export declare function IsIP(version?: any, validationOptions?: ValidationOptions_2): (object: Object, propertyName: string) => void;
 
 export declare const IsMobile: (...args: any[]) => (object: Object, propertyName: string) => void;
 
@@ -317,14 +328,14 @@ export declare const IsNotEmpty: (...args: any[]) => (object: Object, propertyNa
 
 export declare const IsNotIn: (...args: any[]) => (object: Object, propertyName: string) => void;
 
-export declare function IsPhoneNumber(region?: CountryCode, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
+export declare function IsPhoneNumber(region?: CountryCode, validationOptions?: ValidationOptions_2): (object: Object, propertyName: string) => void;
 
 export declare const IsPlateNumber: (...args: any[]) => (object: Object, propertyName: string) => void;
 
-export declare function IsUrl(options?: IsURLOptions, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
+export declare function IsUrl(options?: IsURLOptions, validationOptions?: ValidationOptions_2): (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;
 
@@ -557,20 +568,24 @@ declare class ValidateClass {
      * @param {*} Clazz
      * @param {*} data
      * @param {boolean} [convert=false] auto convert parameters type
+     * @param {ValidationOptions} [options] validation options (returnAllErrors, errorSeparator)
      * @returns {Promise<any>}
      * @memberof ValidateClass
      */
-    valid(Clazz: any, data: any, convert?: boolean): Promise<any>;
+    valid(Clazz: any, data: any, convert?: boolean, options?: ValidationOptions): Promise<any>;
 }
 
 /**
- * 方法验证装饰器
- * 自动验证方法参数中的 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 +638,7 @@ declare class ValidationCache {
 export declare const validationCache: ValidationCache;
 
 /**
- * 验证错误详情
+ * Validation error details
  */
 export declare interface ValidationErrorDetail {
     field: string;
@@ -634,7 +649,26 @@ export declare interface ValidationErrorDetail {
 }
 
 /**
- * 验证函数类型定义
+ * Parameter type key constant
+ */
+/**
+ * Validation options for ClassValidator.valid()
+ */
+export declare interface ValidationOptions {
+    /**
+     * Whether to return all validation errors or only the first one
+     * @default false (backward compatibility - returns only first error)
+     */
+    returnAllErrors?: boolean;
+    /**
+     * Separator for joining multiple error messages
+     * @default '; '
+     */
+    errorSeparator?: string;
+}
+
+/**
+ * Validator function type definition
  */
 export declare type ValidatorFunction = (value: any, ...args: any[]) => boolean;
 
@@ -736,7 +770,7 @@ export declare const ValidFuncs: {
 };
 
 /**
- * 验证选项
+ * Validation options
  */
 export declare type ValidOtpions = {
     message: string;