koatty_validation 1.4.0 → 1.6.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-10 23:32:33
+* @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,45 +193,62 @@ 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;
 
 /**
  * Use functions or built-in rules for validation.
+ * Throws error if validation fails.
  *
  * @export
- * @param {ValidRules} rule
- * @param {unknown} value
- * @param {(string | ValidOtpions)} [options]
- * @returns {*}
  */
 export declare const FunctionValidator: {
-    [key in ValidRules]: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsNotEmpty: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsDate: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsEmail: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsIP: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsPhoneNumber: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsUrl: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsHash: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsCnName: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsIdNumber: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsZipCode: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsMobile: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsPlateNumber: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly Equals: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly NotEquals: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly Contains: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsIn: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly IsNotIn: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly Gt: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly Lt: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly Gte: (value: unknown, options?: string | ValidOtpions) => void;
+    readonly Lte: (value: unknown, options?: string | ValidOtpions) => void;
 };
 
 /**
@@ -232,6 +260,10 @@ export declare function getAllCacheStats(): {
         max: number;
         calculatedSize: number;
         keyCount: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        totalRequests: number;
     };
     regex: {
         size: number;
@@ -251,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";
 
@@ -260,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;
@@ -303,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[];
@@ -322,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[];
@@ -330,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;
@@ -354,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;
 }
@@ -388,6 +420,11 @@ 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";
+
 /**
  * paramterTypes
  *
@@ -498,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;
 
@@ -538,12 +575,16 @@ declare class ValidateClass {
 }
 
 /**
- * 方法验证装饰器
+ * 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);
@@ -582,6 +623,10 @@ declare class ValidationCache {
         max: number;
         calculatedSize: number;
         keyCount: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        totalRequests: number;
     };
     /**
      * 设置缓存TTL
@@ -592,7 +637,7 @@ declare class ValidationCache {
 export declare const validationCache: ValidationCache;
 
 /**
- * 验证错误详情
+ * Validation error details
  */
 export declare interface ValidationErrorDetail {
     field: string;
@@ -603,7 +648,7 @@ export declare interface ValidationErrorDetail {
 }
 
 /**
- * 验证函数类型定义
+ * Validator function type definition
  */
 export declare type ValidatorFunction = (value: any, ...args: any[]) => boolean;
 
@@ -619,7 +664,7 @@ export declare const ValidFuncs: {
     /**
      * Checks if a given value is a real date.
      */
-    IsDate: (value: unknown) => value is Date;
+    IsDate: (value: unknown) => boolean;
     /**
      * Checks if the string is an email. If given value is not a string, then it returns false.
      */
@@ -636,11 +681,11 @@ export declare const ValidFuncs: {
      * See [google-libphonenumber, metadata.js:countryCodeToRegionCodeMap on github]
      * {@link https://github.com/ruimarinho/google-libphonenumber/blob/1e46138878cff479aafe2ce62175c6c49cb58720/src/metadata.js#L33}
      */
-    IsPhoneNumber: (value: string, region?: CountryCode) => boolean;
+    IsPhoneNumber: (value: unknown, region?: CountryCode) => boolean;
     /**
      * Checks if the string is an url. If given value is not a string, then it returns false.
      */
-    IsUrl: (value: string, options?: IsURLOptions) => boolean;
+    IsUrl: (value: unknown, options?: IsURLOptions) => boolean;
     /**
      * check if the string is a hash of type algorithm. Algorithm is one of
      * ['md4', 'md5', 'sha1', 'sha256', 'sha384', 'sha512', 'ripemd128', 'ripemd160', 'tiger128', 'tiger160', 'tiger192', 'crc32', 'crc32b']
@@ -649,23 +694,23 @@ export declare const ValidFuncs: {
     /**
      * Checks if value is a chinese name.
      */
-    IsCnName: (value: any) => boolean;
+    IsCnName: (value: unknown) => boolean;
     /**
      * Checks if value is a idcard number.
      */
-    IsIdNumber: (value: any) => boolean;
+    IsIdNumber: (value: unknown) => boolean;
     /**
      * Checks if value is a zipCode.
      */
-    IsZipCode: (value: any) => boolean;
+    IsZipCode: (value: unknown) => boolean;
     /**
      * Checks if value is a mobile phone number.
      */
-    IsMobile: (value: any) => boolean;
+    IsMobile: (value: unknown) => boolean;
     /**
      * Checks if value is a plateNumber.
      */
-    IsPlateNumber: (value: any) => boolean;
+    IsPlateNumber: (value: unknown) => boolean;
     /**
      * Checks if value matches ("===") the comparison.
      */
@@ -689,23 +734,23 @@ export declare const ValidFuncs: {
     /**
      * Checks if the first number is greater than or equal to the second.
      */
-    Gt: (num: unknown, min: number) => boolean;
+    Gt: (value: unknown, min: number) => boolean;
     /**
      * Checks if the first number is less than or equal to the second.
      */
-    Lt: (num: unknown, max: number) => boolean;
+    Lt: (value: unknown, max: number) => boolean;
     /**
      * Checks if the first number is greater than or equal to the second.
      */
-    Gte: (num: unknown, min: number) => boolean;
+    Gte: (value: unknown, min: number) => boolean;
     /**
      * Checks if the first number is less than or equal to the second.
      */
-    Lte: (num: unknown, max: number) => boolean;
+    Lte: (value: unknown, max: number) => boolean;
 };
 
 /**
- * 验证选项
+ * Validation options
  */
 export declare type ValidOtpions = {
     message: string;