schema-dsl 1.0.0 → 1.0.3

package/examples/README.md

@@ -0,0 +1,81 @@
+# schema-dsl 示例代码
+
+本目录包含 schema-dsl 的各种功能示例。
+
+## 📂 示例列表
+
+### 基础示例
+- [simple-example.js](simple-example.js) - 简单入门示例
+- [dsl-style.js](dsl-style.js) - DSL 风格完整示例
+- [enum.examples.js](enum.examples.js) - 枚举类型验证示例
+
+### 扩展功能
+- [string-extensions.js](string-extensions.js) - String 扩展功能（username、password、phone）
+- [custom-extension.js](custom-extension.js) - 自定义扩展示例
+- [array-dsl-example.js](array-dsl-example.js) - 数组 DSL 语法示例
+
+### 数据库导出
+- [export-demo.js](export-demo.js) - 导出为 MongoDB/MySQL/PostgreSQL Schema
+
+### 国际化 (i18n)
+- [dynamic-locale-configuration.js](dynamic-locale-configuration.js) - 动态语言配置示例
+- [dynamic-locale-example.js](dynamic-locale-example.js) - 动态语言切换示例
+- [i18n-full-demo.js](i18n-full-demo.js) - 完整国际化示例
+- [i18n-memory-safety.examples.js](i18n-memory-safety.examples.js) - i18n 内存安全示例
+
+### Schema 工具
+- [schema-utils-chaining.examples.js](schema-utils-chaining.examples.js) - SchemaUtils 链式调用示例
+- [dsl-match-example.js](dsl-match-example.js) - 条件验证 match 示例
+- [new-features-comparison.js](new-features-comparison.js) - 新版本功能对比
+
+### 插件系统
+- [plugin-system.examples.js](plugin-system.examples.js) - 插件系统完整示例
+
+### 实际应用
+- [express-integration.js](express-integration.js) - Express 集成完整示例
+- [middleware-usage.js](middleware-usage.js) - 中间件使用示例
+- [user-registration/](user-registration/) - 用户注册流程完整示例
+  - [schema.js](user-registration/schema.js) - Schema 定义
+  - [routes.js](user-registration/routes.js) - 路由定义
+  - [server.js](user-registration/server.js) - 服务器入口
+- [password-reset/](password-reset/) - 密码重置流程示例
+  - [schema.js](password-reset/schema.js) - Schema 定义
+  - [test.js](password-reset/test.js) - 测试用例
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+cd schema-dsl
+npm install
+```
+
+### 2. 运行示例
+
+```bash
+# 运行简单示例
+node examples/simple-example.js
+
+# 运行 String 扩展示例
+node examples/string-extensions.js
+
+# 运行导出示例
+node examples/export-demo.js
+```
+
+### 3. 查看完整文档
+
+访问 [docs/INDEX.md](../docs/INDEX.md) 查看完整文档索引。
+
+## 📖 相关文档
+
+- [DSL 语法文档](../docs/dsl-syntax.md)
+- [String 扩展文档](../docs/string-extensions.md)
+- [插件系统文档](../docs/plugin-system.md)
+- [API 参考](../docs/api-reference.md)
+- [最佳实践](../docs/best-practices.md)
+
+## 🤝 贡献
+
+欢迎提交新的示例！请参考 [CONTRIBUTING.md](../CONTRIBUTING.md)。

package/examples/enum.examples.js

@@ -0,0 +1,324 @@
+/**
+ * 枚举功能完整示例
+ *
+ * 演示 schema-dsl 中枚举的各种用法
+ *
+ * @since v1.1.0
+ */
+
+const { dsl, validate } = require('../index');
+
+console.log('========== 枚举功能示例 ==========\n');
+
+// ========================================
+// 1. 基础字符串枚举
+// ========================================
+console.log('【示例 1】基础字符串枚举\n');
+
+const userSchema = dsl({
+  username: 'string:3-32!',
+  role: 'admin|user|guest!',           // 简写形式
+  status: 'enum:active|inactive|pending'  // 完整形式
+});
+
+let result = validate(userSchema, {
+  username: 'john_doe',
+  role: 'admin',
+  status: 'active'
+});
+
+console.log('✅ 验证通过:', result.valid);
+console.log('数据:', result.data);
+console.log('');
+
+// 测试无效值
+result = validate(userSchema, {
+  username: 'jane',
+  role: 'superadmin',  // 无效值
+  status: 'active'
+});
+
+console.log('❌ 验证失败:', !result.valid);
+console.log('错误:', result.errors[0].message);
+console.log('');
+
+// ========================================
+// 2. 布尔值枚举
+// ========================================
+console.log('【示例 2】布尔值枚举\n');
+
+const featureSchema = dsl({
+  name: 'string!',
+  isEnabled: 'true|false!',              // 自动识别为布尔值
+  isPublic: 'enum:boolean:true|false',   // 显式指定布尔值
+  verified: 'true|false'                 // 可选的布尔值
+});
+
+result = validate(featureSchema, {
+  name: 'dark-mode',
+  isEnabled: true,
+  isPublic: false
+});
+
+console.log('✅ 验证通过:', result.valid);
+console.log('数据:', result.data);
+console.log('');
+
+// 测试类型错误
+result = validate(featureSchema, {
+  name: 'feature-x',
+  isEnabled: 'true',  // 字符串 'true' 不是布尔值
+  isPublic: false
+});
+
+console.log('❌ 类型错误（字符串 vs 布尔值）:', !result.valid);
+console.log('');
+
+// ========================================
+// 3. 数字枚举
+// ========================================
+console.log('【示例 3】数字枚举\n');
+
+const taskSchema = dsl({
+  title: 'string!',
+  priority: '1|2|3!',                    // 自动识别为数字
+  level: 'enum:number:1|2|3|4|5',       // 显式指定数字
+  rating: '1.0|1.5|2.0|2.5|3.0'         // 小数枚举
+});
+
+result = validate(taskSchema, {
+  title: 'Fix bug',
+  priority: 1,
+  level: 3,
+  rating: 2.5
+});
+
+console.log('✅ 验证通过:', result.valid);
+console.log('数据:', result.data);
+console.log('');
+
+// 测试超出范围
+result = validate(taskSchema, {
+  title: 'New task',
+  priority: 4,  // 超出 1|2|3
+  level: 2
+});
+
+console.log('❌ 超出范围:', !result.valid);
+console.log('');
+
+// ========================================
+// 4. 整数枚举
+// ========================================
+console.log('【示例 4】整数枚举（禁止小数）\n');
+
+const gameSchema = dsl({
+  playerName: 'string!',
+  difficulty: 'enum:integer:1|2|3'  // 必须是整数
+});
+
+result = validate(gameSchema, {
+  playerName: 'Alice',
+  difficulty: 2
+});
+
+console.log('✅ 整数验证通过:', result.valid);
+console.log('');
+
+// 小数应该失败
+result = validate(gameSchema, {
+  playerName: 'Bob',
+  difficulty: 1.5  // 小数不符合 integer 类型
+});
+
+console.log('❌ 小数验证失败:', !result.valid);
+console.log('');
+
+// ========================================
+// 5. 枚举与链式 API
+// ========================================
+console.log('【示例 5】枚举与链式 API\n');
+
+const postSchema = dsl({
+  title: 'string:5-100!',
+  status: dsl('draft|published|archived')
+    .label('文章状态')
+    .messages({
+      'enum': '状态必须是: 草稿、已发布或已归档'
+    }),
+  visibility: dsl('public|private|unlisted!')
+    .label('可见性')
+    .default('public')
+});
+
+result = validate(postSchema, {
+  title: 'My First Post',
+  status: 'invalid_status',
+  visibility: 'public'
+});
+
+console.log('❌ 自定义错误消息:', !result.valid);
+console.log('错误:', result.errors[0].message);
+console.log('');
+
+// ========================================
+// 6. 数组中的枚举
+// ========================================
+console.log('【示例 6】数组中的枚举\n');
+
+const articleSchema = dsl({
+  title: 'string!',
+  tags: 'array<enum:tech|business|lifestyle>',
+  permissions: 'array<enum:read|write|delete>'
+});
+
+result = validate(articleSchema, {
+  title: 'Tech Article',
+  tags: ['tech', 'business'],
+  permissions: ['read', 'write']
+});
+
+console.log('✅ 数组枚举验证通过:', result.valid);
+console.log('数据:', result.data);
+console.log('');
+
+// ========================================
+// 7. 复杂对象中的枚举
+// ========================================
+console.log('【示例 7】复杂对象中的枚举\n');
+
+const orderSchema = dsl({
+  orderId: 'string!',
+  status: 'pending|processing|completed|cancelled!',
+  priority: '1|2|3'.default(2),
+  payment: {
+    method: 'card|paypal|crypto!',
+    status: 'pending|success|failed!'
+  },
+  items: 'array',
+  metadata: {
+    isUrgent: 'true|false',
+    category: 'electronics|clothing|food'
+  }
+});
+
+result = validate(orderSchema, {
+  orderId: 'ORD-12345',
+  status: 'processing',
+  priority: 1,
+  payment: {
+    method: 'card',
+    status: 'success'
+  },
+  items: [],
+  metadata: {
+    isUrgent: true,
+    category: 'electronics'
+  }
+});
+
+console.log('✅ 复杂对象验证通过:', result.valid);
+console.log('数据:', JSON.stringify(result.data, null, 2));
+console.log('');
+
+// ========================================
+// 8. 错误处理
+// ========================================
+console.log('【示例 8】错误处理\n');
+
+try {
+  // 无效的布尔值枚举
+  dsl({ flag: 'enum:boolean:true|false|maybe' });
+} catch (error) {
+  console.log('❌ 捕获错误:', error.message);
+}
+
+try {
+  // 无效的数字枚举
+  dsl({ value: 'enum:number:1|2|abc' });
+} catch (error) {
+  console.log('❌ 捕获错误:', error.message);
+}
+
+console.log('');
+
+// ========================================
+// 9. 实际应用场景
+// ========================================
+console.log('【示例 9】实际应用 - 用户管理系统\n');
+
+const userManagementSchema = dsl({
+  // 基本信息
+  userId: 'string!',
+  username: 'string:3-32!',
+  email: 'email!',
+
+  // 枚举字段
+  role: 'admin|moderator|user|guest!',
+  status: 'active|inactive|suspended|banned',
+  emailVerified: 'true|false',
+
+  // 权限等级（数字枚举）
+  permissionLevel: '0|1|2|3|4|5'.default(0),
+
+  // 偏好设置
+  preferences: {
+    theme: 'light|dark|auto',
+    language: 'en|zh-CN|zh-TW|ja|ko',
+    notifications: 'all|mentions|none'
+  }
+});
+
+const newUser = {
+  userId: 'u_12345',
+  username: 'alice',
+  email: 'alice@example.com',
+  role: 'user',
+  status: 'active',
+  emailVerified: true,
+  permissionLevel: 1,
+  preferences: {
+    theme: 'dark',
+    language: 'zh-CN',
+    notifications: 'mentions'
+  }
+};
+
+result = validate(userManagementSchema, newUser);
+
+console.log('✅ 用户数据验证通过:', result.valid);
+console.log('用户数据:', JSON.stringify(result.data, null, 2));
+console.log('');
+
+// ========================================
+// 10. 性能测试
+// ========================================
+console.log('【示例 10】性能测试\n');
+
+const perfSchema = dsl({
+  status: 'active|inactive|pending',
+  priority: '1|2|3',
+  flag: 'true|false'
+});
+
+const iterations = 10000;
+const startTime = Date.now();
+
+for (let i = 0; i < iterations; i++) {
+  validate(perfSchema, {
+    status: 'active',
+    priority: 2,
+    flag: true
+  });
+}
+
+const endTime = Date.now();
+const duration = endTime - startTime;
+const perSecond = Math.round((iterations / duration) * 1000);
+
+console.log(`验证 ${iterations} 次耗时: ${duration}ms`);
+console.log(`平均每秒验证: ${perSecond.toLocaleString()} 次`);
+console.log('');
+
+console.log('========== 示例结束 ==========');
+

package/examples/express-integration.js

@@ -7,7 +7,7 @@
  * 3. SchemaUtils 链式调用
  * 4. 完整 CRUD 场景
  * 
- * @version 2.1.0
+ * @version 1.0.3
  * @date 2025-12-29
  */
 
@@ -63,12 +63,12 @@ app.post('/users', async (req, res, next) => {
   try {
     console.log('\n[POST /users] 创建用户');
     console.log('请求体:', req.body);
-    
+
     // 使用 validateAsync 验证
     const data = await validateAsync(createUserSchema, req.body);
-    
+
     console.log('验证通过，数据:', data);
-    
+
     // 保存到数据库
     const user = {
       id: String(db.nextId++),
@@ -76,20 +76,20 @@ app.post('/users', async (req, res, next) => {
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString()
     };
-    
+
     db.users.push(user);
-    
+
     // 返回公开信息
     const { validate } = require('../index');
     const result = validate(publicUserSchema, user);
-    
+
     console.log('返回数据:', result.data);
-    
+
     res.status(201).json({
       success: true,
       user: result.data
     });
-    
+
   } catch (error) {
     next(error);
   }
@@ -102,17 +102,17 @@ app.post('/users', async (req, res, next) => {
  */
 app.get('/users', (req, res) => {
   console.log('\n[GET /users] 获取所有用户');
-  
+
   const { validate } = require('../index');
-  
+
   // 对每个用户应用 publicUserSchema
   const publicUsers = db.users.map(user => {
     const result = validate(publicUserSchema, user);
     return result.data;
   });
-  
+
   console.log(`返回 ${publicUsers.length} 个用户`);
-  
+
   res.json({
     success: true,
     count: publicUsers.length,
@@ -127,9 +127,9 @@ app.get('/users', (req, res) => {
  */
 app.get('/users/:id', (req, res) => {
   console.log(`\n[GET /users/${req.params.id}] 获取用户`);
-  
+
   const user = db.users.find(u => u.id === req.params.id);
-  
+
   if (!user) {
     console.log('用户不存在');
     return res.status(404).json({
@@ -137,13 +137,13 @@ app.get('/users/:id', (req, res) => {
       error: '用户不存在'
     });
   }
-  
+
   // 使用 clean 模式自动移除敏感字段
   const { validate } = require('../index');
   const result = validate(publicUserSchema, user);
-  
+
   console.log('返回数据:', result.data);
-  
+
   res.json({
     success: true,
     user: result.data
@@ -162,9 +162,9 @@ app.patch('/users/:id', async (req, res, next) => {
   try {
     console.log(`\n[PATCH /users/${req.params.id}] 部分更新用户`);
     console.log('请求体:', req.body);
-    
+
     const user = db.users.find(u => u.id === req.params.id);
-    
+
     if (!user) {
       console.log('用户不存在');
       return res.status(404).json({
@@ -172,28 +172,28 @@ app.patch('/users/:id', async (req, res, next) => {
         error: '用户不存在'
       });
     }
-    
+
     // 验证部分数据
     const data = await validateAsync(updateUserSchema, req.body);
-    
+
     console.log('验证通过，更新字段:', data);
-    
+
     // 更新用户
     Object.assign(user, data, {
       updatedAt: new Date().toISOString()
     });
-    
+
     // 返回公开信息
     const { validate } = require('../index');
     const result = validate(publicUserSchema, user);
-    
+
     console.log('返回数据:', result.data);
-    
+
     res.json({
       success: true,
       user: result.data
     });
-    
+
   } catch (error) {
     next(error);
   }
@@ -210,9 +210,9 @@ app.put('/users/:id', async (req, res, next) => {
   try {
     console.log(`\n[PUT /users/${req.params.id}] 替换用户`);
     console.log('请求体:', req.body);
-    
+
     const userIndex = db.users.findIndex(u => u.id === req.params.id);
-    
+
     if (userIndex === -1) {
       console.log('用户不存在');
       return res.status(404).json({
@@ -220,12 +220,12 @@ app.put('/users/:id', async (req, res, next) => {
         error: '用户不存在'
       });
     }
-    
+
     // 验证完整数据
     const data = await validateAsync(replaceUserSchema, req.body);
-    
+
     console.log('验证通过，替换用户:', data);
-    
+
     // 替换用户（保留 id 和 createdAt）
     const oldUser = db.users[userIndex];
     db.users[userIndex] = {
@@ -234,18 +234,18 @@ app.put('/users/:id', async (req, res, next) => {
       createdAt: oldUser.createdAt,
       updatedAt: new Date().toISOString()
     };
-    
+
     // 返回公开信息
     const { validate } = require('../index');
     const result = validate(publicUserSchema, db.users[userIndex]);
-    
+
     console.log('返回数据:', result.data);
-    
+
     res.json({
       success: true,
       user: result.data
     });
-    
+
   } catch (error) {
     next(error);
   }
@@ -256,9 +256,9 @@ app.put('/users/:id', async (req, res, next) => {
  */
 app.delete('/users/:id', (req, res) => {
   console.log(`\n[DELETE /users/${req.params.id}] 删除用户`);
-  
+
   const userIndex = db.users.findIndex(u => u.id === req.params.id);
-  
+
   if (userIndex === -1) {
     console.log('用户不存在');
     return res.status(404).json({
@@ -266,11 +266,11 @@ app.delete('/users/:id', (req, res) => {
       error: '用户不存在'
     });
   }
-  
+
   db.users.splice(userIndex, 1);
-  
+
   console.log('删除成功');
-  
+
   res.json({
     success: true,
     message: '用户已删除'
@@ -290,10 +290,10 @@ app.use((error, req, res, next) => {
     console.log('\n[错误] ValidationError 被捕获');
     console.log('错误数量:', error.getErrorCount());
     console.log('字段错误:', error.getFieldErrors());
-    
+
     return res.status(error.statusCode).json(error.toJSON());
   }
-  
+
   // 其他错误
   console.error('\n[错误] 服务器错误:', error);
   res.status(500).json({
@@ -319,7 +319,7 @@ app.listen(PORT, () => {
   console.log(`  PUT    http://localhost:${PORT}/users/:id - 替换用户`);
   console.log(`  DELETE http://localhost:${PORT}/users/:id - 删除用户`);
   console.log(`\n========================================\n`);
-  
+
   // 打印测试命令
   printTestCommands();
 });
@@ -328,46 +328,46 @@ app.listen(PORT, () => {
 
 function printTestCommands() {
   console.log(`测试命令（使用 curl）:\n`);
-  
+
   console.log(`# 1. 创建用户（成功）`);
   console.log(`curl -X POST http://localhost:${PORT}/users \\`);
   console.log(`  -H "Content-Type: application/json" \\`);
   console.log(`  -d '{"name":"John Doe","email":"john@example.com","password":"password123","age":30,"role":"user"}'\n`);
-  
+
   console.log(`# 2. 创建用户（失败 - 缺少必填字段）`);
   console.log(`curl -X POST http://localhost:${PORT}/users \\`);
   console.log(`  -H "Content-Type: application/json" \\`);
   console.log(`  -d '{"name":"Jane"}'\n`);
-  
+
   console.log(`# 3. 创建用户（失败 - 额外字段被拒绝）`);
   console.log(`curl -X POST http://localhost:${PORT}/users \\`);
   console.log(`  -H "Content-Type: application/json" \\`);
   console.log(`  -d '{"name":"Bob","email":"bob@example.com","password":"password123","extraField":"not allowed"}'\n`);
-  
+
   console.log(`# 4. 获取所有用户`);
   console.log(`curl http://localhost:${PORT}/users\n`);
-  
+
   console.log(`# 5. 获取单个用户（替换 ID）`);
   console.log(`curl http://localhost:${PORT}/users/1\n`);
-  
+
   console.log(`# 6. 部分更新用户（成功 - 只更新 name）`);
   console.log(`curl -X PATCH http://localhost:${PORT}/users/1 \\`);
   console.log(`  -H "Content-Type: application/json" \\`);
   console.log(`  -d '{"name":"John Updated"}'\n`);
-  
+
   console.log(`# 7. 部分更新用户（成功 - 允许额外字段）`);
   console.log(`curl -X PATCH http://localhost:${PORT}/users/1 \\`);
   console.log(`  -H "Content-Type: application/json" \\`);
   console.log(`  -d '{"age":31,"extraField":"allowed"}'\n`);
-  
+
   console.log(`# 8. 替换用户（成功 - 必须提供所有必填字段）`);
   console.log(`curl -X PUT http://localhost:${PORT}/users/1 \\`);
   console.log(`  -H "Content-Type: application/json" \\`);
   console.log(`  -d '{"name":"John Replaced","email":"john.new@example.com","password":"newpassword123","age":32}'\n`);
-  
+
   console.log(`# 9. 删除用户`);
   console.log(`curl -X DELETE http://localhost:${PORT}/users/1\n`);
-  
+
   console.log(`========================================\n`);
 }