schema-dsl 1.0.0 → 1.0.4

package/docs/i18n.md

@@ -0,0 +1,394 @@
+# 多语言配置指南
+
+**版本**: v1.0.1  
+**最后更新**: 2025-12-31
+
+---
+
+## 📖 概述
+
+schema-dsl 支持完整的多语言功能，允许你自定义字段标签和错误消息的翻译。
+
+---
+
+## 🚀 快速开始
+
+### 基础配置
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
+
+// 方式 1: 从目录加载（推荐）
+dsl.config({
+  i18n: path.join(__dirname, 'i18n/dsl')
+});
+
+// 方式 2: 直接传入对象
+dsl.config({
+  i18n: {
+    'zh-CN': require('./i18n/dsl/zh-CN'),
+    'en-US': require('./i18n/dsl/en-US')
+  }
+});
+```
+
+### 目录结构
+
+```
+project/
+├── i18n/
+│   └── dsl/              # schema-dsl 语言包目录
+│       ├── zh-CN.js      # 中文语言包
+│       ├── en-US.js      # 英文语言包
+│       └── ja-JP.js      # 日语语言包（可选）
+```
+
+---
+
+## 📝 语言包格式
+
+### 完整示例 (`i18n/dsl/zh-CN.js`)
+
+```javascript
+module.exports = {
+  // ========== 字段标签 ==========
+  'field.username': '用户名',
+  'field.email': '邮箱地址',
+  'field.password': '密码',
+  'field.age': '年龄',
+  
+  // ========== 覆盖默认错误消息 ==========
+  'required': '{{#label}}是必填项',
+  'string.minLength': '{{#label}}长度不能少于{{#limit}}个字符',
+  'string.maxLength': '{{#label}}长度不能超过{{#limit}}个字符',
+  'string.enum': '{{#label}}必须是以下值之一: {{#valids}}',
+  'number.base': '{{#label}}必须是数字类型',
+  'number.min': '{{#label}}不能小于{{#limit}}',
+  'number.max': '{{#label}}不能大于{{#limit}}',
+  'boolean.base': '{{#label}}必须是布尔类型',
+  'enum': '{{#label}}必须是以下值之一: {{#allowed}}',
+  
+  // ========== 自定义错误消息 ==========
+  'custom.invalidEmail': '邮箱格式不正确，请重新输入',
+  'custom.emailTaken': '该邮箱已被注册',
+  'custom.passwordWeak': '密码强度不够'
+};
+```
+
+---
+
+## 🎯 使用方法
+
+### 1. 字段标签翻译
+
+```javascript
+const schema = dsl({
+  username: dsl('string:3-32!').label('field.username'),
+  email: dsl('email!').label('field.email')
+});
+
+const result = validate(schema, { username: 'ab' });
+// 错误消息: "用户名长度不能少于3个字符"
+```
+
+### 2. 覆盖默认错误消息
+
+```javascript
+// 语言包
+module.exports = {
+  'required': '{{#label}}必须填写'
+};
+
+// Schema
+const schema = dsl({ username: 'string!' });
+
+validate(schema, {});
+// 错误消息: "username必须填写"
+```
+
+### 3. 自定义错误消息
+
+```javascript
+const schema = dsl({
+  status: dsl('active|inactive').messages({
+    'enum': '状态必须是 active 或 inactive'
+  })
+});
+```
+
+### 4. 动态语言切换
+
+```javascript
+dsl.config({
+  i18n: {
+    'zh-CN': { 'required': '{{#label}}是必填项' },
+    'en-US': { 'required': '{{#label}} is required' }
+  }
+});
+
+// 默认语言（zh-CN）
+validate(schema, data);
+
+// 切换到英文
+validate(schema, data, { locale: 'en-US' });
+```
+
+---
+
+## 📋 内置错误消息键
+
+### 通用错误
+
+| 错误键 | 说明 | 默认消息（zh-CN） |
+|--------|------|-------------------|
+| `required` | 必填字段缺失 | {{#label}}是必填项 |
+| `enum` | 枚举值不在范围 | {{#label}}必须是以下值之一: {{#allowed}} |
+| `pattern` | 格式不正确 | {{#label}}格式不正确 |
+
+### String 错误
+
+| 错误键 | 说明 |
+|--------|------|
+| `string.minLength` | 最小长度 |
+| `string.maxLength` | 最大长度 |
+| `string.pattern` | 正则不匹配 |
+| `string.enum` | 字符串枚举 |
+
+### Number 错误
+
+| 错误键 | 说明 |
+|--------|------|
+| `number.base` | 类型不是数字 |
+| `number.min` | 小于最小值 |
+| `number.max` | 大于最大值 |
+| `number.integer` | 不是整数 |
+
+### Boolean 错误
+
+| 错误键 | 说明 |
+|--------|------|
+| `boolean.base` | 类型不是布尔值 |
+
+### Array 错误
+
+| 错误键 | 说明 |
+|--------|------|
+| `array.base` | 类型不是数组 |
+| `array.min` | 元素数量不足 |
+| `array.max` | 元素数量过多 |
+| `array.unique` | 包含重复元素 |
+
+### Format 错误
+
+| 错误键 | 说明 |
+|--------|------|
+| `format.email` | 邮箱格式错误 |
+| `format.url` | URL格式错误 |
+| `format.uuid` | UUID格式错误 |
+| `format.date` | 日期格式错误 |
+| `format.binary` | Base64编码错误 |
+
+### Pattern 错误
+
+| 错误键 | 说明 |
+|--------|------|
+| `pattern.phone` | 手机号格式错误 |
+| `pattern.idCard` | 身份证格式错误 |
+| `pattern.objectId` | ObjectId格式错误 |
+
+完整列表请参考: `lib/locales/zh-CN.js`
+
+---
+
+## 🔧 高级用法
+
+### 嵌套字段标签
+
+```javascript
+// 语言包
+module.exports = {
+  'field.address.city': '城市',
+  'field.address.street': '街道'
+};
+
+// Schema
+const schema = dsl({
+  address: {
+    city: dsl('string!').label('field.address.city'),
+    street: dsl('string!').label('field.address.street')
+  }
+});
+```
+
+### 错误消息优先级
+
+1. **字段级自定义消息** - `.messages()` 方法
+2. **Schema级标签** - `.label()` 方法
+3. **语言包自定义消息** - `i18n` 配置
+4. **默认错误消息** - 内置语言包
+
+```javascript
+// 优先级示例
+dsl.config({
+  i18n: {
+    'zh-CN': {
+      'required': '全局必填消息'  // 优先级 3
+    }
+  }
+});
+
+const schema = dsl({
+  username: dsl('string!')
+    .label('用户名')                    // 优先级 2
+    .messages({ 'required': '必须填' }) // 优先级 1（最高）
+});
+```
+
+### 多语言最佳实践
+
+#### 1. 目录结构
+
+```
+project/
+├── i18n/
+│   └── dsl/
+│       ├── zh-CN.js      # 中文
+│       ├── en-US.js      # 英文
+│       ├── ja-JP.js      # 日语
+│       └── index.js      # 导出工具
+```
+
+#### 2. 导出工具 (`i18n/dsl/index.js`)
+
+```javascript
+const path = require('path');
+
+module.exports = {
+  'zh-CN': require('./zh-CN'),
+  'en-US': require('./en-US'),
+  'ja-JP': require('./ja-JP')
+};
+
+// 使用
+dsl.config({
+  i18n: require('./i18n/dsl')
+});
+```
+
+#### 3. 消息复用
+
+```javascript
+// i18n/dsl/common.js
+module.exports = {
+  required: '{{#label}}是必填项',
+  minLength: '{{#label}}长度不能少于{{#limit}}个字符'
+};
+
+// i18n/dsl/zh-CN.js
+const common = require('./common');
+
+module.exports = {
+  ...common,
+  'field.username': '用户名',
+  'field.email': '邮箱'
+};
+```
+
+---
+
+## 📊 完整示例
+
+### 用户管理系统
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
+
+// 配置多语言
+dsl.config({
+  i18n: path.join(__dirname, 'i18n/dsl')
+});
+
+// 定义 Schema
+const userSchema = dsl({
+  username: dsl('string:3-32!').label('field.username'),
+  email: dsl('email!').label('field.email'),
+  password: dsl('string:8-32!').label('field.password'),
+  age: dsl('number:18-120').label('field.age'),
+  role: dsl('admin|user|guest!').label('field.role')
+});
+
+// 验证（中文）
+let result = validate(userSchema, {
+  username: 'ab',
+  email: 'invalid',
+  role: 'admin'
+});
+
+console.log(result.errors);
+// [
+//   { path: 'username', message: '用户名长度不能少于3个字符' },
+//   { path: 'email', message: '邮箱地址必须是有效的邮箱地址' },
+//   { path: 'password', message: '密码是必填项' }
+// ]
+
+// 验证（英文）
+result = validate(userSchema, {
+  username: 'ab'
+}, { locale: 'en-US' });
+
+console.log(result.errors[0].message);
+// "username must be at least 3 characters"
+```
+
+---
+
+## 🐛 常见问题
+
+### 1. 语言包不生效？
+
+**检查清单**:
+- ✅ 配置键是否正确（`i18n` 而非 `locales`）
+- ✅ 目录路径是否正确
+- ✅ 文件名是否为语言代码（如 `zh-CN.js`）
+- ✅ 是否使用了 `module.exports`
+
+### 2. 错误消息仍然是英文？
+
+**原因**: 默认语言是英文，需要设置语言
+
+```javascript
+// 方法 1: 全局设置
+const Locale = require('schema-dsl/lib/core/Locale');
+Locale.setLocale('zh-CN');
+
+// 方法 2: 验证时指定
+validate(schema, data, { locale: 'zh-CN' });
+```
+
+### 3. 自定义消息不显示？
+
+**检查优先级**: 
+- `.messages()` > `.label()` > 语言包 > 默认
+
+```javascript
+// 错误：label 会被 messages 覆盖
+dsl('string!')
+  .label('用户名')
+  .messages({ 'required': '必填' })  // 这个生效
+```
+
+---
+
+## 📚 相关文档
+
+- [快速开始](../README.md)
+- [API 参考](./api.md)
+- [完整示例](../examples/i18n-full-demo.js)
+
+---
+
+**文档生成时间**: 2025-12-31  
+**版本**: v1.0.1
+

package/docs/performance-benchmark-report.md

@@ -0,0 +1,179 @@
+# schema-dsl 性能测试报告
+
+## 📋 测试概述
+
+**测试日期**: 2024-01-XX  
+**测试版本**: v1.0.3  
+**测试环境**: Node.js (运行环境)  
+**对比库**: Joi, Yup, Zod, Ajv  
+
+## 🎯 测试目标
+
+验证 schema-dsl 在真实场景下的性能表现，并与主流验证库进行公平对比。
+
+## 🔬 测试方法
+
+### 公平性保证
+
+1. **预编译Schema**: 所有库的 schema 均在测试前预编译，避免编译时间影响测试结果
+2. **JIT预热**: 每个测试前执行 10% 的预热迭代，确保 V8 引擎充分优化
+3. **多轮测试**: 每个测试执行 10 轮，移除最高/最低值，取平均值
+4. **高精度计时**: 使用 `process.hrtime.bigint()` 实现纳秒级精度
+5. **无异常处理干扰**: 移除性能关键路径中的 try-catch，避免 JIT 反优化
+6. **统一测试数据**: 所有库使用完全相同的测试数据结构
+
+### 测试配置
+
+```javascript
+// 简单验证场景
+iterations: 10000
+rounds: 10
+warmup: 1000 (10%)
+
+// 复杂验证场景  
+iterations: 5000
+rounds: 10
+warmup: 500 (10%)
+```
+
+### 测试场景
+
+#### 场景1: 简单对象验证
+```javascript
+{
+  username: 'john_doe',
+  email: 'john@example.com',
+  age: 25
+}
+```
+
+#### 场景2: 复杂嵌套验证
+```javascript
+{
+  name: 'John Doe',
+  email: 'john@example.com',
+  profile: {
+    age: 30,
+    bio: 'Software developer',
+    tags: ['javascript', 'nodejs']
+  }
+}
+```
+
+## 📊 测试结果
+
+### 10轮完整测试汇总
+
+#### 简单验证性能
+| 验证库 | 平均吞吐量 | 最低吞吐量 | 最高吞吐量 | 标准差 | 稳定性 |
+|--------|-----------|-----------|-----------|--------|-------|
+| **schema-dsl** | **4,130,506/s** | 3,694,035/s | 4,563,536/s | 266,785 | ⭐⭐⭐⭐ |
+| Joi | 466,616/s | 448,739/s | 477,551/s | 7,941 | ⭐⭐⭐⭐⭐ |
+| Yup | 318,888/s | 309,023/s | 324,891/s | 4,268 | ⭐⭐⭐⭐⭐ |
+| Zod | 9,743,926/s | 8,247,990/s | 10,450,049/s | 646,068 | ⭐⭐⭐⭐ |
+| Ajv | 21,456,535/s | 17,460,641/s | 25,036,512/s | 2,602,772 | ⭐⭐⭐ |
+
+#### 复杂验证性能
+| 验证库 | 平均吞吐量 | 最低吞吐量 | 最高吞吐量 | 标准差 | 稳定性 |
+|--------|-----------|-----------|-----------|--------|-------|
+| **schema-dsl** | **3,159,137/s** | 2,910,530/s | 3,345,526/s | 145,171 | ⭐⭐⭐⭐⭐ |
+| Joi | 242,500/s | 233,608/s | 251,069/s | 4,410 | ⭐⭐⭐⭐⭐ |
+| Yup | 70,313/s | 65,425/s | 72,158/s | 2,016 | ⭐⭐⭐⭐⭐ |
+| Zod | 2,487,493/s | 2,313,726/s | 2,762,660/s | 130,431 | ⭐⭐⭐⭐⭐ |
+| Ajv | 9,021,336/s | 8,012,179/s | 10,069,141/s | 632,381 | ⭐⭐⭐⭐ |
+
+### 性能对比分析
+
+#### schema-dsl vs 其他库
+
+**简单验证场景**:
+- **vs Joi**: 快 **8.85倍** (413万/s vs 47万/s)
+- **vs Yup**: 快 **12.95倍** (413万/s vs 32万/s)
+- **vs Zod**: 慢 0.42倍 (413万/s vs 974万/s)
+- **vs Ajv**: 慢 0.19倍 (413万/s vs 2146万/s)
+
+**复杂验证场景**:
+- **vs Joi**: 快 **13.03倍** (316万/s vs 24万/s)
+- **vs Yup**: 快 **44.93倍** (316万/s vs 7万/s)
+- **vs Zod**: 快 **1.27倍** (316万/s vs 249万/s) ⭐
+- **vs Ajv**: 慢 0.35倍 (316万/s vs 902万/s)
+
+## 🎯 核心发现
+
+### 1. 简洁性与性能的平衡
+
+schema-dsl 在保持最简洁 DSL 语法的同时：
+- 比 Joi 快 **9-13倍**
+- 比 Yup 快 **13-45倍**  
+- **复杂场景超越 Zod 1.3倍**
+
+### 2. 复杂场景优势明显
+
+随着验证规则复杂度增加，schema-dsl 的优势更加明显：
+- 简单场景: 优于 Joi/Yup，但不及 Zod/Ajv
+- **复杂场景: 超越 Zod，仅次于 Ajv**
+
+### 3. 性能稳定性
+
+标准差分析显示：
+- **schema-dsl**: 中等稳定性（简单: 266k, 复杂: 145k）
+- **Joi/Yup/Zod**: 非常稳定（标准差 < 20k）
+- **Ajv**: 波动较大（标准差 > 600k）
+
+## 💡 选型建议
+
+### 选择 schema-dsl 的理由
+
+✅ **追求简洁性**: `'string:3-32!'` vs `Joi.string().min(3).max(32).required()`  
+✅ **复杂验证场景**: 嵌套对象、数组验证性能超越 Zod  
+✅ **平衡性能与可读性**: 比 Joi/Yup 快得多，语法比 Ajv 简单得多  
+✅ **多语言支持**: 内置 5 种语言错误消息自动翻译  
+
+### 其他库的优势
+
+- **Ajv**: 极致性能要求（但需要学习 JSON Schema）
+- **Zod**: TypeScript 类型推导（但复杂场景性能不如 schema-dsl）
+- **Joi**: 生态成熟、稳定可靠（但性能和简洁性较差）
+- **Yup**: 与 Formik 集成好（但性能最慢）
+
+## 🔧 测试改进历史
+
+### 之前的测试问题
+
+1. ❌ Yup 测试中使用 try-catch 导致 JIT 反优化
+2. ❌ 缺少 JIT 预热阶段，冷启动影响结果
+3. ❌ 单次运行，受垃圾回收等因素影响
+4. ❌ 使用 Date.now() 计时，精度不足（±1ms）
+
+### 改进后的测试
+
+1. ✅ 移除所有性能关键路径的 try-catch
+2. ✅ 添加 10% 预热迭代确保 JIT 优化
+3. ✅ 10 轮测试取平均值，移除异常值
+4. ✅ 使用 process.hrtime.bigint() 纳秒级计时
+
+### 性能数据修正
+
+| 版本 | 简单验证 | 复杂验证 | 变化 |
+|------|---------|---------|------|
+| 旧测试 | 50万/s | 63万/s | 基准 |
+| 新测试 | **413万/s** | **316万/s** | ⬆️ 8.3倍 / 5.0倍 |
+
+**注**: 旧测试方法的不公平性导致低估了 schema-dsl 的真实性能。
+
+## 📝 结论
+
+schema-dsl 成功实现了 **"简洁性"** 与 **"性能"** 的平衡：
+
+1. **DSL 语法最简洁**: `'string:3-32!'` 一行搞定
+2. **复杂场景性能优异**: 超越 Zod，仅次于 Ajv
+3. **生产级性能**: 100万+ QPS 足以应对绝大多数应用
+4. **多语言支持**: 自动错误消息翻译
+
+对于追求 **代码可读性** 和 **合理性能** 的开发者来说，schema-dsl 是理想选择！
+
+---
+
+**测试代码**: [test/performance/library-comparison.test.js](../test/performance/library-comparison.test.js)  
+**运行脚本**: [test/performance/run-benchmark.js](../test/performance/run-benchmark.js)  
+**复现方法**: `node test/performance/run-benchmark.js`

package/docs/plugin-system.md

@@ -60,7 +60,7 @@ const myPlugin = {
   version: '1.0.0',
   description: '我的自定义插件',
 
-  install(schema-dsl, options, context) {
+  install(schemaDsl, options, context) {
     console.log('插件安装成功！');
   }
 };
@@ -71,9 +71,9 @@ pluginManager.register(myPlugin);
 ### 3. 安装插件
 
 ```javascript
-const schema-dsl = require('schema-dsl');
+const schemaDsl = require('schema-dsl');
 
-pluginManager.install(schema-dsl, 'my-plugin');
+pluginManager.install(schemaDsl, 'my-plugin');
 ```
 
 ### 4. 使用插件
@@ -92,14 +92,14 @@ pluginManager.install(schema-dsl, 'my-plugin');
 module.exports = {
   // ========== 必填 ==========
   name: 'plugin-name',          // 插件名称（唯一）
-  install: function(schema-dsl, options, context) {
+  install: function(schemaDsl, options, context) {
     // 安装逻辑
   },
 
   // ========== 可选 ==========
   version: '1.0.0',            // 插件版本
   description: '插件描述',      // 插件描述
-  uninstall: function(schema-dsl, context) {
+  uninstall: function(schemaDsl, context) {
     // 卸载逻辑
   },
   hooks: {                      // 生命周期钩子
@@ -119,8 +119,8 @@ module.exports = {
   name: 'custom-validator',
   version: '1.0.0',
 
-  install(schema-dsl, options, context) {
-    const { Validator } = schema-dsl;
+  install(schemaDsl, options, context) {
+    const { Validator } = schemaDsl;
     
     // 添加自定义关键字
     Validator.prototype.addKeyword('unique', {
@@ -142,7 +142,7 @@ module.exports = {
   name: 'custom-format',
   version: '1.0.0',
 
-  install(schema-dsl, options, context) {
+  install(schemaDsl, options, context) {
     const validator = schemaDsl.getDefaultValidator();
     const ajv = validator.getAjv();