schema-dsl 1.0.9 → 1.1.1

package/README.md

@@ -181,12 +181,50 @@ if (result.valid) {
 |------|-----------|------|
 | **基本验证** | ✅ | string、number、boolean、date、email、url... |
 | **高级验证** | ✅ | 正则、自定义、条件、嵌套、数组... |
+| **🆕 跨类型联合** | ✅ | `types:string|number` 一个字段支持多种类型 (v1.1.1) |
 | **错误格式化** | ✅ | 自动多语言翻译 |
+| **🆕 多语言错误** | ✅ | `I18nError` 统一的多语言错误抛出 (v1.1.1) |
 | **数据库导出** | ✅ | MongoDB、MySQL、PostgreSQL |
 | **TypeScript** | ✅ | 完整类型定义 |
 | **性能优化** | ✅ | WeakMap 缓存、智能编译 |
+| **插件系统** | ✅ | 支持自定义类型注册 (v1.1.1) |
 | **文档生成** | ✅ | 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 +415,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 语法速查
@@ -922,241 +1100,293 @@ try {
 
 ---
 
-## 🎯 适用场景
-
-### ✅ 特别适合
+## ❓ 常见问题 FAQ
 
-- 🚀 **快速开发** - API 开发、表单验证，追求开发效率
-- 🌍 **国际化项目** - 需要完整的多语言错误消息支持
-- 🗄️ **全栈开发** - 需要从 Schema 自动生成数据库表结构
-- 📋 **配置驱动** - 验证规则需要从配置文件或数据库动态读取
-- 🏢 **中小型项目** - Node.js + Express/Koa/Egg.js 后端项目
+### Q1: 如何判断数据不能为空？（类似 `if(!data)`）
 
-### 💡 使用场景示例
+**方案1：使用必填标记**（推荐）
+```javascript
+const schema = dsl({
+  username: 'string!',  // 必填，不能为空
+  email: 'email!'
+});
+```
 
-**RESTful API 开发**
+**方案2：使用条件验证 + 抛错**
 ```javascript
-// 统一的验证中间件
-const validateMiddleware = (schema) => {
-  return async (req, res, next) => {
-    try {
-      req.body = await validateAsync(schema, req.body);
-      next();
-    } catch (error) {
-      next(error);
-    }
-  };
-};
+// 验证失败自动抛错
+dsl.if(d => !d)
+  .message('数据不能为空')
+  .assert(data);
+```
 
-app.post('/api/users', 
-  validateMiddleware(createUserSchema), 
-  userController.create
-);
+**方案3：异步验证**
+```javascript
+// Express/Koa 推荐
+await dsl.if(d => !d)
+  .message('数据不能为空')
+  .validateAsync(data);
 ```
 
-**表单验证**
+---
+
+### Q2: 如何判断数据是否是对象？（类似 `typeof data === 'object'`）
+
+**方案1：使用内置 object 类型**（推荐）
 ```javascript
-// 前端也可以使用（支持浏览器）
-const formSchema = dsl({
-  username: 'string:3-32!',
-  email: 'email!',
-  password: 'string:8-32!',
-  confirmPassword: 'string!'
+const schema = dsl({
+  data: 'object!'  // 必须是对象（排除 null 和 array）
 });
 
-const result = validate(formSchema, formData);
-if (!result.valid) {
-  // 显示错误消息
-  showErrors(result.errors);
-}
+validate(schema, { data: { name: 'John' } });  // ✅ 通过
+validate(schema, { data: 'string' });          // ❌ 失败
+validate(schema, { data: [] });                // ❌ 失败
 ```
 
-**动态配置验证**
+**方案2：条件验证 + 抛错**
 ```javascript
-// 从数据库读取验证规则
-const rules = await db.validationRules.find({ formId: 'user-register' });
-
-// 动态构建 Schema
-const dynamicSchema = dsl(
-  rules.reduce((schema, rule) => {
-    schema[rule.field] = rule.dsl;
-    return schema;
-  }, {})
-);
+dsl.if(d => typeof d !== 'object' || d === null || Array.isArray(d))
+  .message('data 必须是一个对象')
+  .assert(data);
+```
+
+**方案3：带结构验证**
+```javascript
+const schema = dsl({
+  data: {
+    name: 'string!',
+    age: 'integer!',
+    email: 'email'
+  }
+});
+
+await validateAsync(schema, input);  // 验证对象结构
 ```
 
 ---
 
-## ⚡ 性能对比
+### Q3: 如何验证嵌套对象？
+
+```javascript
+const schema = dsl({
+  user: {
+    profile: 'object!',  // profile 必须是对象
+    settings: {
+      theme: 'string',
+      notifications: 'object!'  // 嵌套对象验证
+    }
+  }
+});
+```
 
-**测试环境**: Node.js 18, 10,000 次验证
+---
 
-| 库名 | 速度 (ops/sec) | 相对速度 |
-|------|---------------|---------|
-| Ajv | 2,000,000 | 🥇 最快 |
-| Zod | 526,316 | 🥈 很快 |
-| **schema-dsl** | **277,778** | 🥉 **快** |
-| Joi | 97,087 | 中等 |
-| Yup | 60,241 | 较慢 |
+### Q4: 如何在 Express/Koa 中使用？
 
-**结论**:
-- ✅ 比 Joi 快 **2.86倍**
-- ✅ 比 Yup 快 **4.61倍**  
-- ✅ 对 99% 的应用场景足够快（27万+次/秒）
-- ⚠️ 如果需要极致性能（100万+次/秒），推荐使用 Ajv
+```javascript
+app.post('/api/user', async (req, res) => {
+  try {
+    // 1. 验证请求体是对象
+    await dsl.if(d => typeof d !== 'object' || d === null)
+      .message('请求体必须是对象')
+      .validateAsync(req.body);
+    
+    // 2. 验证字段
+    const schema = dsl({
+      username: 'string:3-32!',
+      email: 'email!',
+      password: 'string:8-!'
+    });
+    
+    const validData = await validateAsync(schema, req.body);
+    
+    // 继续处理...
+    res.json({ success: true, data: validData });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+```
 
 ---
 
-## 🆚 与其他库对比
+### Q5: 如何自定义错误消息？
 
-### 选择建议
+```javascript
+const schema = dsl({
+  username: dsl('string:3-32!')
+    .label('用户名')
+    .messages({
+      minLength: '用户名至少需要 {{#limit}} 个字符',
+      required: '用户名不能为空'
+    }),
+  
+  email: dsl('email!')
+    .label('邮箱地址')
+    .messages({
+      format: '请输入有效的邮箱地址',
+      required: '邮箱不能为空'
+    })
+});
+```
 
-| 项目需求 | 推荐方案 | 原因 |
-|---------|---------|------|
-| 快速开发，减少代码量 | **schema-dsl** | 代码量最少，学习成本最低 |
-| TypeScript 强类型推断 | Zod | 最佳的 TypeScript 支持 |
-| 极致性能要求 | Ajv | 性能最强 |
-| 企业级成熟方案 | Joi | 社区最大，经过大规模验证 |
-| 多语言 + 数据库导出 | **schema-dsl** | 独家功能 |
+---
 
-### 详细对比
+### Q6: 类型对照表
 
-<table>
-<tr>
-<th>特性</th>
-<th>schema-dsl</th>
-<th>Joi</th>
-<th>Yup</th>
-<th>Zod</th>
-<th>Ajv</th>
-</tr>
-<tr>
-<td><strong>语法简洁度</strong></td>
-<td>⭐⭐⭐⭐⭐<br>一行代码</td>
-<td>⭐⭐<br>链式调用冗长</td>
-<td>⭐⭐<br>链式调用冗长</td>
-<td>⭐⭐⭐<br>相对简洁</td>
-<td>⭐⭐<br>JSON 配置繁琐</td>
-</tr>
-<tr>
-<td><strong>学习成本</strong></td>
-<td>⭐⭐⭐⭐⭐<br>5分钟</td>
-<td>⭐⭐⭐<br>30分钟</td>
-<td>⭐⭐⭐<br>30分钟</td>
-<td>⭐⭐⭐⭐<br>15分钟</td>
-<td>⭐⭐⭐<br>20分钟</td>
-</tr>
-<tr>
-<td><strong>性能（简单验证）</strong></td>
-<td>⭐⭐⭐⭐<br>55.6万/秒</td>
-<td>⭐⭐⭐<br>23.3万/秒</td>
-<td>⭐⭐<br>18.9万/秒</td>
-<td>⭐⭐⭐⭐⭐<br>100万/秒</td>
-<td>⭐⭐⭐⭐⭐<br>250万/秒</td>
-</tr>
-<tr>
-<td><strong>性能（复杂验证）</strong></td>
-<td>⭐⭐⭐⭐⭐<br>62.5万/秒</td>
-<td>⭐⭐⭐<br>12.5万/秒</td>
-<td>⭐⭐<br>5.5万/秒</td>
-<td>⭐⭐⭐⭐<br>38.5万/秒</td>
-<td>⭐⭐⭐⭐⭐<br>250万/秒</td>
-</tr>
-<tr>
-<td><strong>TypeScript 支持</strong></td>
-<td>⭐⭐⭐<br>.d.ts 类型定义</td>
-<td>⭐⭐⭐<br>.d.ts 类型定义</td>
-<td>⭐⭐⭐<br>.d.ts 类型定义</td>
-<td>⭐⭐⭐⭐⭐<br>完美类型推断</td>
-<td>⭐⭐<br>基础支持</td>
-</tr>
-<tr>
-<td><strong>数据库导出</strong></td>
-<td>✅ MongoDB<br>✅ MySQL<br>✅ PostgreSQL</td>
-<td>❌</td>
-<td>❌</td>
-<td>❌</td>
-<td>❌</td>
-</tr>
-<tr>
-<td><strong>多语言支持</strong></td>
-<td>✅ 完整支持<br>可自定义语言包</td>
-<td>⚠️ 基础支持</td>
-<td>⚠️ 基础支持</td>
-<td>⚠️ 基础支持</td>
-<td>⚠️ 基础支持</td>
-</tr>
-<tr>
-<td><strong>文档生成</strong></td>
-<td>✅ Markdown<br>✅ HTML</td>
-<td>❌</td>
-<td>❌</td>
-<td>❌</td>
-<td>❌</td>
-</tr>
-<tr>
-<td><strong>社区规模</strong></td>
-<td>⭐⭐⭐<br>成长中</td>
-<td>⭐⭐⭐⭐⭐<br>最大</td>
-<td>⭐⭐⭐⭐<br>很大</td>
-<td>⭐⭐⭐⭐<br>快速增长</td>
-<td>⭐⭐⭐⭐<br>成熟</td>
-</tr>
-</table>
+| JavaScript 条件 | schema-dsl 写法 |
+|----------------|----------------|
+| `if (!data)` | `'string!'` 或 `.assert(data)` |
+| `if (typeof data === 'object')` | `'object!'` |
+| `if (typeof data === 'string')` | `'string!'` |
+| `if (typeof data === 'number')` | `'number!'` |
+| `if (Array.isArray(data))` | `'array!'` |
+| `if (data === null)` | `'null!'` |
+| `if (data > 0)` | `'number:0-!'` |
+| `if (data.length >= 3)` | `'string:3-!'` |
 
 ---
 
-## 📚 完整文档
+### Q7: 如何合并多个 dsl.if() 验证？
 
-### 核心文档
-- [快速开始](./docs/quick-start.md) - 5分钟上手指南
-- [DSL 语法完整参考](./docs/dsl-syntax.md) - 所有语法详解
-- [API 文档](./docs/api-reference.md) - 完整 API 说明
-- [**TypeScript 使用指南**](./docs/typescript-guide.md) - TypeScript 最佳实践 ⭐
+**原代码（多个独立验证）**：
+```javascript
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .assert(account);
 
-### 功能指南
-- [String 扩展方法](./docs/string-extensions.md) - 链式调用详解
-- [Schema 复用](./docs/schema-utils.md) - omit/pick/extend/partial
-- [异步验证](./docs/validate-async.md) - validateAsync 使用指南
-- [错误处理](./docs/error-handling.md) - ValidationError 详解
-- [多语言支持](./docs/i18n.md) - 国际化配置指南
-- [插件开发](./docs/plugin-system.md) - 自定义插件教程
+dsl.if(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account.tradable_credits);
+```
 
-### 导出功能
-- [MongoDB 导出](./docs/mongodb-exporter.md) - MongoDB Schema 生成
-- [MySQL 导出](./docs/mysql-exporter.md) - MySQL DDL 生成
-- [PostgreSQL 导出](./docs/postgresql-exporter.md) - PostgreSQL DDL 生成
-- [Markdown 导出](./docs/markdown-exporter.md) - API 文档生成
+**✅ 方案1：使用 .and() 链式合并（v1.1.1 推荐）**
+```javascript
+// ✅ 每个条件都有独立的错误消息
+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'
+// - 所有条件通过 → 验证成功
+```
 
-### 集成示例
-- [Express 集成](./examples/express-integration.js)
+**✅ 方案2：使用 .elseIf() 分支验证**
+```javascript
+// ✅ 按优先级检查，找到第一个失败的
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .elseIf(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+```
+
+**✅ 方案3：保持独立验证**（最清晰）
+```javascript
+// ✅ 两个独立的验证器
+dsl.if(d => !d).message('ACCOUNT_NOT_FOUND').assert(account);
+dsl.if(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account.tradable_credits);
+```
+
+**⚠️ 注意事项**：
+- `.and()` 用于组合多个条件，每个条件可以有**独立的** `.message()` (v1.1.1)
+- 如果 `.and()` 后不调用 `.message()`，则使用前一个条件的消息
+- `.elseIf()` 按顺序检查，找到第一个失败的就停止（if-else-if 逻辑）
+
+**何时使用**：
+- ✅ 使用 `.and()` - 多个条件，每个有不同错误消息（v1.1.1）
+- ✅ 使用 `.elseIf()` - 不同分支有不同验证规则
+- ✅ 独立验证 - 最清晰，最可靠
+
+**实际应用示例**：
+```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);
+
+// 每个失败条件都有清晰的错误消息！
+```
+
+📖 更多示例请查看 [完整文档](./docs/INDEX.md)
 
 ---
 
-## 💻 示例代码
+### Q8: 如何统一抛出多语言错误？(v1.1.1+)
 
-项目包含 30+ 完整示例，涵盖所有功能：
+**问题**: 业务代码中抛出的错误无法多语言，与 `.message()` 和 `.label()` 不一致
 
-```bash
-# 安装依赖（首次运行）
-npm install
+**✅ 解决方案：使用 `I18nError` 或 `dsl.error`**
 
-# 查看所有示例
-ls examples/
+```javascript
+const { I18nError, dsl } = require('schema-dsl');
 
-# 运行基础示例
-node examples/simple-example.js
+// 方式1：直接抛出
+I18nError.throw('account.notFound');
+// 中文: "账户不存在"
+// 英文: "Account not found"
 
-# 运行数据库导出示例
-node examples/export-demo.js
+// 方式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 }
+);
 
-# 运行 Express 集成示例
-node examples/express-integration.js
+// 方式4：快捷方法
+dsl.error.throw('user.noPermission');
+dsl.error.assert(user.role === 'admin', 'user.noPermission');
+```
+
+**Express/Koa 集成**:
+```javascript
+// 错误处理中间件
+app.use((error, req, res, next) => {
+  if (error instanceof I18nError) {
+    return res.status(error.statusCode).json(error.toJSON());
+  }
+  next(error);
+});
 
-# 🆕 v1.0.3 新增：运行 slug 类型示例
-node examples/slug.examples.js
+// 业务代码中使用
+app.post('/withdraw', (req, res) => {
+  const account = getAccount(req.user.id);
+  I18nError.assert(account, 'account.notFound');
+  I18nError.assert(
+    account.balance >= req.body.amount,
+    'account.insufficientBalance',
+    { balance: account.balance, required: req.body.amount }
+  );
+  // ...
+});
 ```
 
+**内置错误代码**:
+- 通用: `error.notFound`, `error.forbidden`, `error.unauthorized`
+- 账户: `account.notFound`, `account.insufficientBalance`
+- 用户: `user.notFound`, `user.noPermission`
+- 订单: `order.notPaid`, `order.paymentMissing`
+
+📖 完整文档请查看 [examples/i18n-error.examples.js](./examples/i18n-error.examples.js)
+
 ---
 
 ## 🤝 贡献指南