koatty_validation 1.6.0 → 1.6.3

package/dist/index.js

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-10-23 01:25:03
+* @Date: 2026-01-28 12:40:10
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
@@ -33,22 +33,22 @@ function _interopNamespaceDefault(e) {
 var helper__namespace = /*#__PURE__*/_interopNamespaceDefault(helper);
 
 /**
- * koatty_validation 类型定义
+ * koatty_validation type definitions
  * @author richen
  * @copyright Copyright (c) - <richenlin(at)gmail.com>
  * @license MIT
  */
 /**
- * 参数类型键常量
+ * Parameter type key constant
  */
 const PARAM_TYPE_KEY = 'PARAM_TYPE_KEY';
 
 /**
- * 性能缓存模块 - 提供多层次缓存和性能监控
+ * Performance cache module - Provides multi-level caching and performance monitoring
  * @author richen
  */
 /**
- * 元数据缓存
+ * Metadata cache
  */
 class MetadataCache {
     constructor() {
@@ -61,7 +61,7 @@ class MetadataCache {
         return MetadataCache.instance;
     }
     /**
-     * 获取类的元数据缓存
+     * Get metadata cache for a class
      */
     getClassCache(target) {
         if (!this.cache.has(target)) {
@@ -70,28 +70,28 @@ class MetadataCache {
         return this.cache.get(target);
     }
     /**
-     * 缓存元数据
+     * Cache metadata
      */
     setMetadata(target, key, value) {
         const classCache = this.getClassCache(target);
         classCache.set(key, value);
     }
     /**
-     * 获取缓存的元数据
+     * Get cached metadata
      */
     getMetadata(target, key) {
         const classCache = this.getClassCache(target);
         return classCache.get(key);
     }
     /**
-     * 检查是否已缓存
+     * Check if metadata is cached
      */
     hasMetadata(target, key) {
         const classCache = this.getClassCache(target);
         return classCache.has(key);
     }
     /**
-     * 清空指定类的缓存
+     * Clear cache for a specific class
      */
     clearClassCache(target) {
         if (this.cache.has(target)) {
@@ -100,7 +100,7 @@ class MetadataCache {
     }
 }
 /**
- * 验证结果缓存
+ * Validation result cache
  */
 class ValidationCache {
     constructor(options) {
@@ -108,7 +108,7 @@ class ValidationCache {
         this.misses = 0;
         this.cache = new lruCache.LRUCache({
             max: (options === null || options === void 0 ? void 0 : options.max) || 5000,
-            ttl: (options === null || options === void 0 ? void 0 : options.ttl) || 1000 * 60 * 10, // 10分钟
+            ttl: (options === null || options === void 0 ? void 0 : options.ttl) || 1000 * 60 * 10, // 10 minutes
             allowStale: (options === null || options === void 0 ? void 0 : options.allowStale) || false,
             updateAgeOnGet: (options === null || options === void 0 ? void 0 : options.updateAgeOnGet) || true,
         });
@@ -226,7 +226,7 @@ class RegexCache {
     constructor(options) {
         this.cache = new lruCache.LRUCache({
             max: (options === null || options === void 0 ? void 0 : options.max) || 200,
-            ttl: (options === null || options === void 0 ? void 0 : options.ttl) || 1000 * 60 * 30, // 30分钟
+            ttl: (options === null || options === void 0 ? void 0 : options.ttl) || 1000 * 60 * 30, // 30 minutes
             allowStale: (options === null || options === void 0 ? void 0 : options.allowStale) || false,
             updateAgeOnGet: (options === null || options === void 0 ? void 0 : options.updateAgeOnGet) || true,
         });
@@ -410,7 +410,7 @@ function cached(validator, ttl) {
             try {
                 const result = originalMethod.apply(this, args);
                 validationCache.set(validator, value, result, ...additionalArgs);
-                // 如果指定了TTL，设置过期时间
+                // If TTL is specified, set expiration time
                 if (ttl && ttl > 0) {
                     validationCache.setTTL(validator, value, ttl, ...additionalArgs);
                 }
@@ -820,6 +820,209 @@ function plateNumber(value) {
     }
 }
 
+/**
+ * Improved error handling mechanism
+ * @author richen
+ */
+/**
+ * Error message internationalization
+ */
+const ERROR_MESSAGES = {
+    zh: {
+        // Chinese localization validation
+        IsCnName: '必须是有效的中文姓名',
+        IsIdNumber: '必须是有效的身份证号码',
+        IsZipCode: '必须是有效的邮政编码',
+        IsMobile: '必须是有效的手机号码',
+        IsPlateNumber: '必须是有效的车牌号码',
+        // Basic validation
+        IsNotEmpty: '不能为空',
+        IsDate: '必须是有效的日期',
+        IsEmail: '必须是有效的邮箱地址',
+        IsIP: '必须是有效的IP地址',
+        IsPhoneNumber: '必须是有效的电话号码',
+        IsUrl: '必须是有效的URL地址',
+        IsHash: '必须是有效的哈希值',
+        // Comparison validation
+        Equals: '必须等于 {comparison}',
+        NotEquals: '不能等于 {comparison}',
+        Contains: '必须包含 {seed}',
+        IsIn: '必须是以下值之一: {possibleValues}',
+        IsNotIn: '不能是以下值之一: {possibleValues}',
+        Gt: '必须大于 {min}',
+        Gte: '必须大于或等于 {min}',
+        Lt: '必须小于 {max}',
+        Lte: '必须小于或等于 {max}',
+        // Common errors
+        invalidParameter: '参数 {field} 无效',
+        validationFailed: '验证失败',
+    },
+    en: {
+        // Chinese localization validators
+        IsCnName: 'must be a valid Chinese name',
+        IsIdNumber: 'must be a valid ID number',
+        IsZipCode: 'must be a valid zip code',
+        IsMobile: 'must be a valid mobile number',
+        IsPlateNumber: 'must be a valid plate number',
+        // Basic validators
+        IsNotEmpty: 'should not be empty',
+        IsDate: 'must be a valid date',
+        IsEmail: 'must be a valid email',
+        IsIP: 'must be a valid IP address',
+        IsPhoneNumber: 'must be a valid phone number',
+        IsUrl: 'must be a valid URL',
+        IsHash: 'must be a valid hash',
+        // Comparison validators
+        Equals: 'must equal to {comparison}',
+        NotEquals: 'should not equal to {comparison}',
+        Contains: 'must contain {seed}',
+        IsIn: 'must be one of the following values: {possibleValues}',
+        IsNotIn: 'should not be one of the following values: {possibleValues}',
+        Gt: 'must be greater than {min}',
+        Gte: 'must be greater than or equal to {min}',
+        Lt: 'must be less than {max}',
+        Lte: 'must be less than or equal to {max}',
+        // Common errors
+        invalidParameter: 'invalid parameter {field}',
+        validationFailed: 'validation failed',
+    }
+};
+/**
+ * Enhanced validation error class
+ */
+class KoattyValidationError extends Error {
+    constructor(errors, message) {
+        const errorMessage = message || 'Validation failed';
+        super(errorMessage);
+        this.name = 'KoattyValidationError';
+        this.errors = errors;
+        this.statusCode = 400;
+        this.timestamp = new Date();
+        // Ensure correct prototype chain
+        Object.setPrototypeOf(this, KoattyValidationError.prototype);
+    }
+    /**
+     * Get the first error message
+     */
+    getFirstError() {
+        return this.errors[0];
+    }
+    /**
+     * Get errors for a specific field
+     */
+    getFieldErrors(field) {
+        return this.errors.filter(error => error.field === field);
+    }
+    /**
+     * Convert to JSON format
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            statusCode: this.statusCode,
+            timestamp: this.timestamp,
+            errors: this.errors
+        };
+    }
+}
+/**
+ * Error message formatter
+ */
+class ErrorMessageFormatter {
+    constructor(language = 'zh') {
+        this.language = 'zh';
+        this.language = language;
+    }
+    /**
+     * Set language
+     */
+    setLanguage(language) {
+        this.language = language;
+    }
+    /**
+     * Format error message
+     */
+    formatMessage(constraint, field, value, context) {
+        const messages = ERROR_MESSAGES[this.language];
+        let template = messages[constraint] || messages.invalidParameter;
+        // Replace placeholders
+        template = template.replace('{field}', field);
+        // Prioritize values from context, then use passed value
+        if (context) {
+            Object.entries(context).forEach(([key, val]) => {
+                template = template.replace(`{${key}}`, this.formatValue(val));
+            });
+        }
+        // If there's still a {value} placeholder and value was passed, replace it
+        if (value !== undefined && template.includes('{value}')) {
+            template = template.replace('{value}', this.formatValue(value));
+        }
+        return template;
+    }
+    /**
+     * Format value for message display
+     * @private
+     */
+    formatValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'number')
+            return String(value);
+        if (typeof value === 'string')
+            return `"${value}"`;
+        if (Array.isArray(value))
+            return `[${value.map(v => this.formatValue(v)).join(', ')}]`;
+        if (typeof value === 'object') {
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                // Handle circular references
+                return '[Circular Reference]';
+            }
+        }
+        return String(value);
+    }
+}
+/**
+ * Global error message formatter instance
+ */
+const errorFormatter = new ErrorMessageFormatter();
+/**
+ * Set global language
+ */
+function setValidationLanguage(language) {
+    errorFormatter.setLanguage(language);
+}
+/**
+ * Create validation error
+ */
+function createValidationError(field, value, constraint, customMessage, context) {
+    const message = customMessage || errorFormatter.formatMessage(constraint, field, value, context);
+    return {
+        field,
+        value,
+        constraint,
+        message,
+        context
+    };
+}
+/**
+ * Create validation errors in batch
+ */
+function createValidationErrors(errors, separator = '; ') {
+    const validationErrors = errors.map(error => createValidationError(error.field, error.value, error.constraint, error.message, error.context));
+    // Generate combined message from all errors
+    const combinedMessage = validationErrors
+        .map(err => err.message)
+        .filter(msg => msg && msg.trim())
+        .join(separator) || 'Validation failed';
+    return new KoattyValidationError(validationErrors, combinedMessage);
+}
+
 /*
  * @Description:
  * @Usage:
@@ -879,10 +1082,11 @@ 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
      */
-    async valid(Clazz, data, convert = false) {
+    async valid(Clazz, data, convert = false, options) {
         let obj = {};
         if (data instanceof Clazz) {
             obj = data;
@@ -898,7 +1102,21 @@ class ValidateClass {
             errors = await classValidator.validate(obj, { skipMissingProperties: true });
         }
         if (errors.length > 0) {
-            throw new Error(Object.values(errors[0].constraints)[0]);
+            // Check if user wants all errors or just the first one
+            if (options === null || options === void 0 ? void 0 : options.returnAllErrors) {
+                // Throw KoattyValidationError with all error details
+                throw createValidationErrors(errors.map(e => ({
+                    field: e.property,
+                    value: e.value,
+                    constraint: Object.keys(e.constraints || {})[0] || 'unknown',
+                    message: Object.values(e.constraints || {})[0] || 'Validation failed',
+                    context: e.constraints
+                })), options.errorSeparator || '; ');
+            }
+            else {
+                // Default behavior (backward compatible): return only first error
+                throw new Error(Object.values(errors[0].constraints)[0]);
+            }
         }
         return obj;
     }
@@ -1135,24 +1353,24 @@ const FunctionValidator = {
 };
 
 /**
- * 装饰器工厂 - 消除装饰器代码重复
+ * Decorator Factory - Eliminate decorator code duplication
  * @author richen
  */
 /**
- * 创建验证装饰器的工厂函数
- * @param options 装饰器配置选项
- * @returns 装饰器工厂函数
+ * Factory function to create validation decorators
+ * @param options Decorator configuration options
+ * @returns Decorator factory function
  */
 function createValidationDecorator(options) {
     const { name, validator, defaultMessage, requiresValue = false } = options;
     return function decoratorFactory(...args) {
-        // 处理参数：最后一个参数是ValidationOptions，前面是验证函数的参数
+        // Handle parameters: last parameter is ValidationOptions, previous ones are validator function parameters
         const validationOptions = args[args.length - 1];
         const validatorArgs = requiresValue ? args.slice(0, -1) : [];
         return function propertyDecorator(object, propertyName) {
-            // 设置属性为可导出
+            // Set property as exportable
             setExpose(object, propertyName);
-            // 注册验证装饰器
+            // Register validation decorator
             classValidator.registerDecorator({
                 name,
                 target: object.constructor,
@@ -1170,8 +1388,9 @@ function createValidationDecorator(options) {
                     },
                     defaultMessage(validationArguments) {
                         const property = validationArguments.property;
-                        return defaultMessage
-                            ? defaultMessage.replace('$property', property)
+                        const customMessage = (validationOptions === null || validationOptions === void 0 ? void 0 : validationOptions.message) || defaultMessage;
+                        return customMessage
+                            ? customMessage.replace('$property', property)
                             : `Invalid value for ${property}`;
                     }
                 }
@@ -1180,11 +1399,11 @@ function createValidationDecorator(options) {
     };
 }
 /**
- * 创建简单验证装饰器（不需要额外参数）
- * @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
  */
 function createSimpleDecorator(name, validator, defaultMessage) {
     return createValidationDecorator({
@@ -1195,11 +1414,11 @@ function createSimpleDecorator(name, validator, defaultMessage) {
     });
 }
 /**
- * 创建带参数的验证装饰器
- * @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
  */
 function createParameterizedDecorator(name, validator, defaultMessage) {
     return createValidationDecorator({
@@ -1211,217 +1430,19 @@ function createParameterizedDecorator(name, validator, defaultMessage) {
 }
 
 /**
- * 改进的错误处理机制
- * @author richen
- */
-/**
- * 错误信息国际化
- */
-const ERROR_MESSAGES = {
-    zh: {
-        // 中国本土化验证
-        IsCnName: '必须是有效的中文姓名',
-        IsIdNumber: '必须是有效的身份证号码',
-        IsZipCode: '必须是有效的邮政编码',
-        IsMobile: '必须是有效的手机号码',
-        IsPlateNumber: '必须是有效的车牌号码',
-        // 基础验证
-        IsNotEmpty: '不能为空',
-        IsDate: '必须是有效的日期',
-        IsEmail: '必须是有效的邮箱地址',
-        IsIP: '必须是有效的IP地址',
-        IsPhoneNumber: '必须是有效的电话号码',
-        IsUrl: '必须是有效的URL地址',
-        IsHash: '必须是有效的哈希值',
-        // 比较验证
-        Equals: '必须等于 {comparison}',
-        NotEquals: '不能等于 {comparison}',
-        Contains: '必须包含 {seed}',
-        IsIn: '必须是以下值之一: {possibleValues}',
-        IsNotIn: '不能是以下值之一: {possibleValues}',
-        Gt: '必须大于 {min}',
-        Gte: '必须大于或等于 {min}',
-        Lt: '必须小于 {max}',
-        Lte: '必须小于或等于 {max}',
-        // 通用错误
-        invalidParameter: '参数 {field} 无效',
-        validationFailed: '验证失败',
-    },
-    en: {
-        // Chinese localization validators
-        IsCnName: 'must be a valid Chinese name',
-        IsIdNumber: 'must be a valid ID number',
-        IsZipCode: 'must be a valid zip code',
-        IsMobile: 'must be a valid mobile number',
-        IsPlateNumber: 'must be a valid plate number',
-        // Basic validators
-        IsNotEmpty: 'should not be empty',
-        IsDate: 'must be a valid date',
-        IsEmail: 'must be a valid email',
-        IsIP: 'must be a valid IP address',
-        IsPhoneNumber: 'must be a valid phone number',
-        IsUrl: 'must be a valid URL',
-        IsHash: 'must be a valid hash',
-        // Comparison validators
-        Equals: 'must equal to {comparison}',
-        NotEquals: 'should not equal to {comparison}',
-        Contains: 'must contain {seed}',
-        IsIn: 'must be one of the following values: {possibleValues}',
-        IsNotIn: 'should not be one of the following values: {possibleValues}',
-        Gt: 'must be greater than {min}',
-        Gte: 'must be greater than or equal to {min}',
-        Lt: 'must be less than {max}',
-        Lte: 'must be less than or equal to {max}',
-        // Common errors
-        invalidParameter: 'invalid parameter {field}',
-        validationFailed: 'validation failed',
-    }
-};
-/**
- * 增强的验证错误类
- */
-class KoattyValidationError extends Error {
-    constructor(errors, message) {
-        const errorMessage = message || 'Validation failed';
-        super(errorMessage);
-        this.name = 'KoattyValidationError';
-        this.errors = errors;
-        this.statusCode = 400;
-        this.timestamp = new Date();
-        // 确保正确的原型链
-        Object.setPrototypeOf(this, KoattyValidationError.prototype);
-    }
-    /**
-     * 获取第一个错误信息
-     */
-    getFirstError() {
-        return this.errors[0];
-    }
-    /**
-     * 获取指定字段的错误
-     */
-    getFieldErrors(field) {
-        return this.errors.filter(error => error.field === field);
-    }
-    /**
-     * 转换为JSON格式
-     */
-    toJSON() {
-        return {
-            name: this.name,
-            message: this.message,
-            statusCode: this.statusCode,
-            timestamp: this.timestamp,
-            errors: this.errors
-        };
-    }
-}
-/**
- * 错误信息格式化器
- */
-class ErrorMessageFormatter {
-    constructor(language = 'zh') {
-        this.language = 'zh';
-        this.language = language;
-    }
-    /**
-     * 设置语言
-     */
-    setLanguage(language) {
-        this.language = language;
-    }
-    /**
-     * 格式化错误消息
-     */
-    formatMessage(constraint, field, value, context) {
-        const messages = ERROR_MESSAGES[this.language];
-        let template = messages[constraint] || messages.invalidParameter;
-        // 替换占位符
-        template = template.replace('{field}', field);
-        // 优先使用上下文中的值，然后是传入的value
-        if (context) {
-            Object.entries(context).forEach(([key, val]) => {
-                template = template.replace(`{${key}}`, this.formatValue(val));
-            });
-        }
-        // 如果还有{value}占位符且传入了value，则替换
-        if (value !== undefined && template.includes('{value}')) {
-            template = template.replace('{value}', this.formatValue(value));
-        }
-        return template;
-    }
-    /**
-     * 格式化值用于消息显示
-     * @private
-     */
-    formatValue(value) {
-        if (value === null)
-            return 'null';
-        if (value === undefined)
-            return 'undefined';
-        if (typeof value === 'number')
-            return String(value);
-        if (typeof value === 'string')
-            return `"${value}"`;
-        if (Array.isArray(value))
-            return `[${value.map(v => this.formatValue(v)).join(', ')}]`;
-        if (typeof value === 'object') {
-            try {
-                return JSON.stringify(value);
-            }
-            catch {
-                // 处理循环引用
-                return '[Circular Reference]';
-            }
-        }
-        return String(value);
-    }
-}
-/**
- * 全局错误信息格式化器实例
- */
-const errorFormatter = new ErrorMessageFormatter();
-/**
- * 设置全局语言
- */
-function setValidationLanguage(language) {
-    errorFormatter.setLanguage(language);
-}
-/**
- * 创建验证错误
- */
-function createValidationError(field, value, constraint, customMessage, context) {
-    const message = customMessage || errorFormatter.formatMessage(constraint, field, value, context);
-    return {
-        field,
-        value,
-        constraint,
-        message,
-        context
-    };
-}
-/**
- * 批量创建验证错误
- */
-function createValidationErrors(errors) {
-    const validationErrors = errors.map(error => createValidationError(error.field, error.value, error.constraint, error.message, error.context));
-    return new KoattyValidationError(validationErrors);
-}
-
-/**
- * 重构后的装饰器定义 - 使用工厂函数消除重复
+ * Refactored decorator definitions - Using factory functions to eliminate duplication
  * @author richen
  */
-// 中国本土化验证装饰器
+// Chinese localization validation decorators
 const IsCnName = createSimpleDecorator('IsCnName', (value) => helper__namespace.isString(value) && cnName(value), 'must be a valid Chinese name');
 const IsIdNumber = createSimpleDecorator('IsIdNumber', (value) => helper__namespace.isString(value) && idNumber(value), 'must be a valid ID number');
 const IsZipCode = createSimpleDecorator('IsZipCode', (value) => helper__namespace.isString(value) && zipCode(value), 'must be a valid zip code');
 const IsMobile = createSimpleDecorator('IsMobile', (value) => helper__namespace.isString(value) && mobile(value), 'must be a valid mobile number');
 const IsPlateNumber = createSimpleDecorator('IsPlateNumber', (value) => helper__namespace.isString(value) && plateNumber(value), 'must be a valid plate number');
-// 基础验证装饰器
+// Basic validation decorators
 const IsNotEmpty = createSimpleDecorator('IsNotEmpty', (value) => !helper__namespace.isEmpty(value), 'should not be empty');
 const IsDate = createSimpleDecorator('IsDate', (value) => helper__namespace.isDate(value), 'must be a valid date');
-// 带参数的验证装饰器
+// Parameterized validation decorators
 const Equals = createParameterizedDecorator('Equals', (value, comparison) => value === comparison, 'must equal to $constraint1');
 const NotEquals = createParameterizedDecorator('NotEquals', (value, comparison) => value !== comparison, 'should not equal to $constraint1');
 const Contains = createParameterizedDecorator('Contains', (value, seed) => helper__namespace.isString(value) && value.includes(seed), 'must contain $constraint1');
@@ -1434,7 +1455,10 @@ const Lt = createParameterizedDecorator('Lt', (value, max) => helper__namespace.
 const Lte = createParameterizedDecorator('Lte', (value, max) => helper__namespace.toNumber(value) <= max, 'must be less than or equal to $constraint1');
 // 复杂验证装饰器（需要特殊处理）
 function IsEmail(options, validationOptions) {
-    return createParameterizedDecorator('IsEmail', (value) => classValidator.isEmail(value, options), 'must be a valid email')(validationOptions);
+    // Handle case where options is actually ValidationOptions (message only)
+    const actualOptions = (options === null || options === void 0 ? void 0 : options.message) ? {} : options;
+    const actualValidationOptions = (options === null || options === void 0 ? void 0 : options.message) ? options : validationOptions;
+    return createParameterizedDecorator('IsEmail', (value) => classValidator.isEmail(value, actualOptions), 'must be a valid email')(actualValidationOptions);
 }
 function IsIP(version, validationOptions) {
     return createParameterizedDecorator('IsIP', (value) => classValidator.isIP(value, version), 'must be a valid IP address')(validationOptions);
@@ -1448,9 +1472,9 @@ function IsUrl(options, validationOptions) {
 function IsHash(algorithm, validationOptions) {
     return createParameterizedDecorator('IsHash', (value) => classValidator.isHash(value, algorithm), 'must be a valid hash')(validationOptions);
 }
-// 基础工具装饰器（从原始decorator.ts移植）
+// Basic utility decorators (migrated from original decorator.ts)
 /**
- * 标记属性为可导出
+ * Mark property as exportable
  */
 function Expose() {
     return function (object, propertyName) {
@@ -1458,7 +1482,7 @@ function Expose() {
     };
 }
 /**
- * Expose的别名
+ * Alias for Expose
  */
 function IsDefined() {
     return function (object, propertyName) {
@@ -1466,61 +1490,89 @@ function IsDefined() {
     };
 }
 /**
- * 参数验证装饰器
+ * Parameter validation decorator
  */
 function Valid(rule, options) {
     return function (object, propertyName, parameterIndex) {
-        // 这里保持与原始实现一致
+        // Keep consistent with original implementation
         const existingRules = Reflect.getOwnMetadata("validate", object, propertyName) || {};
         existingRules[parameterIndex] = { rule, options };
         Reflect.defineMetadata("validate", existingRules, object, propertyName);
     };
 }
 /**
- * 方法验证装饰器
- * 自动验证方法参数中的 DTO 对象
+ * Synchronous validation function - Executes the actual validation logic
+ * @param args Method parameters
+ * @param paramTypes Parameter type metadata
+ * @returns Validated parameters and validation targets
  */
-function Validated() {
-    return function (object, propertyName, descriptor) {
-        const originalMethod = descriptor.value;
-        descriptor.value = async function (...args) {
-            // 获取参数类型元数据
-            const paramTypes = Reflect.getMetadata('design:paramtypes', object, propertyName) || [];
-            // 验证每个参数
-            for (let i = 0; i < args.length; i++) {
-                const arg = args[i];
-                const paramType = paramTypes[i];
-                // 如果是类类型且不是基础类型，执行验证
-                if (paramType && typeof paramType === 'function' &&
-                    paramType !== String && paramType !== Number &&
-                    paramType !== Boolean && paramType !== Array &&
-                    paramType !== Object && paramType !== Date) {
-                    try {
-                        // 如果参数不是目标类型的实例，转换为实例
-                        let validationTarget = arg;
-                        if (!(arg instanceof paramType)) {
-                            validationTarget = Object.assign(new paramType(), arg);
-                        }
-                        const errors = await classValidator.validate(validationTarget);
-                        if (errors.length > 0) {
-                            throw createValidationErrors(errors.map(e => ({
-                                field: e.property,
-                                value: e.value,
-                                constraint: Object.keys(e.constraints || {})[0] || 'unknown',
-                                message: Object.values(e.constraints || {})[0] || 'Validation failed',
-                                context: e.constraints
-                            })));
-                        }
-                    }
-                    catch (error) {
-                        // 如果验证失败，重新抛出错误
-                        throw error;
-                    }
+async function checkValidated(args, paramTypes) {
+    const validationTargets = [];
+    // Validate each parameter
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const paramType = paramTypes[i];
+        // If it's a class type and not a basic type, perform validation
+        if (paramType && typeof paramType === 'function' &&
+            paramType !== String && paramType !== Number &&
+            paramType !== Boolean && paramType !== Array &&
+            paramType !== Object && paramType !== Date) {
+            try {
+                // If parameter is not an instance of the target type, convert it to an instance
+                let validationTarget = arg;
+                if (!(arg instanceof paramType)) {
+                    validationTarget = Object.assign(new paramType(), arg);
+                }
+                const errors = await classValidator.validate(validationTarget);
+                if (errors.length > 0) {
+                    throw createValidationErrors(errors.map(e => ({
+                        field: e.property,
+                        value: e.value,
+                        constraint: Object.keys(e.constraints || {})[0] || 'unknown',
+                        message: Object.values(e.constraints || {})[0] || 'Validation failed',
+                        context: e.constraints
+                    })));
                 }
+                validationTargets.push(validationTarget);
             }
-            // 执行原始方法
-            return originalMethod.apply(this, args);
-        };
+            catch (error) {
+                // If validation fails, rethrow the error
+                throw error;
+            }
+        }
+        else {
+            validationTargets.push(arg);
+        }
+    }
+    return { validatedArgs: args, validationTargets };
+}
+/**
+ * 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)
+ */
+function Validated(isAsync = true) {
+    return function (target, propertyKey, descriptor) {
+        if (isAsync) {
+            // Async mode: Save metadata, validation will be performed by the framework after async parameter retrieval
+            koatty_container.IOCContainer.savePropertyData(PARAM_CHECK_KEY, {
+                dtoCheck: 1
+            }, target, propertyKey);
+        }
+        else {
+            // Sync mode: Perform validation immediately when the method is called
+            const originalMethod = descriptor.value;
+            descriptor.value = async function (...args) {
+                // Get parameter type metadata
+                const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey) || [];
+                // Execute validation
+                await checkValidated(args, paramTypes);
+                // Execute original method
+                return originalMethod.apply(this, args);
+            };
+        }
         return descriptor;
     };
 }
@@ -1562,6 +1614,7 @@ exports.ValidFuncs = ValidFuncs;
 exports.Validated = Validated;
 exports.cached = cached;
 exports.checkParamsType = checkParamsType;
+exports.checkValidated = checkValidated;
 exports.clearAllCaches = clearAllCaches;
 exports.configureCaches = configureCaches;
 exports.convertDtoParamsType = convertDtoParamsType;