rxtutils 1.1.2-beta.3 → 1.1.2-beta.4

package/README.md

@@ -17,6 +17,7 @@ pnpm add rxtutils
 - **缓存管理** - 支持内存、localStorage、sessionStorage 和 IndexedDB 多种存储方式
 - **HTTP 请求** - 基于 axios 的请求封装，支持错误处理和缓存
 - **状态管理** - 轻量级的状态管理解决方案，支持 React Hook
+- **数据验证** - 基于装饰器的数据验证系统，支持多种验证规则
 - **TypeScript** - 完整的 TypeScript 类型支持
 
 ## 📚 模块介绍
@@ -198,7 +199,149 @@ const currentUser = userStore.get();
 userStore.set({ name: 'Jane Doe', email: 'jane@example.com', isLoggedIn: true });
 ```
 
-### 4. 状态计算器 (createStoreGetter)
+### 4. 数据验证 (Validator)
+
+基于装饰器的数据验证系统，提供多种验证规则和自定义验证能力。
+
+#### 基本用法
+
+```typescript
+import { BaseValidator, VString, VNumber, VRequired, VEmail, VMinLength } from 'rxtutils';
+
+// 创建验证模型
+class User extends BaseValidator {
+  @VString('用户名必须为字符串')
+  @(VRequired()('用户名不能为空'))
+  name?: string;
+
+  @VNumber('年龄必须为数字')
+  @(VRequired()('年龄不能为空'))
+  age?: number;
+
+  @VEmail('邮箱格式不正确')
+  @(VRequired()('邮箱不能为空'))
+  email?: string;
+
+  @(VMinLength(6)('密码长度不能少于6位'))
+  @(VRequired()('密码不能为空'))
+  password?: string;
+}
+
+// 使用验证
+const user = new User();
+user.name = '张三';
+user.age = 25;
+user.email = 'invalid-email'; // 无效的邮箱格式
+user.password = '123'; // 密码长度不足
+
+// 验证单个字段
+const emailErrors = user.validate('email');
+console.log(emailErrors); // [{ status: false, message: '邮箱格式不正确' }]
+
+// 验证所有字段
+const allErrors = user.validateAll();
+console.log(allErrors); // 返回所有验证错误
+```
+
+#### 内置验证装饰器
+
+```typescript
+// 基本类型验证
+@VString('必须为字符串')
+@VNumber('必须为数字')
+@VBoolean('必须为布尔值')
+@VArray('必须为数组')
+
+// 必填验证
+@(VRequired()('不能为空'))
+
+// 范围验证
+@(VMin(18)('必须大于等于18'))
+@(VMax(100)('必须小于等于100'))
+
+// 长度验证
+@(VMinLength(6)('长度不能少于6位'))
+@(VMaxLength(20)('长度不能超过20位'))
+
+// 格式验证
+@VEmail('邮箱格式不正确')
+@(VPattern(/^1[3-9]\d{9}$/)('手机号格式不正确'))
+```
+
+#### 自定义验证装饰器
+
+```typescript
+import { BaseValidator } from 'rxtutils';
+
+// 创建自定义验证装饰器
+const VCustom = BaseValidator.decoratorCreator(
+  (val) => {
+    // 自定义验证逻辑
+    return typeof val === 'string' && val.startsWith('custom-');
+  }
+);
+
+// 使用自定义验证装饰器
+class Product extends BaseValidator {
+  @VCustom('产品编码必须以 custom- 开头')
+  code?: string;
+}
+```
+
+#### 验证方法
+
+BaseValidator 类提供了两个主要的验证方法：
+
+```typescript
+// 验证单个字段
+validate(itemKey: string, itemAll: boolean = false): { status: boolean; message?: string }[] | null;
+
+// 验证多个或所有字段
+validateAll(itemAll: boolean = false, everyItem: boolean = false, order?: string[]): { status: boolean; message?: string }[] | null;
+```
+
+参数说明：
+
+- `itemKey`: 要验证的字段名
+- `itemAll`: 是否验证该字段的所有规则，为 true 时会验证所有规则，为 false 时遇到第一个失败的规则就停止
+- `everyItem`: 是否验证所有字段，为 true 时会验证所有字段，为 false 时遇到第一个失败的字段就停止
+- `order`: 验证字段的顺序，可以指定验证的字段名数组及其顺序
+
+使用示例：
+
+```typescript
+// 创建验证模型
+class LoginForm extends BaseValidator {
+  @VString('用户名必须为字符串')
+  @(VRequired()('用户名不能为空'))
+  @(VMinLength(3)('用户名长度不能少于3位'))
+  @(VMaxLength(20)('用户名长度不能超过20位'))
+  username?: string;
+
+  @(VRequired()('密码不能为空'))
+  @(VMinLength(6)('密码长度不能少于6位'))
+  password?: string;
+}
+
+const form = new LoginForm();
+form.username = 'ab'; // 长度不足
+form.password = '123456';
+
+// 验证单个字段的所有规则
+const usernameErrors = form.validate('username', true);
+console.log(usernameErrors); 
+// [{ status: false, message: '用户名长度不能少于3位' }]
+
+// 验证所有字段，每个字段遇到第一个错误就停止
+const allErrors = form.validateAll(false, true);
+console.log(allErrors);
+
+// 按指定顺序验证字段，并验证每个字段的所有规则
+const orderedErrors = form.validateAll(true, true, ['password', 'username']);
+console.log(orderedErrors);
+```
+
+### 5. 状态计算器 (createStoreGetter)
 
 为状态存储提供计算属性和派生状态。
 

package/dist/cjs/validator/decorators.cjs

@@ -2,6 +2,24 @@
 
 var validator = require('./validator.cjs');
 
+/**
+ * 验证器装饰器模块
+ * 提供一系列用于数据验证的装饰器，可用于类属性的验证规则定义
+ * 这些装饰器基于 BaseValidator 的 decoratorCreator 方法创建
+ */
+/**
+ * 必填项验证装饰器
+ * 验证值是否存在且不在指定的无效值列表中
+ *
+ * @param noneVals 被视为无效的值数组，默认为 [undefined]
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VRequired()('用户名不能为空'))
+ *   username?: string;
+ * }
+ */
 function VRequired(noneVals) {
     if (noneVals === void 0) { noneVals = [undefined]; }
     return validator.BaseValidator.decoratorCreator(function (val) {
@@ -11,31 +29,91 @@ function VRequired(noneVals) {
         return true;
     });
 }
+/**
+ * 字符串类型验证装饰器
+ * 验证值是否为字符串类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VString('用户名必须为字符串')
+ *   username?: string;
+ * }
+ */
 var VString = validator.BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'string') {
         return false;
     }
     return true;
 });
+/**
+ * 数字类型验证装饰器
+ * 验证值是否为数字类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VNumber('年龄必须为数字')
+ *   age?: number;
+ * }
+ */
 var VNumber = validator.BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'number') {
         return false;
     }
     return true;
 });
+/**
+ * 数组类型验证装饰器
+ * 验证值是否为数组类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VArray('标签必须为数组')
+ *   tags?: string[];
+ * }
+ */
 var VArray = validator.BaseValidator.decoratorCreator(function (val) {
     if (!Array.isArray(val)) {
         return false;
     }
     return true;
 });
-// 常用校验装饰器
+/**
+ * 布尔类型验证装饰器
+ * 验证值是否为布尔类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VBoolean('状态必须为布尔值')
+ *   active?: boolean;
+ * }
+ */
 var VBoolean = validator.BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'boolean') {
         return false;
     }
     return true;
 });
+/**
+ * 最小值验证装饰器
+ * 验证数字是否大于或等于指定的最小值
+ *
+ * @param min 最小值
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMin(18)('年龄必须大于或等于18岁'))
+ *   age?: number;
+ * }
+ */
 var VMin = function (min) {
     return validator.BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'number' || val < min) {
@@ -44,6 +122,19 @@ var VMin = function (min) {
         return true;
     });
 };
+/**
+ * 最大值验证装饰器
+ * 验证数字是否小于或等于指定的最大值
+ *
+ * @param max 最大值
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMax(120)('年龄必须小于或等于120岁'))
+ *   age?: number;
+ * }
+ */
 var VMax = function (max) {
     return validator.BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'number' || val > max) {
@@ -52,6 +143,19 @@ var VMax = function (max) {
         return true;
     });
 };
+/**
+ * 最小长度验证装饰器
+ * 验证字符串或数组的长度是否大于或等于指定的最小长度
+ *
+ * @param minLen 最小长度
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMinLength(6)('密码长度不能少于6位'))
+ *   password?: string;
+ * }
+ */
 var VMinLength = function (minLen) {
     return validator.BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'string' && !Array.isArray(val)) {
@@ -63,6 +167,19 @@ var VMinLength = function (minLen) {
         return true;
     });
 };
+/**
+ * 最大长度验证装饰器
+ * 验证字符串或数组的长度是否小于或等于指定的最大长度
+ *
+ * @param maxLen 最大长度
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMaxLength(20)('用户名长度不能超过20位'))
+ *   username?: string;
+ * }
+ */
 var VMaxLength = function (maxLen) {
     return validator.BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'string' && !Array.isArray(val)) {
@@ -74,6 +191,18 @@ var VMaxLength = function (maxLen) {
         return true;
     });
 };
+/**
+ * 邮箱格式验证装饰器
+ * 验证字符串是否符合邮箱格式
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VEmail('邮箱格式不正确')
+ *   email?: string;
+ * }
+ */
 var VEmail = validator.BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'string') {
         return false;
@@ -82,6 +211,19 @@ var VEmail = validator.BaseValidator.decoratorCreator(function (val) {
     var emailReg = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
     return emailReg.test(val);
 });
+/**
+ * 正则表达式验证装饰器
+ * 验证字符串是否匹配指定的正则表达式模式
+ *
+ * @param pattern 正则表达式
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VPattern(/^1[3-9]\d{9}$/)('手机号格式不正确'))
+ *   phone?: string;
+ * }
+ */
 var VPattern = function (pattern) {
     return validator.BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'string') {

package/dist/cjs/validator/validator.cjs

@@ -2,12 +2,27 @@
 
 var tslib = require('tslib');
 
+/**
+ * 基础验证器类
+ * 提供字段验证功能，可通过装饰器为类属性添加验证规则
+ */
 var BaseValidator = /** @class */ (function () {
+    /**
+     * 构造函数
+     * 初始化验证器映射存储
+     */
     function BaseValidator() {
+        /** 用于存储验证器映射的私有符号 */
         this.__keySymbol = Symbol('key-description');
         this.__keySymbol = Symbol('key-description');
         this[this.__keySymbol] = {};
     }
+    /**
+     * 验证单个字段
+     * @param itemKey 要验证的字段名
+     * @param itemAll 是否验证所有规则，为true时会验证该字段的所有规则，为false时遇到第一个失败的规则就停止
+     * @returns 验证错误数组，如果没有错误则返回null
+     */
     BaseValidator.prototype.validate = function (itemKey, itemAll) {
         if (itemAll === void 0) { itemAll = false; }
         var validatorMap = this[this.__keySymbol];
@@ -31,6 +46,13 @@ var BaseValidator = /** @class */ (function () {
         }
         return null;
     };
+    /**
+     * 验证多个或所有字段
+     * @param itemAll 是否验证每个字段的所有规则，为true时会验证字段的所有规则，为false时遇到第一个失败的规则就停止
+     * @param everyItem 是否验证所有字段，为true时会验证所有字段，为false时遇到第一个失败的字段就停止
+     * @param order 验证字段的顺序，可以指定验证的字段名数组及其顺序
+     * @returns 验证错误数组，如果没有错误则返回null
+     */
     BaseValidator.prototype.validateAll = function (itemAll, everyItem, order) {
         if (itemAll === void 0) { itemAll = false; }
         if (everyItem === void 0) { everyItem = false; }
@@ -61,6 +83,39 @@ var BaseValidator = /** @class */ (function () {
         }
         return null;
     };
+    /**
+     * 装饰器创建器
+     * 用于创建属性验证装饰器的工厂函数
+     *
+     * @param func 验证函数，接收属性值并返回布尔值表示验证结果
+     * @returns 返回一个接收错误消息的函数，该函数再返回实际的装饰器
+     *
+     * @example
+     * // 创建一个验证字符串的装饰器
+     * const VString = BaseValidator.decoratorCreator(
+     *   (val) => typeof val === 'string' || val === undefined
+     * );
+     *
+     * // 创建一个验证必填项的装饰器
+     * const VRequired = BaseValidator.decoratorCreator(
+     *   (val) => val !== undefined && val !== null && val !== ''
+     * );
+     *
+     * // 在类中使用这些装饰器
+     * class User extends BaseValidator {
+     *   @VString('名称必须为字符串')
+     *   @(VRequired()('名称必须填写'))
+     *   name?: string;
+     *
+     *   // 验证使用
+     *   validateName() {
+     *     return this.validate('name');
+     *   }
+     * }
+     *
+     * const user = new User();
+     * console.log(user.validateName()); // 显示错误信息：名称必须填写
+     */
     BaseValidator.decoratorCreator = function (func) {
         return function (message) {
             if (message === void 0) { message = function (val, value, context) { return "".concat(String(context.name), "\u683C\u5F0F\u9519\u8BEF"); }; }

package/dist/es/validator/decorators.mjs

@@ -1,5 +1,23 @@
 import { BaseValidator } from './validator.mjs';
 
+/**
+ * 验证器装饰器模块
+ * 提供一系列用于数据验证的装饰器，可用于类属性的验证规则定义
+ * 这些装饰器基于 BaseValidator 的 decoratorCreator 方法创建
+ */
+/**
+ * 必填项验证装饰器
+ * 验证值是否存在且不在指定的无效值列表中
+ *
+ * @param noneVals 被视为无效的值数组，默认为 [undefined]
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VRequired()('用户名不能为空'))
+ *   username?: string;
+ * }
+ */
 function VRequired(noneVals) {
     if (noneVals === void 0) { noneVals = [undefined]; }
     return BaseValidator.decoratorCreator(function (val) {
@@ -9,31 +27,91 @@ function VRequired(noneVals) {
         return true;
     });
 }
+/**
+ * 字符串类型验证装饰器
+ * 验证值是否为字符串类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VString('用户名必须为字符串')
+ *   username?: string;
+ * }
+ */
 var VString = BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'string') {
         return false;
     }
     return true;
 });
+/**
+ * 数字类型验证装饰器
+ * 验证值是否为数字类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VNumber('年龄必须为数字')
+ *   age?: number;
+ * }
+ */
 var VNumber = BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'number') {
         return false;
     }
     return true;
 });
+/**
+ * 数组类型验证装饰器
+ * 验证值是否为数组类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VArray('标签必须为数组')
+ *   tags?: string[];
+ * }
+ */
 var VArray = BaseValidator.decoratorCreator(function (val) {
     if (!Array.isArray(val)) {
         return false;
     }
     return true;
 });
-// 常用校验装饰器
+/**
+ * 布尔类型验证装饰器
+ * 验证值是否为布尔类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VBoolean('状态必须为布尔值')
+ *   active?: boolean;
+ * }
+ */
 var VBoolean = BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'boolean') {
         return false;
     }
     return true;
 });
+/**
+ * 最小值验证装饰器
+ * 验证数字是否大于或等于指定的最小值
+ *
+ * @param min 最小值
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMin(18)('年龄必须大于或等于18岁'))
+ *   age?: number;
+ * }
+ */
 var VMin = function (min) {
     return BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'number' || val < min) {
@@ -42,6 +120,19 @@ var VMin = function (min) {
         return true;
     });
 };
+/**
+ * 最大值验证装饰器
+ * 验证数字是否小于或等于指定的最大值
+ *
+ * @param max 最大值
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMax(120)('年龄必须小于或等于120岁'))
+ *   age?: number;
+ * }
+ */
 var VMax = function (max) {
     return BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'number' || val > max) {
@@ -50,6 +141,19 @@ var VMax = function (max) {
         return true;
     });
 };
+/**
+ * 最小长度验证装饰器
+ * 验证字符串或数组的长度是否大于或等于指定的最小长度
+ *
+ * @param minLen 最小长度
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMinLength(6)('密码长度不能少于6位'))
+ *   password?: string;
+ * }
+ */
 var VMinLength = function (minLen) {
     return BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'string' && !Array.isArray(val)) {
@@ -61,6 +165,19 @@ var VMinLength = function (minLen) {
         return true;
     });
 };
+/**
+ * 最大长度验证装饰器
+ * 验证字符串或数组的长度是否小于或等于指定的最大长度
+ *
+ * @param maxLen 最大长度
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMaxLength(20)('用户名长度不能超过20位'))
+ *   username?: string;
+ * }
+ */
 var VMaxLength = function (maxLen) {
     return BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'string' && !Array.isArray(val)) {
@@ -72,6 +189,18 @@ var VMaxLength = function (maxLen) {
         return true;
     });
 };
+/**
+ * 邮箱格式验证装饰器
+ * 验证字符串是否符合邮箱格式
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VEmail('邮箱格式不正确')
+ *   email?: string;
+ * }
+ */
 var VEmail = BaseValidator.decoratorCreator(function (val) {
     if (typeof val !== 'string') {
         return false;
@@ -80,6 +209,19 @@ var VEmail = BaseValidator.decoratorCreator(function (val) {
     var emailReg = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
     return emailReg.test(val);
 });
+/**
+ * 正则表达式验证装饰器
+ * 验证字符串是否匹配指定的正则表达式模式
+ *
+ * @param pattern 正则表达式
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VPattern(/^1[3-9]\d{9}$/)('手机号格式不正确'))
+ *   phone?: string;
+ * }
+ */
 var VPattern = function (pattern) {
     return BaseValidator.decoratorCreator(function (val) {
         if (typeof val !== 'string') {

package/dist/es/validator/validator.mjs

@@ -1,11 +1,26 @@
 import { __spreadArray } from 'tslib';
 
+/**
+ * 基础验证器类
+ * 提供字段验证功能，可通过装饰器为类属性添加验证规则
+ */
 var BaseValidator = /** @class */ (function () {
+    /**
+     * 构造函数
+     * 初始化验证器映射存储
+     */
     function BaseValidator() {
+        /** 用于存储验证器映射的私有符号 */
         this.__keySymbol = Symbol('key-description');
         this.__keySymbol = Symbol('key-description');
         this[this.__keySymbol] = {};
     }
+    /**
+     * 验证单个字段
+     * @param itemKey 要验证的字段名
+     * @param itemAll 是否验证所有规则，为true时会验证该字段的所有规则，为false时遇到第一个失败的规则就停止
+     * @returns 验证错误数组，如果没有错误则返回null
+     */
     BaseValidator.prototype.validate = function (itemKey, itemAll) {
         if (itemAll === void 0) { itemAll = false; }
         var validatorMap = this[this.__keySymbol];
@@ -29,6 +44,13 @@ var BaseValidator = /** @class */ (function () {
         }
         return null;
     };
+    /**
+     * 验证多个或所有字段
+     * @param itemAll 是否验证每个字段的所有规则，为true时会验证字段的所有规则，为false时遇到第一个失败的规则就停止
+     * @param everyItem 是否验证所有字段，为true时会验证所有字段，为false时遇到第一个失败的字段就停止
+     * @param order 验证字段的顺序，可以指定验证的字段名数组及其顺序
+     * @returns 验证错误数组，如果没有错误则返回null
+     */
     BaseValidator.prototype.validateAll = function (itemAll, everyItem, order) {
         if (itemAll === void 0) { itemAll = false; }
         if (everyItem === void 0) { everyItem = false; }
@@ -59,6 +81,39 @@ var BaseValidator = /** @class */ (function () {
         }
         return null;
     };
+    /**
+     * 装饰器创建器
+     * 用于创建属性验证装饰器的工厂函数
+     *
+     * @param func 验证函数，接收属性值并返回布尔值表示验证结果
+     * @returns 返回一个接收错误消息的函数，该函数再返回实际的装饰器
+     *
+     * @example
+     * // 创建一个验证字符串的装饰器
+     * const VString = BaseValidator.decoratorCreator(
+     *   (val) => typeof val === 'string' || val === undefined
+     * );
+     *
+     * // 创建一个验证必填项的装饰器
+     * const VRequired = BaseValidator.decoratorCreator(
+     *   (val) => val !== undefined && val !== null && val !== ''
+     * );
+     *
+     * // 在类中使用这些装饰器
+     * class User extends BaseValidator {
+     *   @VString('名称必须为字符串')
+     *   @(VRequired()('名称必须填写'))
+     *   name?: string;
+     *
+     *   // 验证使用
+     *   validateName() {
+     *     return this.validate('name');
+     *   }
+     * }
+     *
+     * const user = new User();
+     * console.log(user.validateName()); // 显示错误信息：名称必须填写
+     */
     BaseValidator.decoratorCreator = function (func) {
         return function (message) {
             if (message === void 0) { message = function (val, value, context) { return "".concat(String(context.name), "\u683C\u5F0F\u9519\u8BEF"); }; }

package/dist/types/validator/decorators.d.ts

@@ -1,15 +1,159 @@
 import { BaseValidator } from './validator.js';
 
+/**
+ * 验证器装饰器模块
+ * 提供一系列用于数据验证的装饰器，可用于类属性的验证规则定义
+ * 这些装饰器基于 BaseValidator 的 decoratorCreator 方法创建
+ */
+
+/**
+ * 必填项验证装饰器
+ * 验证值是否存在且不在指定的无效值列表中
+ *
+ * @param noneVals 被视为无效的值数组，默认为 [undefined]
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VRequired()('用户名不能为空'))
+ *   username?: string;
+ * }
+ */
 declare function VRequired(noneVals?: any[]): (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 字符串类型验证装饰器
+ * 验证值是否为字符串类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VString('用户名必须为字符串')
+ *   username?: string;
+ * }
+ */
 declare const VString: (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 数字类型验证装饰器
+ * 验证值是否为数字类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VNumber('年龄必须为数字')
+ *   age?: number;
+ * }
+ */
 declare const VNumber: (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 数组类型验证装饰器
+ * 验证值是否为数组类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VArray('标签必须为数组')
+ *   tags?: string[];
+ * }
+ */
 declare const VArray: (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 布尔类型验证装饰器
+ * 验证值是否为布尔类型
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VBoolean('状态必须为布尔值')
+ *   active?: boolean;
+ * }
+ */
 declare const VBoolean: (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 最小值验证装饰器
+ * 验证数字是否大于或等于指定的最小值
+ *
+ * @param min 最小值
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMin(18)('年龄必须大于或等于18岁'))
+ *   age?: number;
+ * }
+ */
 declare const VMin: (min: number) => (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 最大值验证装饰器
+ * 验证数字是否小于或等于指定的最大值
+ *
+ * @param max 最大值
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMax(120)('年龄必须小于或等于120岁'))
+ *   age?: number;
+ * }
+ */
 declare const VMax: (max: number) => (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 最小长度验证装饰器
+ * 验证字符串或数组的长度是否大于或等于指定的最小长度
+ *
+ * @param minLen 最小长度
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMinLength(6)('密码长度不能少于6位'))
+ *   password?: string;
+ * }
+ */
 declare const VMinLength: (minLen: number) => (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 最大长度验证装饰器
+ * 验证字符串或数组的长度是否小于或等于指定的最大长度
+ *
+ * @param maxLen 最大长度
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VMaxLength(20)('用户名长度不能超过20位'))
+ *   username?: string;
+ * }
+ */
 declare const VMaxLength: (maxLen: number) => (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 邮箱格式验证装饰器
+ * 验证字符串是否符合邮箱格式
+ *
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @VEmail('邮箱格式不正确')
+ *   email?: string;
+ * }
+ */
 declare const VEmail: (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
+/**
+ * 正则表达式验证装饰器
+ * 验证字符串是否匹配指定的正则表达式模式
+ *
+ * @param pattern 正则表达式
+ * @returns 装饰器工厂函数，可接收自定义错误消息
+ *
+ * @example
+ * class User extends BaseValidator {
+ *   @(VPattern(/^1[3-9]\d{9}$/)('手机号格式不正确'))
+ *   phone?: string;
+ * }
+ */
 declare const VPattern: (pattern: RegExp) => (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
 
 export { VArray, VBoolean, VEmail, VMax, VMaxLength, VMin, VMinLength, VNumber, VPattern, VRequired, VString };

package/dist/types/validator/validator.d.ts

@@ -1,23 +1,88 @@
+/**
+ * 验证器函数类型，接收任意值并返回验证结果
+ * @param val 需要验证的值
+ * @returns 包含验证状态和可选错误消息的对象
+ */
 type Validator = (val: any) => {
     status: boolean;
     message?: string;
 };
+/**
+ * 验证器映射类型，用于存储字段名到验证器数组的映射
+ */
 type ValidatorMap = {
     [key: string]: Validator[];
 };
+/**
+ * 基础验证器类
+ * 提供字段验证功能，可通过装饰器为类属性添加验证规则
+ */
 declare class BaseValidator {
+    /** 用于存储验证器映射的私有符号 */
     private __keySymbol;
+    /** 用于存储验证器映射的索引签名 */
     [key: symbol]: ValidatorMap;
+    /** 用于存储类属性的索引签名 */
     [key: string]: any;
+    /**
+     * 构造函数
+     * 初始化验证器映射存储
+     */
     constructor();
+    /**
+     * 验证单个字段
+     * @param itemKey 要验证的字段名
+     * @param itemAll 是否验证所有规则，为true时会验证该字段的所有规则，为false时遇到第一个失败的规则就停止
+     * @returns 验证错误数组，如果没有错误则返回null
+     */
     validate(itemKey: string, itemAll?: boolean): {
         status: boolean;
         message?: string;
     }[];
+    /**
+     * 验证多个或所有字段
+     * @param itemAll 是否验证每个字段的所有规则，为true时会验证字段的所有规则，为false时遇到第一个失败的规则就停止
+     * @param everyItem 是否验证所有字段，为true时会验证所有字段，为false时遇到第一个失败的字段就停止
+     * @param order 验证字段的顺序，可以指定验证的字段名数组及其顺序
+     * @returns 验证错误数组，如果没有错误则返回null
+     */
     validateAll(itemAll?: boolean, everyItem?: boolean, order?: string[]): {
         status: boolean;
         message?: string;
     }[];
+    /**
+     * 装饰器创建器
+     * 用于创建属性验证装饰器的工厂函数
+     *
+     * @param func 验证函数，接收属性值并返回布尔值表示验证结果
+     * @returns 返回一个接收错误消息的函数，该函数再返回实际的装饰器
+     *
+     * @example
+     * // 创建一个验证字符串的装饰器
+     * const VString = BaseValidator.decoratorCreator(
+     *   (val) => typeof val === 'string' || val === undefined
+     * );
+     *
+     * // 创建一个验证必填项的装饰器
+     * const VRequired = BaseValidator.decoratorCreator(
+     *   (val) => val !== undefined && val !== null && val !== ''
+     * );
+     *
+     * // 在类中使用这些装饰器
+     * class User extends BaseValidator {
+     *   @VString('名称必须为字符串')
+     *   @(VRequired()('名称必须填写'))
+     *   name?: string;
+     *
+     *   // 验证使用
+     *   validateName() {
+     *     return this.validate('name');
+     *   }
+     * }
+     *
+     * const user = new User();
+     * console.log(user.validateName()); // 显示错误信息：名称必须填写
+     */
     static decoratorCreator: (func: (val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => boolean) => (message?: ((val: any, value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => string) | string) => (value: undefined, context: ClassFieldDecoratorContext<BaseValidator>) => void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rxtutils",
-  "version": "1.1.2-beta.3",
+  "version": "1.1.2-beta.4",
   "type": "module",
   "main": "dist/cjs/index.cjs",
   "module": "dist/es/index.mjs",