schema-dsl 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -11,6 +11,8 @@
 
 | 版本               | 日期 | 变更摘要 | 详细 |
 |------------------|------|---------|------|
+| [v1.1.2](#v112)  | 2026-01-06 | 🎉 新功能：数字比较运算符 + Bug修复 | [查看详情](#v112) |
+| [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) |
@@ -25,31 +27,322 @@
 
 ---
 
-## [v1.1.0] - 2026-01-05
+## [v1.1.2] - 2026-01-06
 
 ### 🎉 新功能
 
-#### 1. 跨类型联合验证 - `types:` 语法
+#### 数字比较运算符 - 更直观的数值验证
 
-**一个字段支持多种类型**
+**新增 5 种比较运算符，让数值验证更语义化**
 
-现在可以使用 `types:` 前缀定义跨类型联合验证，支持字段匹配多种不同的数据类型。
+现在 `number` 和 `integer` 类型支持 5 种比较运算符：`>`, `>=`, `<`, `<=`, `=`
 
 **基础用法**：
 
 ```javascript
 const { dsl, validate } = require('schema-dsl');
 
-// 字段可以是字符串或数字
+// ✅ 大于（不包括边界）
+const schema1 = dsl({ value: 'number:>0' });
+validate(schema1, { value: 1 });   // ✅ true
+validate(schema1, { value: 0 });   // ❌ false (0不满足>0)
+
+// ✅ 大于等于
+const schema2 = dsl({ age: 'number:>=18' });
+validate(schema2, { age: 18 });    // ✅ true (包括18)
+validate(schema2, { age: 17 });    // ❌ false
+
+// ✅ 小于（不包括边界）
+const schema3 = dsl({ temp: 'number:<100' });
+validate(schema3, { temp: 99.9 }); // ✅ true
+validate(schema3, { temp: 100 });  // ❌ false (100不满足<100)
+
+// ✅ 小于等于
+const schema4 = dsl({ score: 'number:<=100' });
+validate(schema4, { score: 100 }); // ✅ true (包括100)
+
+// ✅ 等于
+const schema5 = dsl({ level: 'number:=5' });
+validate(schema5, { level: 5 });   // ✅ true
+validate(schema5, { level: 4 });   // ❌ false
+```
+
+**支持小数和负数**：
+
+```javascript
+// 小数
+dsl({ value: 'number:>0.5' })      // 大于0.5
+dsl({ price: 'number:<=99.99' })   // 小于等于99.99
+
+// 负数
+dsl({ value: 'number:>-10' })      // 大于-10
+dsl({ temp: 'number:<-5' })        // 小于-5
+
+// 配合必填标记
+dsl({ age: 'number:>=18!' })       // 必填且大于等于18
+dsl({ price: 'number:>0!' })       // 必填且大于0
+```
+
+**对比：比较运算符 vs 范围语法**：
+
+| 需求 | 范围语法 | 比较运算符 | 推荐 |
+|------|---------|-----------|------|
+| x ≥ 18 | `number:18-` | `number:>=18` | **比较运算符**（更清晰） |
+| x > 0（不包括0） | ❌ 无法表达 | `number:>0` | **比较运算符**（唯一方法） |
+| x < 100（不包括100） | ❌ 无法表达 | `number:<100` | **比较运算符**（唯一方法） |
+| x = 100 | `number:100`（实际≤100） | `number:=100` | **比较运算符**（精确匹配） |
+
+**实际应用场景**：
+
+```javascript
+// 场景1：用户注册 - 年龄限制
+const schema = dsl({
+  username: 'string:3-32!',
+  email: 'email!',
+  age: 'number:>=18!',  // 必须年满18岁
+  password: 'string:8-!'
+});
+
+// 场景2：电商系统 - 价格验证
+const schema = dsl({
+  productName: 'string:1-100!',
+  price: 'number:>0!',      // 价格必须大于0
+  discount: 'number:0-100'  // 折扣 0-100
+});
+
+// 场景3：温度监控
 const schema = dsl({
-  value: 'types:string|number'
+  deviceId: 'string!',
+  temperature: 'number:>0',   // 温度 > 0
+  humidity: 'number:<=100'    // 湿度 ≤ 100
+});
+```
+
+**JSON Schema 映射**：
+
+```javascript
+'number:>0'    → { exclusiveMinimum: 0 }
+'number:>=18'  → { minimum: 18 }
+'number:<100'  → { exclusiveMaximum: 100 }
+'number:<=100' → { maximum: 100 }
+'number:=100'  → { enum: [100] }
+```
+
+**特性**：
+- ✅ 支持 5 种比较运算符
+- ✅ 支持小数（如 `number:>0.5`）
+- ✅ 支持负数（如 `number:>-10`）
+- ✅ 支持必填标记（如 `number:>=18!`）
+- ✅ 适用于 `number` 和 `integer` 类型
+- ✅ 完全向后兼容原有范围语法
+- ✅ 完整的 TypeScript 类型支持
+
+**文档链接**：
+- [数字比较运算符完整文档](./docs/number-operators.md)
+- [README 语法速查](./README.md#-dsl-语法速查)
+
+---
+
+### 🐛 Bug 修复
+
+#### 修复比较运算符被误解析为枚举的问题
+
+**问题描述**：
+在 v1.1.1 及之前版本，使用 `number:>0` 等语法时会被错误解析为字符串枚举 `enum: ['>0']`，导致验证结果完全相反。
+
+**修复前**：
+```javascript
+const schema = dsl({ value: 'number:>0' });
+validate(schema, { value: -5 }); // ❌ 错误：返回 true（应该false）
+validate(schema, { value: 5 });  // ❌ 错误：返回 false（应该true）
+```
+
+**修复后**：
+```javascript
+const schema = dsl({ value: 'number:>0' });
+validate(schema, { value: -5 }); // ✅ 正确：返回 false
+validate(schema, { value: 5 });  // ✅ 正确：返回 true
+```
+
+**影响范围**：
+- 仅影响使用 `>`, `<`, `>=`, `<=`, `=` 符号的 number 约束
+- 原有范围语法（如 `number:0-100`）不受影响
+- 完全向后兼容
+
+---
+
+### 📚 文档更新
+
+- 新增 [数字比较运算符文档](./docs/number-operators.md)
+- 更新 README.md 添加比较运算符示例
+- 更新 index.d.ts 添加比较运算符类型注释
+- 新增 28 个比较运算符单元测试
+
+---
+
+### 🧪 测试
+
+- **新增测试**：28 个比较运算符测试用例
+- **测试总数**：949 个（921 + 28）
+- **测试覆盖**：100% 通过
+- **测试文件**：`test/unit/number-operators.test.js`
+
+---
+
+### 📊 变更统计
+
+- **新增功能**：1 个（数字比较运算符）
+- **Bug 修复**：1 个（比较运算符误解析）
+- **文档更新**：3 个（README, docs/number-operators.md, index.d.ts）
+- **测试新增**：28 个
+- **代码变更**：2 个文件（lib/core/DslBuilder.js, lib/adapters/DslAdapter.js）
+
+---
+
+## [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 集成**：
 
-validate(schema, { value: 'hello' });  // ✅ 通过
-validate(schema, { value: 123 });      // ✅ 通过
-validate(schema, { value: true });     // ❌ 失败
+```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