koatty_validation 1.3.6 → 1.6.0

package/dist/index.d.ts

@@ -1,21 +1,27 @@
 /*!
 * @Author: richen
-* @Date: 2024-11-06 10:51:37
+* @Date: 2025-10-23 01:25:11
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
 import { CountryCode } from 'libphonenumber-js';
-import { IsIpVersion } from 'class-validator';
 import { ValidationOptions } from 'class-validator';
 
 /**
- * Use a custom function for validation
- * @param func
- * @param validationOptions
- * @returns
+ * 缓存装饰器 - 用于缓存验证函数结果
+ */
+export declare function cached(validator: string, ttl?: number): (target: any, propertyName: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
+/**
+ * 缓存配置选项
  */
-export declare function CheckFunc(func: (value: unknown) => boolean, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare interface CacheOptions {
+    max?: number;
+    ttl?: number;
+    allowStale?: boolean;
+    updateAgeOnGet?: boolean;
+}
 
 /**
  * Check the base types.
@@ -32,14 +38,19 @@ export declare function checkParamsType(value: any, type: string): any;
 export declare const ClassValidator: ValidateClass;
 
 /**
- * Checks if the string contains the seed.
- *
- * @export
- * @param {string} seed
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 清空所有缓存
  */
-export declare function Contains(seed: string, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare function clearAllCaches(): void;
+
+/**
+ * 配置缓存设置
+ */
+export declare function configureCaches(options: {
+    validation?: CacheOptions;
+    regex?: CacheOptions;
+}): void;
+
+export declare const Contains: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
  * convertDtoParamsType
@@ -59,208 +70,262 @@ export declare function convertDtoParamsType(clazz: any, cls: any): any;
  */
 export declare function convertParamsType(param: any, type: string): any;
 
-export declare const ENABLE_VALIDATED = "ENABLE_VALIDATED";
-
 /**
- * Checks if value matches ("===") the comparison.
- *
- * @export
- * @param {*} comparison
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 创建带参数的验证装饰器
+ * @param name 装饰器名称
+ * @param validator 验证函数
+ * @param defaultMessage 默认错误信息
+ * @returns 装饰器工厂函数
  */
-export declare function Equals(comparison: any, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare function createParameterizedDecorator(name: string, validator: ValidatorFunction, defaultMessage?: string): (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Marks property as included in the process of transformation.
- *
- * @export
- * @returns {PropertyDecorator}
+ * 创建简单验证装饰器（不需要额外参数）
+ * @param name 装饰器名称
+ * @param validator 验证函数
+ * @param defaultMessage 默认错误信息
+ * @returns 装饰器函数
  */
-export declare function Expose(): PropertyDecorator;
+export declare function createSimpleDecorator(name: string, validator: ValidatorFunction, defaultMessage?: string): (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Use functions or built-in rules for validation.
- *
- * @export
- * @param {ValidRules} rule
- * @param {unknown} value
- * @param {(string | ValidOtpions)} [options]
- * @returns {*}
+ * 创建验证装饰器的工厂函数
+ * @param options 装饰器配置选项
+ * @returns 装饰器工厂函数
  */
-export declare const FunctionValidator: {
-    [key in ValidRules]: (value: unknown, options?: string | ValidOtpions) => void;
-};
+export declare function createValidationDecorator(options: DecoratorOptions): (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Checks if the first number is greater than or equal to the min value.
- *
- * @export
- * @param {number} min
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 创建验证错误
  */
-export declare function Gt(min: number, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare function createValidationError(field: string, value: any, constraint: string, customMessage?: string, context?: Record<string, any>): ValidationErrorDetail;
 
 /**
- * Checks if the first number is greater than or equal to the min value.
- *
- * @export
- * @param {number} min
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 批量创建验证错误
  */
-export declare function Gte(min: number, validationOptions?: ValidationOptions): PropertyDecorator;
-
-export declare type HashAlgorithm = "md4" | "md5" | "sha1" | "sha256" | "sha384" | "sha512" | "ripemd128" | "ripemd160" | "tiger128" | "tiger160" | "tiger192" | "crc32" | "crc32b";
+export declare function createValidationErrors(errors: Array<{
+    field: string;
+    value: any;
+    constraint: string;
+    message?: string;
+    context?: Record<string, any>;
+}>): KoattyValidationError;
 
 /**
- * Checks if value is a chinese name.
- *
- * @export
- * @param {string} property
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 装饰器选项
  */
-export declare function IsCnName(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare interface DecoratorOptions {
+    name: string;
+    validator: ValidatorFunction;
+    defaultMessage?: string;
+    requiresValue?: boolean;
+}
 
-/**
- * Checks if a given value is a real date.
- *
- * @export
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function IsDate(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const ENABLE_VALIDATED = "ENABLE_VALIDATED";
+
+export declare const Equals: (...args: any[]) => (object: Object, propertyName: string) => void;
+
+/**
+ * 错误信息国际化
+ */
+export declare const ERROR_MESSAGES: {
+    readonly zh: {
+        readonly IsCnName: "必须是有效的中文姓名";
+        readonly IsIdNumber: "必须是有效的身份证号码";
+        readonly IsZipCode: "必须是有效的邮政编码";
+        readonly IsMobile: "必须是有效的手机号码";
+        readonly IsPlateNumber: "必须是有效的车牌号码";
+        readonly IsNotEmpty: "不能为空";
+        readonly IsDate: "必须是有效的日期";
+        readonly IsEmail: "必须是有效的邮箱地址";
+        readonly IsIP: "必须是有效的IP地址";
+        readonly IsPhoneNumber: "必须是有效的电话号码";
+        readonly IsUrl: "必须是有效的URL地址";
+        readonly IsHash: "必须是有效的哈希值";
+        readonly Equals: "必须等于 {comparison}";
+        readonly NotEquals: "不能等于 {comparison}";
+        readonly Contains: "必须包含 {seed}";
+        readonly IsIn: "必须是以下值之一: {possibleValues}";
+        readonly IsNotIn: "不能是以下值之一: {possibleValues}";
+        readonly Gt: "必须大于 {min}";
+        readonly Gte: "必须大于或等于 {min}";
+        readonly Lt: "必须小于 {max}";
+        readonly Lte: "必须小于或等于 {max}";
+        readonly invalidParameter: "参数 {field} 无效";
+        readonly validationFailed: "验证失败";
+    };
+    readonly en: {
+        readonly IsCnName: "must be a valid Chinese name";
+        readonly IsIdNumber: "must be a valid ID number";
+        readonly IsZipCode: "must be a valid zip code";
+        readonly IsMobile: "must be a valid mobile number";
+        readonly IsPlateNumber: "must be a valid plate number";
+        readonly IsNotEmpty: "should not be empty";
+        readonly IsDate: "must be a valid date";
+        readonly IsEmail: "must be a valid email";
+        readonly IsIP: "must be a valid IP address";
+        readonly IsPhoneNumber: "must be a valid phone number";
+        readonly IsUrl: "must be a valid URL";
+        readonly IsHash: "must be a valid hash";
+        readonly Equals: "must equal to {comparison}";
+        readonly NotEquals: "should not equal to {comparison}";
+        readonly Contains: "must contain {seed}";
+        readonly IsIn: "must be one of the following values: {possibleValues}";
+        readonly IsNotIn: "should not be one of the following values: {possibleValues}";
+        readonly Gt: "must be greater than {min}";
+        readonly Gte: "must be greater than or equal to {min}";
+        readonly Lt: "must be less than {max}";
+        readonly Lte: "must be less than or equal to {max}";
+        readonly invalidParameter: "invalid parameter {field}";
+        readonly validationFailed: "validation failed";
+    };
+};
 
 /**
- * Alias of Expose
- *
- * @export
- * @returns {PropertyDecorator}
+ * 全局错误信息格式化器实例
  */
-export declare function IsDefined(): PropertyDecorator;
+export declare const errorFormatter: ErrorMessageFormatter;
 
 /**
- * Checks if the string is an email. If given value is not a string, then it returns false.
- *
- * @export
- * @param {IsEmailOptions} [options]
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 错误信息格式化器
  */
-export declare function IsEmail(options?: IsEmailOptions, validationOptions?: ValidationOptions): PropertyDecorator;
-
-export declare interface IsEmailOptions {
-    allow_display_name?: boolean;
-    require_display_name?: boolean;
-    allow_utf8_local_part?: boolean;
-    require_tld?: boolean;
+export declare class ErrorMessageFormatter {
+    constructor(language?: SupportedLanguage);
+    /**
+     * 设置语言
+     */
+    setLanguage(language: SupportedLanguage): void;
+    /**
+     * 格式化错误消息
+     */
+    formatMessage(constraint: string, field: string, value?: any, context?: Record<string, any>): string;
+    /**
+     * 格式化值用于消息显示
+     * @private
+     */
 }
 
 /**
- * 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']
- *
- * @export
- * @param {HashAlgorithm} algorithm
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 标记属性为可导出
  */
-export declare function IsHash(algorithm: HashAlgorithm, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare function Expose(): PropertyDecorator;
 
 /**
- * Checks if value is a idCard number(chinese).
+ * Use functions or built-in rules for validation.
+ * Throws error if validation fails.
  *
  * @export
- * @param {string} property
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
  */
-export declare function IsIdNumber(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const FunctionValidator: {
+    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;
+};
 
 /**
- * Checks if given value is in a array of allowed values.
- *
- * @export
- * @param {any[]} possibleValues
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function IsIn(possibleValues: any[], validationOptions?: ValidationOptions): PropertyDecorator;
+ * 获取所有缓存统计信息
+ */
+export declare function getAllCacheStats(): {
+    validation: {
+        size: number;
+        max: number;
+        calculatedSize: number;
+        keyCount: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        totalRequests: number;
+    };
+    regex: {
+        size: number;
+        max: number;
+        calculatedSize: number;
+    };
+    performance: Record<string, any>;
+    hotspots: {
+        name: string;
+        avgTime: number;
+        count: number;
+    }[];
+};
 
-/**
- * Checks if the string is an IP (version 4 or 6). If given value is not a string, then it returns false.
- *
- * @export
- * @param {number} [version]
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function IsIP(version?: IsIpVersion, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const Gt: (...args: any[]) => (object: Object, propertyName: string) => void;
 
-/**
- * Checks if value is a mobile phone number(chinese).
- *
- * @export
- * @param {string} property
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function IsMobile(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const Gte: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Checks value is not empty, undefined, null, '', NaN, [], {} and any empty string(including spaces, tabs, formfeeds, etc.), returns false.
- *
- * @export
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 哈希算法类型
  */
-export declare function IsNotEmpty(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare type HashAlgorithm = "md4" | "md5" | "sha1" | "sha256" | "sha384" | "sha512" | "ripemd128" | "ripemd160" | "tiger128" | "tiger160" | "tiger192" | "crc32" | "crc32b";
+
+export declare const IsCnName: (...args: any[]) => (object: Object, propertyName: string) => void;
+
+export declare const IsDate: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Checks if given value not in a array of allowed values.
- *
- * @export
- * @param {any[]} possibleValues
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * Expose的别名
  */
-export declare function IsNotIn(possibleValues: any[], validationOptions?: ValidationOptions): PropertyDecorator;
+export declare function IsDefined(): PropertyDecorator;
+
+export declare function IsEmail(options?: IsEmailOptions, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
 
 /**
- * Checks if the string is a valid phone number.
- *
- * @export
- * @param {string} {string} region 2 characters uppercase country code (e.g. DE, US, CH).
- * If users must enter the intl. prefix (e.g. +41), then you may pass "ZZ" or null as region.
- * See [google-libphonenumber, metadata.js:countryCodeToRegionCodeMap on github]
- * {@link https://github.com/ruimarinho/google-libphonenumber/blob/1e46138878cff479aafe2ce62175c6c49cb58720/src/metadata.js#L33}
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * koatty_validation 类型定义
+ * @author richen
+ * @copyright Copyright (c) - <richenlin(at)gmail.com>
+ * @license MIT
  */
-export declare function IsPhoneNumber(region?: CountryCode, validationOptions?: ValidationOptions): PropertyDecorator;
-
 /**
- * Checks if value is a plate number(chinese).
- *
- * @export
- * @param {string} property
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 邮箱验证选项
  */
-export declare function IsPlateNumber(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare interface IsEmailOptions {
+    allow_display_name?: boolean;
+    require_display_name?: boolean;
+    allow_utf8_local_part?: boolean;
+    require_tld?: boolean;
+}
+
+export declare function IsHash(algorithm: HashAlgorithm, validationOptions?: ValidationOptions): (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 const IsMobile: (...args: any[]) => (object: Object, propertyName: string) => void;
+
+export declare const IsNotEmpty: (...args: any[]) => (object: Object, propertyName: string) => void;
+
+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 const IsPlateNumber: (...args: any[]) => (object: Object, propertyName: string) => void;
+
+export declare function IsUrl(options?: IsURLOptions, validationOptions?: ValidationOptions): (object: Object, propertyName: string) => void;
 
 /**
- * Checks if the string is an url.
- *
- * @export
- * @param {IsURLOptions} [options]
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * URL验证选项
  */
-export declare function IsUrl(options?: IsURLOptions, validationOptions?: ValidationOptions): PropertyDecorator;
-
 export declare interface IsURLOptions {
     protocols?: string[];
     require_tld?: boolean;
@@ -275,62 +340,78 @@ export declare interface IsURLOptions {
     disallow_auth?: boolean;
 }
 
-/**
- * Checks if value is a zipCode(chinese).
- *
- * @export
- * @param {string} property
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function IsZipCode(validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const IsZipCode: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Checks if the string's length falls in a range. Note: this function takes into account surrogate pairs.
- * If given value is not a string, then it returns false.
- *
- * @export
- * @param {number} min
- * @param {number} [max]
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 增强的验证错误类
  */
-export declare function Length(min: number, max?: number, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare class KoattyValidationError extends Error {
+    readonly errors: ValidationErrorDetail[];
+    readonly statusCode: number;
+    readonly timestamp: Date;
+    constructor(errors: ValidationErrorDetail[], message?: string);
+    /**
+     * 获取第一个错误信息
+     */
+    getFirstError(): ValidationErrorDetail | undefined;
+    /**
+     * 获取指定字段的错误
+     */
+    getFieldErrors(field: string): ValidationErrorDetail[];
+    /**
+     * 转换为JSON格式
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        statusCode: number;
+        timestamp: Date;
+        errors: ValidationErrorDetail[];
+    };
+}
 
-/**
- * Checks if the first number is less than or equal to the max value.
- *
- * @export
- * @param {number} max
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function Lt(max: number, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const Lt: (...args: any[]) => (object: Object, propertyName: string) => void;
 
-/**
- * Checks if the first number is less than or equal to the max value.
- *
- * @export
- * @param {number} max
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
- */
-export declare function Lte(max: number, validationOptions?: ValidationOptions): PropertyDecorator;
+export declare const Lte: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 /**
- * Checks if value does not match ("!==") the comparison.
- *
- * @export
- * @param {*} comparison
- * @param {ValidationOptions} [validationOptions]
- * @returns {PropertyDecorator}
+ * 元数据缓存
  */
-export declare function NotEquals(comparison: any, validationOptions?: ValidationOptions): PropertyDecorator;
+declare class MetadataCache {
+    static getInstance(): MetadataCache;
+    /**
+     * 获取类的元数据缓存
+     */
+    getClassCache(target: Function): Map<string, any>;
+    /**
+     * 缓存元数据
+     */
+    setMetadata(target: Function, key: string, value: any): void;
+    /**
+     * 获取缓存的元数据
+     */
+    getMetadata(target: Function, key: string): any;
+    /**
+     * 检查是否已缓存
+     */
+    hasMetadata(target: Function, key: string): boolean;
+    /**
+     * 清空指定类的缓存
+     */
+    clearClassCache(target: Function): void;
+}
+
+export declare const metadataCache: MetadataCache;
+
+export declare const NotEquals: (...args: any[]) => (object: Object, propertyName: string) => void;
 
 export declare const PARAM_CHECK_KEY = "PARAM_CHECK_KEY";
 
 export declare const PARAM_RULE_KEY = "PARAM_RULE_KEY";
 
+/**
+ * 参数类型键常量
+ */
 export declare const PARAM_TYPE_KEY = "PARAM_TYPE_KEY";
 
 /**
@@ -362,6 +443,42 @@ export declare enum paramterTypes {
     "undefined" = 19
 }
 
+/**
+ * 性能监控
+ */
+declare class PerformanceMonitor {
+    static getInstance(): PerformanceMonitor;
+    /**
+     * 开始计时
+     */
+    startTimer(name: string): () => void;
+    /**
+     * 记录性能指标
+     */
+    /**
+     * 获取性能报告
+     */
+    getReport(): Record<string, any>;
+    /**
+     * 获取热点分析（执行时间最长的操作）
+     */
+    getHotspots(limit?: number): Array<{
+        name: string;
+        avgTime: number;
+        count: number;
+    }>;
+    /**
+     * 清空指标
+     */
+    clear(): void;
+    /**
+     * 导出性能数据为CSV格式
+     */
+    exportToCSV(): string;
+}
+
+export declare const performanceMonitor: PerformanceMonitor;
+
 /**
  * plain object convert to class instance
  *
@@ -374,13 +491,54 @@ export declare enum paramterTypes {
 export declare function plainToClass(clazz: any, data: any, convert?: boolean): any;
 
 /**
- * Validation parameter's type and values.
- *
- * @export
- * @param {(ValidRules | ValidRules[] | Function)} rule
- * @param {*} [options] If the options type is a string, the value is the error message of the validation rule.
- * Some validation rules require additional parameters, ext: @Valid("Gte", {message:"Requires value greater than or equal to 100", value: 100})
- * @returns {*}  {ParameterDecorator}
+ * 正则表达式缓存
+ */
+declare class RegexCache {
+    constructor(options?: CacheOptions);
+    static getInstance(options?: CacheOptions): RegexCache;
+    /**
+     * 获取缓存的正则表达式
+     */
+    get(pattern: string, flags?: string): RegExp;
+    /**
+     * 预编译常用正则表达式
+     */
+    precompile(patterns: Array<{
+        pattern: string;
+        flags?: string;
+    }>): void;
+    /**
+     * 获取缓存统计
+     */
+    getStats(): {
+        size: number;
+        max: number;
+        calculatedSize: number;
+    };
+    /**
+     * 清空缓存
+     */
+    clear(): void;
+}
+
+export declare const regexCache: RegexCache;
+
+/**
+ * 设置全局语言
+ */
+export declare function setValidationLanguage(language: SupportedLanguage): void;
+
+/**
+ * 改进的错误处理机制
+ * @author richen
+ */
+/**
+ * 支持的语言
+ */
+export declare type SupportedLanguage = 'zh' | 'en';
+
+/**
+ * 参数验证装饰器
  */
 export declare function Valid(rule: ValidRules | ValidRules[] | Function, options?: string | ValidOtpions): ParameterDecorator;
 
@@ -406,13 +564,80 @@ declare class ValidateClass {
 }
 
 /**
- * Validation parameter's type and values from DTO class.
- *
- * @export
- * @returns {MethodDecorator}
+ * 方法验证装饰器
+ * 自动验证方法参数中的 DTO 对象
  */
 export declare function Validated(): MethodDecorator;
 
+/**
+ * 验证结果缓存
+ */
+declare class ValidationCache {
+    constructor(options?: CacheOptions);
+    static getInstance(options?: CacheOptions): ValidationCache;
+    /**
+     * 生成缓存键
+     */
+    /**
+     * 序列化值用于缓存键
+     */
+    /**
+     * 获取缓存的验证结果
+     */
+    get(validator: string, value: any, ...args: any[]): boolean | undefined;
+    /**
+     * 缓存验证结果
+     */
+    set(validator: string, value: any, result: boolean, ...args: any[]): void;
+    /**
+     * 检查是否存在缓存
+     */
+    has(validator: string, value: any, ...args: any[]): boolean;
+    /**
+     * 删除特定缓存
+     */
+    delete(validator: string, value: any, ...args: any[]): boolean;
+    /**
+     * 清空缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存统计
+     */
+    getStats(): {
+        size: number;
+        max: number;
+        calculatedSize: number;
+        keyCount: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        totalRequests: number;
+    };
+    /**
+     * 设置缓存TTL
+     */
+    setTTL(validator: string, value: any, ttl: number, ...args: any[]): void;
+}
+
+export declare const validationCache: ValidationCache;
+
+/**
+ * 验证错误详情
+ */
+export declare interface ValidationErrorDetail {
+    field: string;
+    value: any;
+    constraint: string;
+    message: string;
+    context?: Record<string, any>;
+}
+
+/**
+ * 验证函数类型定义
+ */
+export declare type ValidatorFunction = (value: any, ...args: any[]) => boolean;
+
 /**
  * Validator Functions
  */
@@ -442,11 +667,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']
@@ -455,23 +680,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.
      */
@@ -495,21 +720,24 @@ 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;
 };
 
+/**
+ * 验证选项
+ */
 export declare type ValidOtpions = {
     message: string;
     value: any;
@@ -523,4 +751,9 @@ export declare type ValidOtpions = {
  */
 export declare type ValidRules = "IsNotEmpty" | "IsDate" | "IsEmail" | "IsIP" | "IsPhoneNumber" | "IsUrl" | "IsHash" | "IsCnName" | "IsIdNumber" | "IsZipCode" | "IsMobile" | "IsPlateNumber" | "Equals" | "NotEquals" | "Contains" | "IsIn" | "IsNotIn" | "Gt" | "Lt" | "Gte" | "Lte";
 
+/**
+ * 预热缓存 - 预编译常用正则表达式
+ */
+export declare function warmupCaches(): void;
+
 export { }