schema-dsl 1.0.8 → 1.1.0

package/docs/typescript-guide.md

@@ -479,12 +479,11 @@ const schema = dsl({
 const schema = dsl({
   userType: dsl('string!').label('用户类型'),
   
-  companyName: dsl('string')
-    .when('userType', {
-      is: 'company',
-      then: dsl('string!').label('公司名称'),  // 企业用户必填
-      otherwise: dsl('string').label('公司名称')  // 个人用户可选
-    })
+  // 使用 dsl.match() 根据 userType 字段动态验证
+  companyName: dsl.match('userType', {
+    'company': 'string!',  // 企业用户必填
+    '_default': 'string'   // 个人用户可选
+  })
 });
 ```
 

package/docs/union-type-guide.md

@@ -0,0 +1,147 @@
+# 一个字段支持多种类型
+
+> 使用 `.pattern()` 方法匹配多种格式
+
+---
+
+## 基本用法
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+// 邮箱 或 手机号
+const schema = dsl({
+  contact: dsl('string!')
+    .pattern(/^([^\s@]+@[^\s@]+\.[^\s@]+|1[3-9]\d{9})$/)
+    .messages({ pattern: '必须是邮箱或手机号' })
+});
+
+validate(schema, { contact: 'test@example.com' });  // ✅
+validate(schema, { contact: '13800138000' });       // ✅
+validate(schema, { contact: 'invalid' });           // ❌
+```
+
+**说明**：
+- 正则中使用 `|` 表示"或"，括号 `()` 分组
+- 使用 `.messages()` 设置错误消息，支持多语言
+
+---
+
+## 常用示例
+
+### 用户登录（用户名或邮箱）
+
+```javascript
+const loginSchema = dsl({
+  username: dsl('string:3-32!')
+    .pattern(/^([^\s@]+@[^\s@]+\.[^\s@]+|[a-zA-Z0-9_]+)$/)
+    .messages({ pattern: '必须是邮箱或用户名' }),
+  password: 'string:8-32!'
+});
+```
+
+### 联系方式（邮箱或手机号）
+
+```javascript
+const schema = dsl({
+  contact: dsl('string!')
+    .pattern(/^([^\s@]+@[^\s@]+\.[^\s@]+|1[3-9]\d{9})$/)
+    .messages({ pattern: '必须是邮箱或手机号' })
+});
+```
+
+### URL（http 或 https）
+
+```javascript
+const schema = dsl({
+  website: dsl('string!')
+    .pattern(/^https?:\/\/.+$/)
+    .messages({ pattern: '必须是 http 或 https 开头的 URL' })
+});
+```
+
+---
+
+## 支持多语言
+
+```javascript
+// 使用多语言 key
+const schema = dsl({
+  contact: dsl('string!')
+    .pattern(/^([^\s@]+@[^\s@]+\.[^\s@]+|1[3-9]\d{9})$/)
+    .messages({ pattern: 'pattern.emailOrPhone' })  // 多语言 key
+});
+
+// 验证时指定语言
+validate(schema, { contact: 'invalid' }, { locale: 'zh-CN' });  // 中文：必须是邮箱或手机号
+validate(schema, { contact: 'invalid' }, { locale: 'en-US' });  // 英文：Must be an email or phone number
+```
+
+**内置多语言 key**：
+- `pattern.emailOrPhone` - 邮箱或手机号
+- `pattern.usernameOrEmail` - 用户名或邮箱
+- `pattern.httpOrHttps` - http 或 https URL
+
+---
+
+## 正则表达式速查
+
+```javascript
+// 邮箱 或 手机号
+/^([^\s@]+@[^\s@]+\.[^\s@]+|1[3-9]\d{9})$/
+
+// http 或 https
+/^https?:\/\/.+$/
+
+// 用户名 或 邮箱
+/^([^\s@]+@[^\s@]+\.[^\s@]+|[a-zA-Z0-9_]{3,32})$/
+
+// 数字ID 或 UUID
+/^(\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i
+
+// 多个邮箱域名
+/^[^\s@]+@(gmail\.com|qq\.com|163\.com)$/
+
+// 中国或美国手机号
+/^(1[3-9]\d{9}|\+1\d{10})$/
+```
+
+---
+
+
+## 完整示例
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+const registerSchema = dsl({
+  name: 'string:1-50!',
+  contact: dsl('string!')
+    .pattern(/^([^\s@]+@[^\s@]+\.[^\s@]+|1[3-9]\d{9})$/)
+    .messages({ pattern: '必须是邮箱或手机号' })
+});
+
+const testData = [
+  { name: '张三', contact: 'zhangsan@example.com' },
+  { name: '李四', contact: '13800138000' },
+  { name: '王五', contact: 'invalid' }
+];
+
+testData.forEach((data, index) => {
+  const result = validate(registerSchema, data);
+  console.log(`测试${index + 1}:`, result.valid ? '✅' : '❌');
+  if (!result.valid) {
+    console.log('  错误:', result.errors[0].message);
+  }
+});
+```
+
+**输出**：
+```
+测试1: ✅
+测试2: ✅
+测试3: ❌
+  错误: 必须是邮箱或手机号
+```
+
+

package/docs/union-types.md

@@ -0,0 +1,277 @@
+# 跨类型联合验证 - types: 语法
+
+> **版本**: v1.1.0+  
+> **状态**: ✅ 稳定
+
+---
+
+## 概述
+
+`types:` 语法允许您定义跨类型联合验证，支持字段匹配多种不同的数据类型。
+
+### 特性
+
+✅ **简洁语法** - `'types:string|number'` 一行搞定  
+✅ **带约束** - `'types:string:3-10|number:0-100'`  
+✅ **插件扩展** - 支持自定义类型注册  
+✅ **多语言** - 完整的i18n支持
+
+---
+
+## 快速开始
+
+### 基础用法
+
+```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({
+  value: 'types:string:3-10|number:0-100!'
+});
+
+validate(schema, { value: 'abc' });    // ✅ 通过
+validate(schema, { value: 50 });       // ✅ 通过
+validate(schema, { value: 'ab' });     // ❌ 太短
+validate(schema, { value: 101 });      // ❌ 超范围
+```
+
+---
+
+## 语法说明
+
+### 基本格式
+
+```
+types:type1|type2|type3[!]
+```
+
+- `types:` - 固定前缀
+- `type1|type2` - 类型列表，用 `|` 分隔
+- `!` - 可选的必填标记
+
+### 带约束格式
+
+```
+types:type1:constraint1|type2:constraint2
+```
+
+---
+
+## 支持的类型
+
+### 内置类型
+
+所有内置类型都可以在 `types:` 中使用：
+
+- **基本类型**: `string`, `number`, `integer`, `boolean`, `null`, `any`
+- **格式类型**: `email`, `url`, `uuid`, `date`, `datetime`, `time`
+- **特殊类型**: `phone`, `idCard`, `objectId`, `hexColor` 等
+
+### 插件自定义类型
+
+通过插件注册的自定义类型也可以使用：
+
+```javascript
+const { DslBuilder, PluginManager } = require('schema-dsl');
+
+// 注册自定义类型
+DslBuilder.registerType('order-id', {
+  type: 'string',
+  pattern: /^ORD[0-9]{12}$/.source,
+  minLength: 15,
+  maxLength: 15
+});
+
+// 在types:中使用
+const schema = dsl({
+  identifier: 'types:uuid|order-id'
+});
+```
+
+---
+
+## 实际应用场景
+
+### 场景1：用户注册（邮箱或手机号）
+
+```javascript
+const registerSchema = dsl({
+  username: 'string:3-20!',
+  password: 'string:8-20!',
+  contact: 'types:email|phone!'  // 邮箱或手机号
+});
+```
+
+### 场景2：灵活的价格输入
+
+```javascript
+const productSchema = dsl({
+  price: 'types:number:0-|string:1-20'  // 数字价格或"面议"
+});
+
+validate(productSchema, { price: 99.99 });  // ✅ 数字
+validate(productSchema, { price: '面议' });  // ✅ 字符串
+```
+
+### 场景3：订单查询（订单号或SKU）
+
+```javascript
+// 先注册自定义类型
+DslBuilder.registerType('order-id', { ... });
+DslBuilder.registerType('sku', { ... });
+
+const querySchema = dsl({
+  identifier: 'types:order-id|sku!'
+});
+```
+
+---
+
+## 插件开发指南
+
+### 注册自定义类型
+
+```javascript
+// 在插件的install方法中
+install(schemaDsl, options, context) {
+  const { DslBuilder } = schemaDsl;
+
+  // 注册DSL类型
+  DslBuilder.registerType('custom-type', {
+    type: 'string',
+    pattern: /^CUSTOM-\d+$/.source,
+    minLength: 8,
+    maxLength: 20
+  });
+
+  // 同时注册ajv format（可选）
+  const validator = schemaDsl.getDefaultValidator();
+  const ajv = validator.getAjv();
+  ajv.addFormat('custom-type', {
+    validate: /^CUSTOM-\d+$/
+  });
+}
+```
+
+### DslBuilder API
+
+#### `DslBuilder.registerType(name, schema)`
+
+注册自定义类型。
+
+**参数**:
+- `name` (string) - 类型名称
+- `schema` (Object|Function) - JSON Schema对象或生成函数
+
+#### `DslBuilder.hasType(type)`
+
+检查类型是否已注册。
+
+#### `DslBuilder.getCustomTypes()`
+
+获取所有已注册的自定义类型。
+
+#### `DslBuilder.clearCustomTypes()`
+
+清除所有自定义类型（主要用于测试）。
+
+---
+
+## 多语言支持
+
+### 中文
+
+```javascript
+validate(schema, { value: true }, { locale: 'zh-CN' });
+// 错误: "必须匹配以下类型之一"
+```
+
+### 英文
+
+```javascript
+validate(schema, { value: true }, { locale: 'en-US' });
+// Error: "Must match one of the following types"
+```
+
+支持的语言：`zh-CN`, `en-US`, `es-ES`, `fr-FR`, `ja-JP`
+
+---
+
+## 最佳实践
+
+### 1. 优先使用内置类型
+
+```javascript
+// ✅ 推荐
+'types:email|phone'
+
+// ⚠️ 不推荐（性能较差）
+'types:string:custom-email-pattern|string:custom-phone-pattern'
+```
+
+### 2. 合理使用约束
+
+```javascript
+// ✅ 明确约束
+'types:string:3-32|number:0-100'
+
+// ❌ 过于宽松
+'types:string|number'  // 没有约束
+```
+
+### 3. 插件类型命名规范
+
+```javascript
+// ✅ 使用kebab-case
+DslBuilder.registerType('order-id', { ... });
+DslBuilder.registerType('phone-cn', { ... });
+
+// ❌ 不推荐
+DslBuilder.registerType('OrderID', { ... });
+DslBuilder.registerType('phone_cn', { ... });
+```
+
+---
+
+## 注意事项
+
+### oneOf语义
+
+`types:` 语法内部使用JSON Schema的 `oneOf`，表示"恰好匹配其中一种类型"。
+
+### 性能考虑
+
+联合类型会依次验证每个类型，直到匹配成功。类型越多，性能开销越大。
+
+**建议**:
+- 联合类型数量控制在5个以内
+- 将最常用的类型放在前面
+
+---
+
+## 相关文档
+
+- [插件系统](./plugin-system.md)
+- [自定义类型注册](./plugin-type-registration.md)
+- [代码规范](../specs/rules/代码规范.md)
+
+---
+
+## 版本历史
+
+- **v1.1.0** - 首次发布跨类型联合验证功能
+

package/docs/validate-async.md

@@ -476,5 +476,5 @@ new ValidationError(errors, data)
 
 **版本**: v1.0.4  
 **更新日期**: 2025-12-29  
-**作者**: SchemaIO Team
+**作者**: SchemaI-DSL Team
 

package/examples/array-dsl-example.js

@@ -104,7 +104,7 @@ const withAge = dsl({
 // ✨ 新特性：merge方法
 const extendedSchema = SchemaUtils.extend(baseUser, withAge);
 
-console.log('合并后字段数:', Object.keys(mergedSchema.properties).length);
+console.log('合并后字段数:', Object.keys(extendedSchema.properties).length);
 console.log('');
 
 // ========== 7. Schema pick/omit ==========