koatty_validation 1.6.0 → 1.6.1

package/dist/index.js

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2025-10-23 01:25:03
+* @Date: 2025-10-23 20:54:39
 * @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);
                 }
@@ -1135,24 +1135,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,
@@ -1180,11 +1180,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 +1195,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,21 +1211,21 @@ function createParameterizedDecorator(name, validator, defaultMessage) {
 }
 
 /**
- * 改进的错误处理机制
+ * 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: '必须是有效的邮箱地址',
@@ -1233,7 +1233,7 @@ const ERROR_MESSAGES = {
         IsPhoneNumber: '必须是有效的电话号码',
         IsUrl: '必须是有效的URL地址',
         IsHash: '必须是有效的哈希值',
-        // 比较验证
+        // Comparison validation
         Equals: '必须等于 {comparison}',
         NotEquals: '不能等于 {comparison}',
         Contains: '必须包含 {seed}',
@@ -1243,7 +1243,7 @@ const ERROR_MESSAGES = {
         Gte: '必须大于或等于 {min}',
         Lt: '必须小于 {max}',
         Lte: '必须小于或等于 {max}',
-        // 通用错误
+        // Common errors
         invalidParameter: '参数 {field} 无效',
         validationFailed: '验证失败',
     },
@@ -1278,7 +1278,7 @@ const ERROR_MESSAGES = {
     }
 };
 /**
- * 增强的验证错误类
+ * Enhanced validation error class
  */
 class KoattyValidationError extends Error {
     constructor(errors, message) {
@@ -1288,23 +1288,23 @@ class KoattyValidationError extends Error {
         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);
     }
     /**
-     * 转换为JSON格式
+     * Convert to JSON format
      */
     toJSON() {
         return {
@@ -1317,7 +1317,7 @@ class KoattyValidationError extends Error {
     }
 }
 /**
- * 错误信息格式化器
+ * Error message formatter
  */
 class ErrorMessageFormatter {
     constructor(language = 'zh') {
@@ -1325,33 +1325,33 @@ class ErrorMessageFormatter {
         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);
-        // 优先使用上下文中的值，然后是传入的value
+        // Prioritize values from context, then use passed value
         if (context) {
             Object.entries(context).forEach(([key, val]) => {
                 template = template.replace(`{${key}}`, this.formatValue(val));
             });
         }
-        // 如果还有{value}占位符且传入了value，则替换
+        // 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) {
@@ -1370,7 +1370,7 @@ class ErrorMessageFormatter {
                 return JSON.stringify(value);
             }
             catch {
-                // 处理循环引用
+                // Handle circular references
                 return '[Circular Reference]';
             }
         }
@@ -1378,17 +1378,17 @@ class ErrorMessageFormatter {
     }
 }
 /**
- * 全局错误信息格式化器实例
+ * 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);
@@ -1401,7 +1401,7 @@ function createValidationError(field, value, constraint, customMessage, context)
     };
 }
 /**
- * 批量创建验证错误
+ * Create validation errors in batch
  */
 function createValidationErrors(errors) {
     const validationErrors = errors.map(error => createValidationError(error.field, error.value, error.constraint, error.message, error.context));
@@ -1409,19 +1409,19 @@ function createValidationErrors(errors) {
 }
 
 /**
- * 重构后的装饰器定义 - 使用工厂函数消除重复
+ * 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');
@@ -1448,9 +1448,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 +1458,7 @@ function Expose() {
     };
 }
 /**
- * Expose的别名
+ * Alias for Expose
  */
 function IsDefined() {
     return function (object, propertyName) {
@@ -1466,61 +1466,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 +1590,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;