schema-dsl 1.0.9 → 1.1.0

package/CHANGELOG.md

@@ -11,12 +11,11 @@
 
 | 版本               | 日期 | 变更摘要 | 详细 |
 |------------------|------|---------|------|
+| [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.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) |
 | [v1.0.4](#v104)  | 2025-12-31 | TypeScript 完整支持、validateAsync、ValidationError | [查看详情](#v104) |
 | [v1.0.3](#v103)  | 2025-12-31 | ⚠️ 破坏性变更：单值语法修复 | [查看详情](#v103) |
@@ -26,6 +25,210 @@
 
 ---
 
+## [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
 
 ### 🎉 重大改进

package/README.md

@@ -181,12 +181,49 @@ if (result.valid) {
 |------|-----------|------|
 | **基本验证** | ✅ | string、number、boolean、date、email、url... |
 | **高级验证** | ✅ | 正则、自定义、条件、嵌套、数组... |
+| **🆕 跨类型联合** | ✅ | `types:string|number` 一个字段支持多种类型 (v1.1.0+) |
 | **错误格式化** | ✅ | 自动多语言翻译 |
 | **数据库导出** | ✅ | MongoDB、MySQL、PostgreSQL |
 | **TypeScript** | ✅ | 完整类型定义 |
 | **性能优化** | ✅ | WeakMap 缓存、智能编译 |
+| **插件系统** | ✅ | 支持自定义类型注册 (v1.1.0+) |
 | **文档生成** | ✅ | Markdown、HTML |
 
+### 🆕 v1.1.0 新特性：跨类型联合验证
+
+**一行代码支持多种类型**
+
+```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 });     // ❌ 失败
+
+// 带约束的联合类型
+const advancedSchema = dsl({
+  contact: 'types:email|phone!',  // 邮箱或手机号
+  price: 'types:number:0-|string:1-20'  // 数字价格或"面议"
+});
+```
+
+**实际场景示例**:
+```javascript
+// 用户注册：支持邮箱或手机号
+const registerSchema = dsl({
+  username: 'string:3-20!',
+  contact: 'types:email|phone!',  // 灵活的联系方式
+  age: 'types:integer:1-150|null' // 年龄可选
+});
+```
+
+📖 [完整文档](./docs/union-types.md) | [插件开发指南](./docs/plugin-type-registration.md)
+
 ---
 
 ## 📦 安装
@@ -377,6 +414,146 @@ const registerSchema = SchemaUtils
 // partial - 变为可选（用于更新接口）
 ```
 
+### 条件验证 - 一行代码搞定
+
+**问题场景**：不同情况需要不同的验证规则
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// 场景1：年龄限制 - 未成年不能注册
+// ❌ 传统做法：先验证，再判断，写两次
+const result = validate(schema, userData);
+if (!result.valid) return;
+if (userData.age < 18) {
+  throw new Error('未成年用户不能注册');
+}
+
+// ✅ 新做法：一行代码搞定
+dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .assert(userData);  // 失败自动抛错
+
+// 场景2：权限检查 - 快速判断
+// ❌ 传统做法：写 if 判断
+if (user.role !== 'admin' && user.role !== 'moderator') {
+  return res.status(403).json({ error: '权限不足' });
+}
+
+// ✅ 新做法：一行搞定
+if (!dsl.if(d => d.role === 'admin' || d.role === 'moderator')
+     .message('权限不足')
+     .check(user)) {
+  return res.status(403).json({ error: '权限不足' });
+}
+
+// 场景3：批量过滤 - 筛选符合条件的数据
+// ❌ 传统做法：写 filter 函数
+const adults = users.filter(u => u.age >= 18);
+
+// ✅ 新做法：语义更清晰
+const adults = users.filter(u => 
+  !dsl.if(d => d.age < 18).message('未成年').check(u)
+);
+```
+
+#### 四种方法，满足不同场景
+
+| 方法 | 什么时候用 | 返回什么 | 示例 |
+|------|-----------|---------|------|
+| **`.validate()`** | 需要知道错误详情 | `{ valid, errors, data }` | 表单验证 |
+| **`.validateAsync()`** | async/await 场景 | Promise（失败抛错） | Express 中间件 |
+| **`.assert()`** | 快速失败，不想写 if | 失败直接抛错 | 函数入口检查 |
+| **`.check()`** | 只需要判断真假 | `true/false` | 数据过滤 |
+
+#### 实际例子
+
+**表单验证 - 需要显示错误**
+
+```javascript
+// 使用 .validate() 获取错误详情
+const result = dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .validate(formData);
+
+if (!result.valid) {
+  showError(result.errors[0].message);  // 显示给用户
+}
+```
+
+**Express 中间件 - 异步验证**
+
+```javascript
+// 使用 .validateAsync() 失败自动抛错
+app.post('/register', async (req, res, next) => {
+  try {
+    await dsl.if(d => d.age < 18)
+      .message('未成年用户不能注册')
+      .validateAsync(req.body);
+    
+    // 验证通过，继续处理
+    const user = await createUser(req.body);
+    res.json(user);
+  } catch (error) {
+    next(error);  // 自动传递给错误处理中间件
+  }
+});
+```
+
+**函数参数检查 - 快速断言**
+
+```javascript
+// 使用 .assert() 不满足直接抛错
+function registerUser(userData) {
+  // 入口检查，不满足直接抛错，代码更清晰
+  dsl.if(d => d.age < 18).message('未成年不能注册').assert(userData);
+  dsl.if(d => !d.email).message('邮箱必填').assert(userData);
+  dsl.if(d => !d.phone).message('手机号必填').assert(userData);
+  
+  // 检查通过，继续业务逻辑
+  return createUser(userData);
+}
+```
+
+**批量数据处理 - 快速过滤**
+
+```javascript
+// 使用 .check() 只返回 true/false
+const canRegister = dsl.if(d => d.age < 18)
+  .or(d => d.status === 'blocked')
+  .message('不允许注册');
+
+// 过滤出可以注册的用户
+const validUsers = users.filter(u => !canRegister.check(u));
+
+// 统计未成年用户数量
+const minorCount = users.filter(u => 
+  dsl.if(d => d.age < 18).message('未成年').check(u)
+).length;
+```
+
+**复用验证器**
+
+```javascript
+// 创建一次，到处使用
+const ageValidator = dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册');
+
+// 不同场景使用不同方法
+const r1 = ageValidator.validate({ age: 16 });      // 同步，返回详情
+const r2 = await ageValidator.validateAsync(data);  // 异步，失败抛错
+const r3 = ageValidator.check({ age: 20 });         // 快速判断
+```
+
+#### 💡 选择建议
+
+- 🎯 **表单验证**：用 `.validate()` - 需要显示错误给用户
+- 🚀 **API 接口**：用 `.validateAsync()` - 配合 try/catch
+- ⚡ **函数入口**：用 `.assert()` - 快速失败，代码简洁
+- 🔍 **数据过滤**：用 `.check()` - 只需要判断真假
+
+**完整文档**: [ConditionalBuilder API](./docs/conditional-api.md)
+
 ---
 
 ## 📖 DSL 语法速查
@@ -599,6 +776,86 @@ const vipSchema = dsl({
 validate(vipSchema, { isVip: true, discount: 30 });
 
 // ❌ 非 VIP 用户折扣超过 10
+```
+
+### 🆕 链式条件判断 - dsl.if() (v1.1.0)
+
+**运行时动态条件判断，类似 JavaScript if-else 语句**
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+// 1. 简单条件 + 错误消息
+const schema1 = dsl({
+  age: 'number!',
+  status: dsl.if((data) => data.age >= 18)
+    .message('未成年用户不能注册')  // 不满足自动抛错
+});
+
+validate(schema1, { age: 16, status: 'active' });
+// => { valid: false, errors: [{ message: '未成年用户不能注册' }] }
+
+
+// 2. 条件 + then/else（动态Schema）
+const schema2 = dsl({
+  userType: 'string!',
+  email: dsl.if((data) => data.userType === 'admin')
+    .then('email!')  // 管理员必填
+    .else('email')   // 普通用户可选
+});
+
+
+// 3. 多条件 AND
+const schema3 = dsl({
+  age: 'number!',
+  userType: 'string!',
+  email: dsl.if((data) => data.age >= 18)
+    .and((data) => data.userType === 'admin')
+    .then('email!')
+    .else('email')
+});
+
+
+// 4. 多条件 OR
+const schema4 = dsl({
+  age: 'number!',
+  status: 'string!',
+  reason: dsl.if((data) => data.age < 18)
+    .or((data) => data.status === 'blocked')
+    .message('不允许注册')
+});
+
+
+// 5. elseIf 多分支
+const schema5 = dsl({
+  userType: 'string!',
+  permissions: dsl.if((data) => data.userType === 'admin')
+    .then('array<string>!')
+    .elseIf((data) => data.userType === 'vip')
+    .then('array<string>')
+    .else(null)  // 游客不验证
+});
+
+
+// 6. else 可选（不写 else 就不验证）
+const schema6 = dsl({
+  userType: 'string!',
+  vipLevel: dsl.if((data) => data.userType === 'vip')
+    .then('enum:gold|silver|bronze!')
+    // 不写 else，非 vip 用户不验证
+});
+```
+
+**核心特性**:
+- ✅ **运行时执行** - 在验证时根据实际数据判断（不是Schema定义时）
+- ✅ **多条件组合** - 支持 and/or 逻辑组合
+- ✅ **elseIf 分支** - 支持多层条件判断
+- ✅ **else 可选** - 不写 else 就不验证
+- ✅ **简化设计** - message 自动抛错，无需 throwError()
+
+📖 [完整链式条件判断文档](./docs/conditional-api.md)
+
+---
 validate(vipSchema, { isVip: false, discount: 15 });
 
 

package/docs/FEATURE-INDEX.md

@@ -514,6 +514,6 @@ const schema = {
 ---
 
 **最后更新**: 2025-12-29
-**维护者**: SchemaIO Team
+**维护者**: SchemaI-DSL Team
 
 

package/docs/best-practices.md

@@ -79,7 +79,7 @@ const schema = dsl({
 
 ### 3. 使用预设验证器
 
-SchemaIO 提供了常用的预设验证器，开箱即用：
+SchemaI-DSL 提供了常用的预设验证器，开箱即用：
 
 ```javascript
 const schema = dsl({
@@ -639,7 +639,7 @@ setInterval(() => {
 
 ## 性能基准参考
 
-基于 SchemaIO 的性能测试：
+基于 SchemaI-DSL 的性能测试：
 
 | 操作 | 性能指标 |
 |------|---------|
@@ -655,7 +655,7 @@ setInterval(() => {
 
 ## 总结
 
-遵循这些最佳实践，你的 SchemaIO 代码将具备：
+遵循这些最佳实践，你的 SchemaI-DSL 代码将具备：
 
 ✅ **高性能** - 通过预编译和缓存  
 ✅ **高安全性** - 避免常见安全陷阱  

package/docs/cache-manager.md

@@ -19,7 +19,7 @@
 
 ## 概述
 
-`CacheManager` 是 SchemaIO 的内部缓存系统，用于缓存编译后的 Schema 验证函数，避免重复编译带来的性能开销。
+`CacheManager` 是 SchemaI-DSL 的内部缓存系统，用于缓存编译后的 Schema 验证函数，避免重复编译带来的性能开销。
 
 ### 核心功能