schema-dsl 1.2.5 → 2.0.1

package/docs/index.md

@@ -0,0 +1,48 @@
+---
+pageType: home
+
+hero:
+  name: schema-dsl
+  text: 简洁强大的 JSON Schema 验证库
+  tagline: DSL 语法 · 链式 API · 多格式导出 · 完整 TypeScript 支持
+  actions:
+    - theme: brand
+      text: 快速上手
+      link: /quick-start
+    - theme: alt
+      text: 文档索引
+      link: /doc-index
+    - theme: alt
+      text: GitHub
+      link: https://github.com/vextjs/schema-dsl
+
+features:
+  - title: DSL 语法
+    details: 用紧凑 DSL 字符串或对象定义验证规则，覆盖常见字段、约束与组合场景。
+  - title: 高性能验证
+    details: 基于 AJV 8 封装，支持同步、异步和批量验证，并提供缓存管理能力。
+  - title: 多格式导出
+    details: 同一份 schema 可导出到 MongoDB、MySQL、PostgreSQL 和 Markdown 文档。
+  - title: 国际化
+    details: 内置多语言错误消息与动态 locale 切换，适合服务端和前端共享校验规则。
+  - title: 插件系统
+    details: 支持扩展关键字、格式和类型注册，兼容 v1 常见插件用法。
+  - title: TypeScript 友好
+    details: 提供完整类型声明，便于在现代 Node.js 与 TypeScript 项目中直接集成。
+---
+
+## 入口导航
+
+- 在线文档: https://schema-dsl.github.io
+- 本地文档索引: [doc-index.md](./doc-index.md)
+- 快速开始: [quick-start.md](./quick-start.md)
+- 功能索引: [FEATURE-INDEX.md](./FEATURE-INDEX.md)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [home.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/home.ts)  
+**说明**: 覆盖首页展示的 DSL 定义、便捷验证与编译复用路径，可作为 Batch 1 的总入口样板。
+
+

package/docs/json-schema-basics.md

@@ -0,0 +1,40 @@
+# JSON Schema 基础
+
+schema-dsl 生成的是 JSON Schema Draft 7 风格的对象，并额外保留少量内部字段供验证器使用。
+
+常见字段：
+
+- `type`
+- `properties`
+- `required`
+- `minLength` / `maxLength`
+- `minimum` / `maximum`
+- `format`
+- `enum`
+- `items`
+
+对外输出纯净 JSON Schema 时，请使用 `toJsonSchema()`。
+
+```javascript
+const emailField = dsl('email!').label('邮箱');
+
+emailField.toSchema();
+// 含 _label / _customMessages 等内部字段
+
+emailField.toJsonSchema();
+// 纯净 JSON Schema，适合导出到外部系统
+
+const objectSchema = dsl({
+	email: emailField,
+	age: dsl('number:18-100')
+});
+// dsl({ ... }) 入口直接返回 Draft 7 风格对象
+```
+
+---
+
+## 对应示例文件
+
+**示例入口**: [json-schema-basics.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/json-schema-basics.ts)  
+**说明**: 直接对比 `toSchema()` 与 `toJsonSchema()` 的输出差异，并展示对象入口返回的 JSON Schema 结构。
+

package/docs/label-vs-description.md

@@ -1,262 +1,271 @@
-# label vs description 使用指南
-
-## 📋 快速对比
-
-| 属性 | 用途 | 显示位置 | 示例 |
-|------|------|----------|------|
-| **label** | 字段名称 | 错误消息中 | "邮箱地址不能为空" |
-| **description** | 字段说明 | 表单提示/文档 | "用于登录和接收通知" |
-
----
-
-## 🎯 详细说明
-
-### label（标签）
-
-**作用**: 在错误消息中替换字段名
-
-**使用场景**:
-- 让错误消息更友好
-- 中文化字段名
-- 简化技术字段名
-
-**示例**:
-
-```javascript
-// 不使用label
-email: 'email!'
-// 错误消息: "email is required"  ❌ 不友好
-
-// 使用label
-email: 'email!'.label('邮箱地址')
-// 错误消息: "邮箱地址不能为空"  ✅ 友好
-```
-
-**完整示例**:
-
-```javascript
-const schema = dsl({
-  userEmail: 'email!'
-    .label('用户邮箱')
-    .messages({
-      'required': '{{#label}}不能为空',  // 使用label值
-      'format': '{{#label}}格式不正确'
-    })
-});
-
-// 验证失败时:
-// 错误: "用户邮箱不能为空"
-// 错误: "用户邮箱格式不正确"
-```
-
----
-
-### description（描述）
-
-**作用**: 提供字段的详细说明
-
-**使用场景**:
-- 表单输入提示
-- API文档生成
-- Schema文档
-- 帮助用户理解字段用途
-
-**示例**:
-
-```javascript
-email: 'email!'
-  .label('邮箱地址')
-  .description('用于登录和接收系统通知')
-```
-
-**在表单中使用**:
-
-```html
-<div class="form-field">
-  <label>邮箱地址</label>  <!-- 来自 label -->
-  <input type="email" />
-  <span class="hint">用于登录和接收系统通知</span>  <!-- 来自 description -->
-</div>
-```
-
-**在API文档中**:
-
-```json
-{
-  "email": {
-    "type": "string",
-    "format": "email",
-    "title": "邮箱地址",           // 来自 label
-    "description": "用于登录和接收系统通知"  // 来自 description
-  }
-}
-```
-
----
-
-## 💡 最佳实践
-
-### 1. label 是必需的（用户可见字段）
-
-```javascript
-const schema = dsl({
-  // ✅ 好：所有用户可见字段都有label
-  username: 'string:3-32!'.label('用户名'),
-  email: 'email!'.label('邮箱地址'),
-  password: 'string:8-64!'.label('密码'),
-  
-  // ⚠️ 可以：内部字段可以不用label
-  userId: 'uuid!',
-  createdAt: 'date!'
-});
-```
-
-### 2. description 是可选的（需要说明时使用）
-
-```javascript
-const schema = dsl({
-  // ✅ 复杂字段：添加description
-  apiKey: 'string:32!'
-    .label('API密钥')
-    .description('用于调用第三方API，请妥善保管'),
-  
-  // ✅ 简单字段：不需要description
-  name: 'string:1-50!'.label('姓名'),
-  
-  // ✅ 有特殊要求的字段：添加description
-  password: 'string:8-64!'
-    .label('密码')
-    .description('必须包含大小写字母和数字')
-    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
-});
-```
-
-### 3. 组合使用示例
-
-```javascript
-const userSchema = dsl({
-  // 完整的字段定义
-  email: 'email!'
-    .label('邮箱地址')                    // 错误消息中显示
-    .description('用于登录和接收通知')    // 表单提示/文档
-    .messages({
-      'required': '{{#label}}不能为空',
-      'format': '请输入有效的{{#label}}'
-    }),
-  
-  // 简单字段
-  age: 'number:18-120'.label('年龄'),
-  
-  // 复杂字段
-  bio: 'string:500'
-    .label('个人简介')
-    .description('介绍你自己，最多500字'),
-  
-  // 内部字段（无需label/description）
-  userId: 'uuid!',
-  createdAt: 'date!'
-});
-```
-
----
-
-## 📊 使用场景对比
-
-| 场景 | label | description |
-|------|-------|-------------|
-| **错误消息** | ✅ 必需 | ❌ 不使用 |
-| **表单标签** | ✅ 推荐 | ⚠️ 可选 |
-| **表单提示** | ❌ 不使用 | ✅ 推荐 |
-| **API文档** | ✅ 作为title | ✅ 作为说明 |
-| **Schema文档** | ✅ 字段名 | ✅ 字段说明 |
-| **内部字段** | ⚠️ 可选 | ⚠️ 可选 |
-
----
-
-## 🎨 实际效果
-
-### 验证错误显示
-
-```javascript
-// Schema定义
-const schema = dsl({
-  email: 'email!'
-    .label('邮箱地址')
-    .messages({
-      'required': '{{#label}}不能为空',
-      'format': '{{#label}}格式不正确'
-    })
-});
-
-// 验证空值
-validator.validate(schema, { email: '' });
-// 错误: "邮箱地址不能为空"  ← 使用了label
-
-// 验证错误格式
-validator.validate(schema, { email: 'invalid' });
-// 错误: "邮箱地址格式不正确"  ← 使用了label
-```
-
-### 表单渲染
-
-```javascript
-const schema = dsl({
-  password: 'string:8-64!'
-    .label('登录密码')
-    .description('8-64位，包含大小写字母和数字')
-    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
-});
-
-// 渲染为HTML
-<div class="form-field">
-  <label>登录密码</label>                              ← label
-  <input type="password" />
-  <span class="hint">8-64位，包含大小写字母和数字</span>  ← description
-</div>
-```
-
----
-
-## ✅ 总结
-
-### label
-
-- **必需性**: 用户可见字段推荐使用
-- **用途**: 让错误消息更友好
-- **位置**: 错误消息、表单标签
-- **格式**: 简短的名词（2-6个字）
-
-### description
-
-- **必需性**: 可选，需要说明时使用
-- **用途**: 帮助用户理解字段用途
-- **位置**: 表单提示、API文档
-- **格式**: 完整的句子或短语
-
-### 推荐组合
-
-```javascript
-// 最小配置（简单字段）
-name: 'string:1-50!'.label('姓名')
-
-// 标准配置（常规字段）
-email: 'email!'
-  .label('邮箱地址')
-  .messages({ 'format': '请输入有效的{{#label}}' })
-
-// 完整配置（复杂字段）
-apiKey: 'string:32!'
-  .label('API密钥')
-  .description('用于调用第三方API，请妥善保管')
-  .pattern(/^[A-Za-z0-9]{32}$/)
-  .messages({
-    'required': '{{#label}}不能为空',
-    'pattern': '{{#label}}格式不正确'
-  })
-```
-
----
-
-**记住**: label用于错误消息，description用于帮助说明！
-
-
+# label vs description 使用指南
+
+## 📋 快速对比
+
+| 属性 | 用途 | 显示位置 | 示例 |
+|------|------|----------|------|
+| **label** | 字段名称 | 错误消息中 | "邮箱地址不能为空" |
+| **description** | 字段说明 | 表单提示/文档 | "用于登录和接收通知" |
+
+---
+
+## 🎯 详细说明
+
+### label（标签）
+
+**作用**: 在错误消息中替换字段名
+
+**使用场景**:
+- 让错误消息更友好
+- 中文化字段名
+- 简化技术字段名
+
+**示例**:
+
+```javascript
+// 不使用label
+email: 'email!'
+// 错误消息: "email is required"  ❌ 不友好
+
+// 使用label
+email: 'email!'.label('邮箱地址')
+// 错误消息: "邮箱地址不能为空"  ✅ 友好
+```
+
+**完整示例**:
+
+```javascript
+const schema = dsl({
+  userEmail: 'email!'
+    .label('用户邮箱')
+    .messages({
+      'required': '{{#label}}不能为空',  // 使用label值
+      'format': '{{#label}}格式不正确'
+    })
+});
+
+// 验证失败时:
+// 错误: "用户邮箱不能为空"
+// 错误: "用户邮箱格式不正确"
+```
+
+---
+
+### description（描述）
+
+**作用**: 提供字段的详细说明
+
+**使用场景**:
+- 表单输入提示
+- API文档生成
+- Schema文档
+- 帮助用户理解字段用途
+
+**示例**:
+
+```javascript
+email: 'email!'
+  .label('邮箱地址')
+  .description('用于登录和接收系统通知')
+```
+
+**在表单中使用**:
+
+```html
+<div class="form-field">
+  <label>邮箱地址</label>  <!-- 来自 label -->
+  <input type="email" />
+  <span class="hint">用于登录和接收系统通知</span>  <!-- 来自 description -->
+</div>
+```
+
+**在导出 / 文档工具中**:
+
+```json
+{
+  "email": {
+    "type": "string",
+    "format": "email",
+    "_label": "邮箱地址",          // label 在 schema-dsl 内部以 _label 保存
+    "description": "用于登录和接收系统通知"  // 来自 description
+  }
+}
+```
+
+`SchemaUtils.toMarkdown()`、导出器或你自己的表单渲染层，通常会再把 `_label` 映射成展示标题。
+
+---
+
+## 💡 最佳实践
+
+### 1. label 是必需的（用户可见字段）
+
+```javascript
+const schema = dsl({
+  // ✅ 好：所有用户可见字段都有label
+  username: 'string:3-32!'.label('用户名'),
+  email: 'email!'.label('邮箱地址'),
+  password: 'string:8-64!'.label('密码'),
+  
+  // ⚠️ 可以：内部字段可以不用label
+  userId: 'uuid!',
+  createdAt: 'date!'
+});
+```
+
+### 2. description 是可选的（需要说明时使用）
+
+```javascript
+const schema = dsl({
+  // ✅ 复杂字段：添加description
+  apiKey: 'string:32!'
+    .label('API密钥')
+    .description('用于调用第三方API，请妥善保管'),
+  
+  // ✅ 简单字段：不需要description
+  name: 'string:1-50!'.label('姓名'),
+  
+  // ✅ 有特殊要求的字段：添加description
+  password: 'string:8-64!'
+    .label('密码')
+    .description('必须包含大小写字母和数字')
+    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
+});
+```
+
+### 3. 组合使用示例
+
+```javascript
+const userSchema = dsl({
+  // 完整的字段定义
+  email: 'email!'
+    .label('邮箱地址')                    // 错误消息中显示
+    .description('用于登录和接收通知')    // 表单提示/文档
+    .messages({
+      'required': '{{#label}}不能为空',
+      'format': '请输入有效的{{#label}}'
+    }),
+  
+  // 简单字段
+  age: 'number:18-120'.label('年龄'),
+  
+  // 复杂字段
+  bio: 'string:500'
+    .label('个人简介')
+    .description('介绍你自己，最多500字'),
+  
+  // 内部字段（无需label/description）
+  userId: 'uuid!',
+  createdAt: 'date!'
+});
+```
+
+---
+
+## 📊 使用场景对比
+
+| 场景 | label | description |
+|------|-------|-------------|
+| **错误消息** | ✅ 必需 | ❌ 不使用 |
+| **表单标签** | ✅ 推荐 | ⚠️ 可选 |
+| **表单提示** | ❌ 不使用 | ✅ 推荐 |
+| **API文档** | ✅ 作为title | ✅ 作为说明 |
+| **Schema文档** | ✅ 字段名 | ✅ 字段说明 |
+| **内部字段** | ⚠️ 可选 | ⚠️ 可选 |
+
+---
+
+## 🎨 实际效果
+
+### 验证错误显示
+
+```javascript
+// Schema定义
+const schema = dsl({
+  email: 'email!'
+    .label('邮箱地址')
+    .messages({
+      'required': '{{#label}}不能为空',
+      'format': '{{#label}}格式不正确'
+    })
+});
+
+// 验证空值
+validator.validate(schema, { email: '' });
+// 错误: "邮箱地址不能为空"  ← 使用了label
+
+// 验证错误格式
+validator.validate(schema, { email: 'invalid' });
+// 错误: "邮箱地址格式不正确"  ← 使用了label
+```
+
+### 表单渲染
+
+```javascript
+const schema = dsl({
+  password: 'string:8-64!'
+    .label('登录密码')
+    .description('8-64位，包含大小写字母和数字')
+    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
+});
+
+// 渲染为HTML
+<div class="form-field">
+  <label>登录密码</label>                              ← label
+  <input type="password" />
+  <span class="hint">8-64位，包含大小写字母和数字</span>  ← description
+</div>
+```
+
+---
+
+## ✅ 总结
+
+### label
+
+- **必需性**: 用户可见字段推荐使用
+- **用途**: 让错误消息更友好
+- **位置**: 错误消息、表单标签
+- **格式**: 简短的名词（2-6个字）
+
+### description
+
+- **必需性**: 可选，需要说明时使用
+- **用途**: 帮助用户理解字段用途
+- **位置**: 表单提示、API文档
+- **格式**: 完整的句子或短语
+
+### 推荐组合
+
+```javascript
+// 最小配置（简单字段）
+name: 'string:1-50!'.label('姓名')
+
+// 标准配置（常规字段）
+email: 'email!'
+  .label('邮箱地址')
+  .messages({ 'format': '请输入有效的{{#label}}' })
+
+// 完整配置（复杂字段）
+apiKey: 'string:32!'
+  .label('API密钥')
+  .description('用于调用第三方API，请妥善保管')
+  .pattern(/^[A-Za-z0-9]{32}$/)
+  .messages({
+    'required': '{{#label}}不能为空',
+    'pattern': '{{#label}}格式不正确'
+  })
+```
+
+---
+
+**记住**: label用于错误消息和展示标题来源，description用于帮助说明！
+
+---
+
+## 对应示例文件
+
+**示例入口**: [label-vs-description.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/label-vs-description.ts)  
+**说明**: 直接展示 `_label` / `description` 在 schema 中的实际落点，以及验证错误如何消费 `label`。
+
+