schema-dsl 1.0.8 → 1.1.0

package/CHANGELOG.md

@@ -11,9 +11,9 @@
 
 | 版本               | 日期 | 变更摘要 | 详细 |
 |------------------|------|---------|------|
-| [v1.0.8](#v1071) | 2026-01-04 | 优化：错误消息过滤增强 | [查看详情](#v1071) |
-| [v1.0.7](#v107)  | 2026-01-04 | 修复：dsl.match/dsl.if 嵌套支持 dsl() 包裹 | [查看详情](#v107) |
-| [v1.0.6](#v106)  | 2026-01-04 | 🚨 紧急修复：TypeScript 类型污染 | [查看详情](#v106) |
+| [v1.1.0](#v110)  | 2026-01-05 | 🎉 重大功能：跨类型联合验证 + 插件系统增强 | [查看详情](#v110) |
+| [v1.0.9](#v109)  | 2026-01-04 | 🎉 重大改进：多语言支持完善 + TypeScript 类型完整 | [查看详情](#v109) |
+| [v1.0.8](#v108) | 2026-01-04 | 优化：错误消息过滤增强 | [查看详情](#v108) |
 | [v1.0.7](#v107)  | 2026-01-04 | 修复：dsl.match/dsl.if 嵌套支持 dsl() 包裹 | [查看详情](#v107) |
 | [v1.0.6](#v106)  | 2026-01-04 | 🚨 紧急修复：TypeScript 类型污染 | [查看详情](#v106) |
 | [v1.0.5](#v105)  | 2026-01-04 | 测试覆盖率提升至 97% | [查看详情](#v105) |
@@ -25,6 +25,341 @@
 
 ---
 
+## [v1.1.0] - 2026-01-05
+
+### 🎉 新功能
+
+#### 1. 跨类型联合验证 - `types:` 语法
+
+**一个字段支持多种类型**
+
+现在可以使用 `types:` 前缀定义跨类型联合验证，支持字段匹配多种不同的数据类型。
+
+**基础用法**：
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+// 字段可以是字符串或数字
+const schema = dsl({
+  value: 'types:string|number'
+});
+
+validate(schema, { value: 'hello' });  // ✅ 通过
+validate(schema, { value: 123 });      // ✅ 通过
+validate(schema, { value: true });     // ❌ 失败
+```
+
+**带约束的联合类型**：
+
+```javascript
+const schema = dsl({
+  contact: 'types:email|phone!',         // 邮箱或手机号
+  price: 'types:number:0-|string:1-20',  // 数字价格或"面议"
+  rating: 'types:integer:1-5|string:9'   // 整数1-5或字符串"excellent"
+});
+```
+
+**实际应用场景**：
+
+```javascript
+// 用户注册：灵活的联系方式
+const registerSchema = dsl({
+  username: 'string:3-20!',
+  contact: 'types:email|phone!',  // 支持邮箱或手机号注册
+  age: 'types:integer:1-150|null' // 年龄可选（null表示不填）
+});
+```
+
+**支持的类型**：
+- ✅ 所有内置类型：`string`, `number`, `email`, `url`, `uuid` 等
+- ✅ 插件注册的自定义类型（见下文）
+
+---
+
+#### 2. 插件系统增强 - DSL类型注册
+
+**插件现在可以注册自定义DSL类型**
+
+插件不再局限于注册ajv format/keyword，现在可以注册完整的DSL类型，让自定义类型在DSL语法中直接可用。
+
+**改造前** (v1.0.x)：
+```javascript
+// ❌ 只能注册ajv format（仅验证阶段生效）
+install(schemaDsl, options) {
+  const ajv = validator.getAjv();
+  ajv.addFormat('phone-cn', { validate: /^1[3-9]\d{9}$/ });
+  
+  // ❌ 无法在DSL语法中使用
+  // dsl({ phone: 'phone-cn!' })  // 报错：未知类型
+}
+```
+
+**改造后** (v1.1.0)：
+```javascript
+// ✅ 同时注册DSL类型和ajv format
+install(schemaDsl, options) {
+  const { DslBuilder } = schemaDsl;
+  
+  // ✅ 注册到DSL解析器（解析阶段）
+  DslBuilder.registerType('phone-cn', {
+    type: 'string',
+    pattern: /^1[3-9]\d{9}$/.source,
+    minLength: 11,
+    maxLength: 11
+  });
+  
+  // ✅ 注册到ajv（验证阶段）
+  const ajv = validator.getAjv();
+  ajv.addFormat('phone-cn', { validate: /^1[3-9]\d{9}$/ });
+  
+  // ✅ 现在可以在DSL中直接使用
+  // dsl({ phone: 'phone-cn!' })  // ✅ 成功
+  // dsl({ contact: 'types:email|phone-cn' })  // ✅ 在联合类型中也能用
+}
+```
+
+**新增 API**：
+
+| API | 说明 | 用途 |
+|-----|------|------|
+| `DslBuilder.registerType(name, schema)` | 注册自定义类型 | 插件注册新类型 |
+| `DslBuilder.hasType(type)` | 检查类型是否存在 | 插件验证类型 |
+| `DslBuilder.getCustomTypes()` | 获取所有自定义类型 | 调试和测试 |
+| `DslBuilder.clearCustomTypes()` | 清除自定义类型 | 测试用 |
+
+**插件示例**：
+
+```javascript
+// plugins/custom-format.js (v2.0.0)
+module.exports = {
+  name: 'custom-format',
+  version: '2.0.0',
+  
+  install(schemaDsl, options, context) {
+    const { DslBuilder } = schemaDsl;
+    const ajv = validator.getAjv();
+    
+    // 定义自定义类型
+    const types = {
+      'phone-cn': {
+        pattern: /^1[3-9]\d{9}$/,
+        schema: { type: 'string', pattern: /^1[3-9]\d{9}$/.source, minLength: 11, maxLength: 11 }
+      },
+      'qq': {
+        pattern: /^[1-9][0-9]{4,10}$/,
+        schema: { type: 'string', pattern: /^[1-9][0-9]{4,10}$/.source, minLength: 5, maxLength: 11 }
+      }
+    };
+    
+    // 注册到DSL和ajv
+    Object.keys(types).forEach(name => {
+      const config = types[name];
+      DslBuilder.registerType(name, config.schema);  // DSL解析
+      ajv.addFormat(name, { validate: config.pattern });  // ajv验证
+    });
+  }
+};
+```
+
+---
+
+#### 3. ConditionalBuilder 快捷验证方法
+
+**一行代码完成条件验证**
+
+新增4个快捷验证方法，让条件判断更简洁：
+
+| 方法 | 返回值 | 抛错 | 异步 | 适用场景 |
+|------|--------|------|------|---------|
+| `.validate()` | `{ valid, errors, data }` | ❌ | ❌ | 需要错误详情 |
+| `.validateAsync()` | `Promise<data>` | ✅ | ✅ | async/await、中间件 |
+| `.assert()` | `data` | ✅ | ❌ | 快速失败、断言 |
+| `.check()` | `boolean` | ❌ | ❌ | 只需判断真假 |
+
+**使用示例**：
+
+```javascript
+// 同步验证 - 返回详细结果
+const result = dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .validate({ age: 16 });
+
+// 异步验证 - 失败自动抛错
+await dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .validateAsync({ age: 16 });
+
+// 断言验证 - 同步抛错
+dsl.if(d => d.age < 18).message('未成年').assert(userData);
+
+// 快速判断 - 返回 boolean
+const isValid = dsl.if(d => d.age < 18).message('未成年').check(data);
+```
+
+**优势**：
+- ✅ 从2行代码减少到1行
+- ✅ 支持 async/await
+- ✅ 快速失败模式
+- ✅ 完全向后兼容
+
+**详细文档**：[ConditionalBuilder API](./docs/conditional-api.md)
+
+### Changed
+
+- 📖 优化 README.md，新增"条件验证 - 一行代码搞定"章节
+- 📖 完善 API 文档和使用示例
+- 📖 新增4个方法的 TypeScript 类型定义
+
+### Tests
+
+- ✅ 新增 45个测试用例（总计 807个测试）
+  - `.validate()` 方法: 9个
+  - `.validateAsync()` 方法: 6个
+  - `.assert()` 方法: 6个
+  - `.check()` 方法: 5个
+  - 边界情况: 12个
+  - 特殊场景: 7个
+- ✅ 测试覆盖率 100%（807/807）
+- ✅ 覆盖 null、undefined、空值、NaN、异常处理等所有边界情况
+
+### 向后兼容
+
+✅ **完全向后兼容**，所有现有代码无需修改
+
+---
+
+## [v1.0.9] - 2026-01-04
+
+### 🎉 重大改进
+
+#### 1. 多语言文档完善 ⭐⭐⭐
+
+**优化内容**：
+
+1. ✅ **统一文档描述为"首次加载，运行时切换"**
+   - 修复 `i18n-user-guide.md` 配置示例错误
+   - 更新 `add-custom-locale.md`、`dynamic-locale.md`、`frontend-i18n-guide.md`
+   - 添加完整的配置和使用示例
+   - 添加错误示例对比（运行时单个加载 vs 首次加载）
+
+2. ✅ **添加文档导航**
+   - 在 `i18n.md` 添加多语言文档导航
+   - 帮助用户快速找到所需文档
+
+3. ✅ **性能数据更新**
+   - 更新性能对比数据：**2,879,606 ops/s**（提升3.19倍）
+   - 比 Zod 快 1.58倍
+   - 比 Joi 快 9.61倍
+   - 比 Yup 快 27.07倍
+
+#### 2. 多语言支持完善（v1.0.9 早期）⭐⭐⭐
+
+**问题描述**：
+- TypeScript 类型定义缺少 `options` 参数
+- 多语言切换需要修改全局状态，并发场景不安全
+- 自定义错误消息查找逻辑有问题
+
+**修复内容**：
+
+1. ✅ **TypeScript 类型定义完善**
+   ```typescript
+   // 新增 ValidateOptions 接口
+   interface ValidateOptions {
+     format?: boolean;      // 是否格式化错误
+     locale?: string;       // 动态指定语言（如 'zh-CN', 'en-US'）
+     messages?: ErrorMessages; // 自定义错误消息
+   }
+   
+   // 更新函数签名
+   function validate(
+     schema: JSONSchema | DslBuilder,
+     data: any,
+     options?: ValidateOptions  // ← 新增
+   ): ValidationResult;
+   
+   // 更新 Validator.validate 方法签名
+   validate(
+     schema: JSONSchema | DslBuilder | Function,
+     data: any,
+     options?: ValidateOptions  // ← 新增
+   ): ValidationResult;
+   ```
+
+2. ✅ **参数化语言切换（无需全局状态）**
+   ```javascript
+   // 旧方式（需要修改全局状态）
+   Locale.setLocale('zh-CN');
+   const result = validate(schema, data);
+   
+   // 新方式（参数化，支持并发）
+   const result = validate(schema, data, { locale: 'zh-CN' });
+   ```
+
+3. ✅ **修复自定义错误消息查找逻辑**
+   - **Bug 1**: 优先使用通用模板而非 schema 自定义消息
+   - **Bug 2**: 无法正确处理三种自定义消息格式：
+     - 键引用：`_customMessages.pattern = "pattern.objectId"`
+     - 模板字符串：`_customMessages.min = "{{#label}}必须大于{{#limit}}"`
+     - 最终消息：`_customMessages.pattern = "手机号格式不正确"`
+
+**修复效果**：
+
+```javascript
+// 1. 并发调用不同语言
+const [resultZh, resultEn] = await Promise.all([
+  validate(schema, data, { locale: 'zh-CN' }),
+  validate(schema, data, { locale: 'en-US' })
+]);
+// ✅ 两次调用互不影响
+
+// 2. 自定义消息（键引用）
+const schema = dsl('objectId!');
+const result = validate(schema, 'invalid', { locale: 'zh-CN' });
+// message: "无效的 ObjectId" ✅
+
+// 3. 自定义消息（模板字符串）
+const schema = dsl({
+  age: 'number:18-!'.label('年龄')
+    .messages({ 'min': '{{#label}}必须大于{{#limit}}' })
+});
+const result = validate(schema, { age: 10 });
+// message: "年龄必须大于18" ✅
+
+// 4. 自定义消息（最终消息）
+const schema = dsl({
+  phone: 'string!'.pattern(/^1[3-9]\d{9}$/)
+    .messages({ 'pattern': '手机号格式不正确' })
+});
+const result = validate(schema, { phone: 'invalid' });
+// message: "手机号格式不正确" ✅
+```
+
+**技术细节**：
+- 修改 `index.js` 中的 `validate()` 函数，传递 `options` 参数
+- 修改 `Validator.js` 中的 `validate()` 方法，直接传递 `locale` 到 ErrorFormatter
+- 修改 `ErrorFormatter.js`：
+  - `format()` 方法支持对象参数 `{ locale, messages }`
+  - `formatDetailed()` 方法新增 `customMessages` 参数
+  - 优化自定义消息查找逻辑：优先检查 schema 中的 `_customMessages`
+
+**测试结果**：
+- ✅ 725 个测试全部通过（从 51 个失败修复到 0 个失败）
+- ✅ 完全向后兼容，不破坏现有 API
+
+### Changed (变更)
+
+- 📝 **API**: `validate()` 和 `Validator.validate()` 新增 `options` 参数（向后兼容）
+- 🔧 **内部**: `ErrorFormatter.formatDetailed()` 新增 `customMessages` 参数
+
+### Fixed (修复)
+
+- 🐛 修复 TypeScript 类型定义缺少 `options` 参数
+- 🐛 修复自定义错误消息查找逻辑（优先级问题）
+- 🐛 修复自定义消息无法区分键引用/模板字符串/最终消息
+
+---
+
 ## [v1.0.8] - 2026-01-04
 
 ### Improved (优化)