rxtutils 1.1.2-beta.3 → 1.1.2-beta.5

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/request/index.cjs

@@ -30,16 +30,17 @@ function createBaseRequest(baseOptions) {
      */
     return function createRequest(requestOptions, createOptions) {
         var _a = tslib.__assign({}, requestOptions), method = _a.method, url = _a.url;
-        var _b = tslib.__assign(tslib.__assign({}, baseOptions), createOptions), baseURL = _b.baseURL, _c = _b.cacheDataKey, cacheDataKey = _c === void 0 ? "".concat(method, ":").concat(baseURL).concat(url) : _c, cacheDataInStorage = _b.cacheDataInStorage, _d = _b.cacheKeyEquals, cacheKeyEquals = _d === void 0 ? defaultEquals : _d, cacheTime = _b.cacheTime, _e = _b.indexDBName, indexDBName = _e === void 0 ? '__apiCacheDatabase__' : _e;
+        var _b = tslib.__assign(tslib.__assign({}, baseOptions), createOptions), baseURL = _b.baseURL, _c = _b.cacheDataKey, cacheDataKey = _c === void 0 ? "".concat(method, ":").concat(baseURL).concat(url) : _c, cacheDataInStorage = _b.cacheDataInStorage, _d = _b.cacheKeyEquals, cacheKeyEquals = _d === void 0 ? defaultEquals : _d, cacheTime = _b.cacheTime, _e = _b.indexDBName, indexDBName = _e === void 0 ? "__apiCacheDatabase__" : _e;
         var cache = new index.default(cacheDataInStorage, cacheDataKey, cacheTime, indexDBName, cacheKeyEquals);
         function request(requestParam, options) {
+            var _this = this;
             var _a = tslib.__assign(tslib.__assign({}, requestOptions), requestParam), method = _a.method, url = _a.url, _b = _a.data, data = _b === void 0 ? {} : _b, _c = _a.params, params = _c === void 0 ? {} : _c;
             var requestDataOrParams = params;
-            if (method.toLowerCase() === 'post') {
+            if (method.toLowerCase() === "post") {
                 requestDataOrParams = data;
             }
             var _d = tslib.__assign(tslib.__assign(tslib.__assign({}, baseOptions), createOptions), options).defaultMessageShower, defaultMessageShower = _d === void 0 ? console.error : _d;
-            var _e = tslib.__assign(tslib.__assign(tslib.__assign({}, baseOptions), createOptions), options), _f = _e.enableCache, enableCache = _f === void 0 ? false : _f, _g = _e.cacheData, cacheData = _g === void 0 ? false : _g, _h = _e.defaultErrorCodeHandler, defaultErrorCodeHandler = _h === void 0 ? defaultHandlers._defaultErrorCodeHandler.bind(null, defaultMessageShower) : _h, _j = _e.defaultHttpErrorCodeHandler, defaultHttpErrorCodeHandler = _j === void 0 ? defaultHandlers._defaultHttpErrorCodeHandler.bind(null, defaultMessageShower) : _j, _k = _e.otherErrorHandler, otherErrorHandler = _k === void 0 ? defaultHandlers._defaultOtherErrorCodeHandler.bind(null, defaultMessageShower) : _k, _l = _e.errorCodePath, errorCodePath = _l === void 0 ? 'code' : _l, _m = _e.cacheTime, cacheTime = _m === void 0 ? 60 : _m, _o = _e.errorCodeMap, errorCodeMap = _o === void 0 ? {} : _o, _p = _e.successCodes, successCodes = _p === void 0 ? ['0', '200'] : _p, _q = _e.httpErrorCodeMap, httpErrorCodeMap = _q === void 0 ? {} : _q, _r = _e.axiosOptions, axiosOptions = _r === void 0 ? {} : _r, _s = _e.throwError, throwError = _s === void 0 ? true : _s;
+            var _e = tslib.__assign(tslib.__assign(tslib.__assign({}, baseOptions), createOptions), options), _f = _e.enableCache, enableCache = _f === void 0 ? false : _f, _g = _e.cacheData, cacheData = _g === void 0 ? false : _g, _h = _e.defaultErrorCodeHandler, defaultErrorCodeHandler = _h === void 0 ? defaultHandlers._defaultErrorCodeHandler.bind(null, defaultMessageShower) : _h, _j = _e.defaultHttpErrorCodeHandler, defaultHttpErrorCodeHandler = _j === void 0 ? defaultHandlers._defaultHttpErrorCodeHandler.bind(null, defaultMessageShower) : _j, _k = _e.otherErrorHandler, otherErrorHandler = _k === void 0 ? defaultHandlers._defaultOtherErrorCodeHandler.bind(null, defaultMessageShower) : _k, _l = _e.errorCodePath, errorCodePath = _l === void 0 ? "code" : _l, _m = _e.cacheTime, cacheTime = _m === void 0 ? 60 : _m, _o = _e.errorCodeMap, errorCodeMap = _o === void 0 ? {} : _o, _p = _e.successCodes, successCodes = _p === void 0 ? ["0", "200"] : _p, _q = _e.httpErrorCodeMap, httpErrorCodeMap = _q === void 0 ? {} : _q, _r = _e.axiosOptions, axiosOptions = _r === void 0 ? {} : _r, _s = _e.throwError, throwError = _s === void 0 ? true : _s;
             if (enableCache) {
                 var cacheItem = cache.getCache(requestDataOrParams);
                 if (cacheItem) {
@@ -48,76 +49,96 @@ function createBaseRequest(baseOptions) {
             }
             return instance
                 .request(tslib.__assign({ method: method, url: url, data: data, params: params }, axiosOptions))
-                .then(function (res) {
-                var errorCode = String(lodash.at(res.data, errorCodePath));
-                if (successCodes.includes(errorCode)) {
-                    if (cacheData) {
-                        cache.setCache(requestDataOrParams, res.data, { cacheTime: cacheTime });
-                    }
-                    return res.data;
-                }
-                var _a = errorCodeMap, _b = errorCode, _c = _a[_b], customHandler = _c === void 0 ? defaultErrorCodeHandler : _c;
-                var err = new error('服务端错误', 'server', res);
-                if (typeof customHandler === 'string') {
-                    defaultMessageShower(customHandler);
-                }
-                else {
-                    var _d = (Object(customHandler(errorCode, res.data, res, tslib.__assign(tslib.__assign({}, requestOptions), requestParam)))), _e = _d.replaceResData, replaceResData = _e === void 0 ? res.data : _e, _f = _d.throwError, handlerThrowError = _f === void 0 ? 'default' : _f;
-                    res.data = replaceResData;
-                    switch (handlerThrowError) {
-                        case true:
-                            throw err;
-                        case false:
-                            return res.data;
-                    }
-                }
-                if (throwError) {
-                    throw err;
-                }
-                return res.data;
-            }, function (error$1) {
-                if (error$1.response) {
-                    // 请求成功发出且服务器也响应了状态码，但状态代码超出了 2xx 的范围
-                    var resData = error$1;
-                    var _a = httpErrorCodeMap, _b = error$1.response.status, _c = _a[_b], customHandler = _c === void 0 ? defaultHttpErrorCodeHandler : _c;
-                    var err = new error('服务端错误', 'http', error$1);
-                    if (typeof customHandler === 'string') {
-                        defaultMessageShower(customHandler);
-                    }
-                    else {
-                        var _d = (Object(customHandler(error$1.response.status, error$1, tslib.__assign(tslib.__assign({}, requestOptions), requestParam)))), _e = _d.replaceResData, replaceResData = _e === void 0 ? error$1 : _e, _f = _d.throwError, handlerThrowError = _f === void 0 ? 'default' : _f;
-                        resData = replaceResData;
-                        switch (handlerThrowError) {
-                            case true:
+                .then(function (res) { return tslib.__awaiter(_this, void 0, void 0, function () {
+                var errorCode, _a, _b, _c, customHandler, err, _d, _e, replaceResData, _f, handlerThrowError, _g;
+                return tslib.__generator(this, function (_h) {
+                    switch (_h.label) {
+                        case 0:
+                            errorCode = String(lodash.at(res.data, errorCodePath));
+                            if (successCodes.includes(errorCode)) {
+                                if (cacheData) {
+                                    cache.setCache(requestDataOrParams, res.data, { cacheTime: cacheTime });
+                                }
+                                return [2 /*return*/, res.data];
+                            }
+                            _a = errorCodeMap, _b = errorCode, _c = _a[_b], customHandler = _c === void 0 ? defaultErrorCodeHandler : _c;
+                            err = new error("服务端错误", "server", res);
+                            if (!(typeof customHandler === "string")) return [3 /*break*/, 1];
+                            defaultMessageShower(customHandler);
+                            return [3 /*break*/, 3];
+                        case 1:
+                            _g = Object;
+                            return [4 /*yield*/, customHandler(errorCode, res.data, res, tslib.__assign(tslib.__assign({}, requestOptions), requestParam))];
+                        case 2:
+                            _d = (_g.apply(void 0, [(_h.sent())])), _e = _d.replaceResData, replaceResData = _e === void 0 ? res.data : _e, _f = _d.throwError, handlerThrowError = _f === void 0 ? "default" : _f;
+                            res.data = replaceResData;
+                            switch (handlerThrowError) {
+                                case true:
+                                    throw err;
+                                case false:
+                                    return [2 /*return*/, res.data];
+                            }
+                            _h.label = 3;
+                        case 3:
+                            if (throwError) {
                                 throw err;
-                            case false:
-                                return resData;
-                        }
+                            }
+                            return [2 /*return*/, res.data];
                     }
-                    if (throwError) {
-                        throw err;
-                    }
-                    return resData;
-                }
-                else {
-                    var resData = error$1;
-                    var err = new error('服务端错误', 'http', error$1);
-                    err.type = 'http';
-                    err.data = error$1;
-                    var _g = (Object(otherErrorHandler(error$1))), _h = _g.replaceResData, replaceResData = _h === void 0 ? error$1 : _h, _j = _g.throwError, handlerThrowError = _j === void 0 ? 'default' : _j;
-                    resData = replaceResData;
-                    switch (handlerThrowError) {
-                        case true:
-                            throw err;
-                        case false:
-                            return resData;
-                    }
-                    if (throwError) {
-                        throw err;
+                });
+            }); }, function (error$1) { return tslib.__awaiter(_this, void 0, void 0, function () {
+                var resData, _a, _b, _c, customHandler, err, _d, _e, replaceResData, _f, handlerThrowError, _g, resData, err, _h, _j, replaceResData, _k, handlerThrowError, _l;
+                return tslib.__generator(this, function (_m) {
+                    switch (_m.label) {
+                        case 0:
+                            if (!error$1.response) return [3 /*break*/, 4];
+                            resData = error$1;
+                            _a = httpErrorCodeMap, _b = error$1.response.status, _c = _a[_b], customHandler = _c === void 0 ? defaultHttpErrorCodeHandler : _c;
+                            err = new error("服务端错误", "http", error$1);
+                            if (!(typeof customHandler === "string")) return [3 /*break*/, 1];
+                            defaultMessageShower(customHandler);
+                            return [3 /*break*/, 3];
+                        case 1:
+                            _g = Object;
+                            return [4 /*yield*/, customHandler(error$1.response.status, error$1, tslib.__assign(tslib.__assign({}, requestOptions), requestParam))];
+                        case 2:
+                            _d = (_g.apply(void 0, [(_m.sent())])), _e = _d.replaceResData, replaceResData = _e === void 0 ? error$1 : _e, _f = _d.throwError, handlerThrowError = _f === void 0 ? "default" : _f;
+                            resData = replaceResData;
+                            switch (handlerThrowError) {
+                                case true:
+                                    throw err;
+                                case false:
+                                    return [2 /*return*/, resData];
+                            }
+                            _m.label = 3;
+                        case 3:
+                            if (throwError) {
+                                throw err;
+                            }
+                            return [2 /*return*/, resData];
+                        case 4:
+                            resData = error$1;
+                            err = new error("服务端错误", "http", error$1);
+                            err.type = "http";
+                            err.data = error$1;
+                            _l = Object;
+                            return [4 /*yield*/, otherErrorHandler(error$1)];
+                        case 5:
+                            _h = (_l.apply(void 0, [(_m.sent())])), _j = _h.replaceResData, replaceResData = _j === void 0 ? error$1 : _j, _k = _h.throwError, handlerThrowError = _k === void 0 ? "default" : _k;
+                            resData = replaceResData;
+                            switch (handlerThrowError) {
+                                case true:
+                                    throw err;
+                                case false:
+                                    return [2 /*return*/, resData];
+                            }
+                            if (throwError) {
+                                throw err;
+                            }
+                            return [2 /*return*/, resData];
                     }
-                    return resData;
-                }
-            });
+                });
+            }); });
         }
         request.clearCache = function () {
             cache.clear();

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"); }; }