schema-dsl 1.0.9 → 1.1.1

package/CHANGELOG.md

@@ -11,12 +11,12 @@
 
 | 版本               | 日期 | 变更摘要 | 详细 |
 |------------------|------|---------|------|
+| [v1.1.1](#v111)  | 2026-01-06 | 🎉 新功能：ConditionalBuilder 独立消息支持 | [查看详情](#v111) |
+| [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 +26,329 @@
 
 ---
 
+## [v1.1.1] - 2026-01-06
+
+### 🎉 新功能
+
+#### ConditionalBuilder 独立消息支持 - `.and()/.or()` 后可调用 `.message()`
+
+**每个条件都可以有自己的错误消息**
+
+现在支持在 `.and()` 和 `.or()` 后调用 `.message()` 设置独立的错误消息，让错误提示更精确。
+
+**基础用法**：
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// ✅ v1.1.1 新功能：每个条件独立消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+
+// 工作原理：
+// - 第一个条件失败 → 返回 'ACCOUNT_NOT_FOUND'
+// - 第二个条件失败 → 返回 'INSUFFICIENT_TRADABLE_CREDITS'
+// - 所有条件通过 → 验证成功
+```
+
+**特性**：
+- ✅ 支持多个 `.and()` 条件各有独立消息
+- ✅ 支持 `.or()` 条件独立消息
+- ✅ 自动检测启用链式检查模式
+- ✅ 100% 向后兼容，不影响现有代码
+- ✅ 完整的 TypeScript 类型支持
+
+**实际应用示例**：
+
+```javascript
+// 多层验证，每层都有清晰的错误消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.status !== 'active')
+  .message('ACCOUNT_INACTIVE')
+  .and(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+```
+
+**文档链接**：
+- [条件 API 文档](./docs/conditional-api.md)
+- [README FAQ Q7](./README.md#q7-如何合并多个-dslif-验证)
+
+---
+
+#### I18nError 多语言错误抛出机制
+
+**统一的多语言错误抛出**
+
+新增 `I18nError` 类和 `dsl.error` 快捷方法，提供统一的多语言错误抛出机制。
+
+**基础用法**：
+
+```javascript
+const { I18nError, dsl } = require('schema-dsl');
+
+// 方式1：直接抛出
+I18nError.throw('account.notFound');
+// 中文: "账户不存在"
+// 英文: "Account not found"
+
+// 方式2：带参数插值
+I18nError.throw('account.insufficientBalance', {
+  balance: 50,
+  required: 100
+});
+// 输出: "余额不足，当前余额50，需要100"
+
+// 方式3：断言风格（推荐）
+I18nError.assert(account, 'account.notFound');
+I18nError.assert(
+  account.balance >= 100,
+  'account.insufficientBalance',
+  { balance: account.balance, required: 100 }
+);
+
+// 方式4：快捷方法
+dsl.error.throw('user.noPermission');
+dsl.error.assert(user.role === 'admin', 'user.noPermission');
+```
+
+**特性**：
+- ✅ 统一的错误代码格式：`{模块}.{错误类型}`
+- ✅ 自动多语言翻译（支持中英文）
+- ✅ 参数插值支持
+- ✅ Express/Koa 集成（toJSON 方法）
+- ✅ 与 `.message()` 和 `.label()` 使用相同的多语言机制
+
+**内置错误代码**：
+- 通用: `error.notFound`, `error.forbidden`, `error.unauthorized`
+- 账户: `account.notFound`, `account.insufficientBalance`, `account.insufficientCredits`
+- 用户: `user.notFound`, `user.noPermission`, `user.notVerified`
+- 订单: `order.notPaid`, `order.paymentMissing`, `order.addressMissing`
+
+**Express/Koa 集成**：
+
+```javascript
+app.use((error, req, res, next) => {
+  if (error instanceof I18nError) {
+    return res.status(error.statusCode).json(error.toJSON());
+  }
+  next(error);
+});
+```
+
+**文档链接**：
+- [使用示例](./examples/i18n-error.examples.js)
+- [README FAQ Q8](./README.md#q8-如何统一抛出多语言错误v111)
+
+---
+
+### 📝 测试
+
+- **新增**: 52 个测试用例（24个独立消息 + 28个 I18nError）
+- **总计**: 921 个测试全部通过 (100%)
+
+### 📖 文档
+
+- **新增**: docs/conditional-api.md 新增 600+ 行功能说明
+- **新增**: examples/i18n-error.examples.js I18nError 使用示例
+- **更新**: README.md FAQ Q7/Q8 添加新功能说明
+- **更新**: index.d.ts TypeScript 类型注释和示例（I18nError + dsl.error）
+
+---
+
+## [v1.1.0] - 2026-01-05
+
+### 🎉 新功能
+
+#### 1. 跨类型联合验证 - `types:` 语法
+
+**一个字段支持多种类型**
+
+...existing content...
+
+**带约束的联合类型**：
+
+```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
 
 ### 🎉 重大改进