schema-dsl 1.0.0

package/examples/plugin-system.examples.js

@@ -0,0 +1,205 @@
+/**
+ * 插件系统使用示例
+ */
+
+const { dsl, validate, PluginManager } = require('../index');
+
+// ========== 1. 基础使用 ==========
+
+console.log('=== 1. 基础使用 ===\n');
+
+// 创建插件管理器
+const pluginManager = new PluginManager();
+
+// 注册插件
+const customValidatorPlugin = require('../plugins/custom-validator');
+pluginManager.register(customValidatorPlugin);
+
+const customFormatPlugin = require('../plugins/custom-format');
+pluginManager.register(customFormatPlugin);
+
+// 安装插件
+const schemaDsl = require('../index');
+pluginManager.install(schemaDsl);
+
+console.log('已安装插件:', pluginManager.list());
+console.log('');
+
+// ========== 2. 使用自定义格式 ==========
+
+console.log('=== 2. 使用自定义格式 ===\n');
+
+const contactSchema = dsl({
+    phone: 'string!',
+    email: 'email!',
+    wechat: 'string'
+});
+
+// 测试数据
+const validContact = {
+    phone: '13800138000',
+    email: 'test@example.com',
+    wechat: 'my_wechat_id'
+};
+
+const result1 = validate(contactSchema, validContact);
+console.log('验证结果:', result1.valid ? '✅ 通过' : '❌ 失败');
+if (!result1.valid) {
+    console.log('错误:', result1.errors);
+}
+console.log('');
+
+// ========== 3. 使用钩子系统 ==========
+
+console.log('=== 3. 使用钩子系统 ===\n');
+
+// 注册钩子
+pluginManager.hook('onBeforeValidate', (schema, data) => {
+    console.log('[Hook] 验证前:', { schema: '...', data });
+});
+
+pluginManager.hook('onAfterValidate', (result) => {
+    console.log('[Hook] 验证后:', { valid: result.valid });
+});
+
+// 运行钩子
+const testSchema = dsl({ name: 'string!' });
+const testData = { name: 'John' };
+
+pluginManager.runHook('onBeforeValidate', testSchema, testData);
+const result2 = validate(testSchema, testData);
+pluginManager.runHook('onAfterValidate', result2);
+console.log('');
+
+// ========== 4. 自定义插件 ==========
+
+console.log('=== 4. 自定义插件 ===\n');
+
+// 创建自定义插件
+const myPlugin = {
+    name: 'my-plugin',
+    version: '1.0.0',
+    description: '我的自定义插件',
+
+    install(schemaDsl, options, context) {
+        console.log('[Plugin] my-plugin 安装中...');
+        console.log('  选项:', options);
+        console.log('  已注册插件数:', context.plugins.size);
+
+        // 添加自定义方法
+        schemaDsl.myCustomMethod = () => {
+            console.log('  这是自定义方法!');
+        };
+    },
+
+    uninstall(schemaDsl, context) {
+        console.log('[Plugin] my-plugin 卸载中...');
+        delete schemaDsl.myCustomMethod;
+    },
+
+    hooks: {
+        onBeforeValidate(schema, data) {
+            console.log('  [my-plugin] 验证前钩子');
+        }
+    }
+};
+
+// 注册并安装
+pluginManager.register(myPlugin);
+pluginManager.install(schemaDsl, 'my-plugin', { custom: true });
+
+// 使用自定义方法
+if (schemaDsl.myCustomMethod) {
+    schemaDsl.myCustomMethod();
+}
+console.log('');
+
+// ========== 5. 插件管理 ==========
+
+console.log('=== 5. 插件管理 ===\n');
+
+// 查看所有插件
+console.log('所有插件:', pluginManager.list());
+
+// 检查插件是否存在
+console.log('my-plugin 是否存在:', pluginManager.has('my-plugin'));
+
+// 获取插件数量
+console.log('插件数量:', pluginManager.size);
+console.log('');
+
+// ========== 6. 实用插件示例 ==========
+
+console.log('=== 6. 实用插件示例 ===\n');
+
+// 日志插件
+const loggingPlugin = {
+    name: 'logging',
+    version: '1.0.0',
+
+    install(schemaDsl, options, context) {
+        // 包装 validate 方法
+        const originalValidate = schemaDsl.validate;
+        schemaDsl.validate = function (...args) {
+            console.log('[Logging] 开始验证');
+            const start = Date.now();
+            const result = originalValidate.apply(this, args);
+            const duration = Date.now() - start;
+            console.log(`[Logging] 验证完成，耗时 ${duration}ms，结果: ${result.valid ? '通过' : '失败'}`);
+            return result;
+        };
+    }
+};
+
+pluginManager.register(loggingPlugin);
+pluginManager.install(schemaDsl, 'logging');
+
+// 测试日志插件
+const schema = dsl({ email: 'email!' });
+validate(schema, { email: 'test@example.com' });
+console.log('');
+
+// ========== 7. 卸载插件 ==========
+
+console.log('=== 7. 卸载插件 ===\n');
+
+pluginManager.uninstall('my-plugin', schemaDsl);
+console.log('my-plugin 已卸载');
+console.log('当前插件数:', pluginManager.size);
+console.log('');
+
+// ========== 8. 批量插件 ==========
+
+console.log('=== 8. 批量插件 ===\n');
+
+// 清空所有插件
+pluginManager.clear(schemaDsl);
+console.log('所有插件已清空');
+console.log('当前插件数:', pluginManager.size);
+console.log('');
+
+// 批量注册多个插件
+const plugins = [
+    customValidatorPlugin,
+    customFormatPlugin
+];
+
+plugins.forEach(plugin => pluginManager.register(plugin));
+pluginManager.install(schemaDsl); // 安装所有插件
+
+console.log('批量安装完成:', pluginManager.list());
+console.log('');
+
+// ========== 总结 ==========
+
+console.log('=== 总结 ===\n');
+console.log('✅ 插件系统支持:');
+console.log('  - 动态注册/卸载插件');
+console.log('  - 生命周期钩子');
+console.log('  - 自定义验证器和格式');
+console.log('  - 插件间通信');
+console.log('  - 事件监听');
+console.log('');
+console.log('示例运行完成！');
+
+

package/examples/schema-utils-chaining.examples.js

@@ -0,0 +1,250 @@
+/**
+ * SchemaUtils 核心方法示例
+ *
+ * 展示 v2.1.0 简化后的核心 4 个方法：
+ * 1. omit() - 排除字段
+ * 2. pick() - 保留字段
+ * 3. partial() - 部分验证
+ * 4. extend() - 扩展字段
+ *
+ * @version 2.1.0 (简化版)
+ * @date 2025-12-29
+ */
+
+const { dsl, validate, SchemaUtils } = require('../index');
+
+console.log('========================================');
+console.log('  SchemaUtils 核心方法示例');
+console.log('========================================\n');
+
+// ===== 定义基础 Schema =====
+
+const fullUserSchema = dsl({
+  id: 'objectId!',
+  name: 'string:1-50!',
+  email: 'email!',
+  password: 'string:8-32!',
+  age: 'integer:18-120',
+  role: 'admin|user|guest',
+  createdAt: 'date',
+  updatedAt: 'date'
+});
+
+console.log('基础 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('必填字段:', fullUserSchema.required);
+console.log('');
+
+// ===== 1. omit() - 排除字段 =====
+
+console.log('========== 1. omit() - 排除字段 ==========\n');
+
+const publicSchema = SchemaUtils.omit(fullUserSchema, ['password', 'createdAt', 'updatedAt']);
+
+console.log('原 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('omit 后字段:', Object.keys(publicSchema.properties));
+console.log('password 字段被移除:', publicSchema.properties.password === undefined);
+console.log('');
+
+// ===== 2. pick() - 保留字段 =====
+
+console.log('========== 2. pick() - 保留字段 ==========\n');
+
+const nameEmailSchema = SchemaUtils.pick(fullUserSchema, ['name', 'email']);
+
+console.log('原 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('pick 后字段:', Object.keys(nameEmailSchema.properties));
+console.log('只保留 name 和 email');
+console.log('');
+
+// ===== 3. partial() - 部分验证 =====
+
+console.log('========== 3. partial() - 部分验证 ==========\n');
+
+const partialSchema = SchemaUtils.partial(fullUserSchema);
+
+console.log('原 Schema 必填字段:', fullUserSchema.required);
+console.log('partial Schema 必填字段:', partialSchema.required);
+
+// 测试：缺少必填字段
+const result4 = validate(partialSchema, {
+  name: 'John'
+  // 缺少其他必填字段
+});
+
+console.log('\n验证结果（缺少必填字段）:');
+console.log('  valid:', result4.valid);
+if (result4.valid) {
+  console.log('  数据:', result4.data);
+}
+console.log('');
+
+// 部分验证 - 只验证指定字段
+const nameAgeSchema = SchemaUtils.partial(fullUserSchema, ['name', 'age']);
+
+console.log('partial(schema, [name, age]) 保留字段:', Object.keys(nameAgeSchema.properties));
+
+const result5 = validate(nameAgeSchema, {
+  name: 'John',
+  age: 30
+});
+
+console.log('验证结果（只验证 name 和 age）:');
+console.log('  valid:', result5.valid);
+console.log('');
+
+// ===== 4. extend() - 扩展字段 =====
+
+console.log('========== 4. extend() - 扩展字段 ==========\n');
+
+const extendedSchema = SchemaUtils.extend(fullUserSchema, {
+  avatar: 'url',
+  bio: 'string:0-500'
+});
+
+console.log('原 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('extend 后字段:', Object.keys(extendedSchema.properties));
+console.log('新增字段: avatar, bio');
+console.log('');
+
+// ===== 5. 链式调用 =====
+
+console.log('========== 5. 链式调用 ==========\n');
+
+// 示例 1: omit
+console.log('示例 1: omit (创建用户 Schema)');
+const createSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+console.log('  字段:', Object.keys(createSchema.properties));
+console.log('');
+
+// 示例 2: pick + partial
+console.log('示例 2: pick + partial (更新用户 Schema)');
+const updateSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'age'])
+  .partial();
+
+console.log('  字段:', Object.keys(updateSchema.properties));
+console.log('  必填字段:', updateSchema.required);
+console.log('');
+
+// 示例 3: pick + extend (用户建议的常见场景)
+console.log('示例 3: pick + extend (自定义用户 Schema)');
+const customSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'email'])
+  .extend({ avatar: 'url', bio: 'string:0-500' });
+
+console.log('  字段:', Object.keys(customSchema.properties));
+console.log('');
+
+// 示例 4: omit + extend
+console.log('示例 4: omit + extend (增强用户 Schema)');
+const enhancedSchema = SchemaUtils
+  .omit(fullUserSchema, ['password'])
+  .extend({ avatar: 'url', bio: 'string:0-500' });
+
+console.log('  字段:', Object.keys(enhancedSchema.properties));
+console.log('  新增字段: avatar, bio');
+console.log('');
+
+// ===== 6. 实际 CRUD 场景 =====
+
+console.log('========== 6. 实际 CRUD 场景 ==========\n');
+
+console.log('场景 1: POST /users - 创建用户');
+const postSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+const postData = {
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'password123',
+  age: 30,
+  role: 'user'
+};
+
+const postResult = validate(postSchema, postData);
+console.log('  验证结果:', postResult.valid);
+console.log('  数据:', postResult.data);
+console.log('');
+
+console.log('场景 2: GET /users/:id - 查询用户');
+const getSchema = SchemaUtils.omit(fullUserSchema, ['password']);
+
+const userData = {
+  id: '507f1f77bcf86cd799439011',
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'password123',  // 已从 schema 移除，但验证时会被忽略
+  age: 30,
+  role: 'user',
+  createdAt: new Date(),
+  updatedAt: new Date()
+};
+
+const getResult = validate(getSchema, userData);
+console.log('  验证结果:', getResult.valid);
+console.log('  保留字段:', Object.keys(getResult.data));
+console.log('');
+
+console.log('场景 3: PATCH /users/:id - 部分更新用户');
+const patchSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'age'])
+  .partial();
+
+const patchData = {
+  name: 'John Updated'
+  // 只更新 name，age 缺失也可以
+};
+
+const patchResult = validate(patchSchema, patchData);
+console.log('  验证结果:', patchResult.valid);
+console.log('  数据:', patchResult.data);
+console.log('');
+
+console.log('场景 4: PUT /users/:id - 替换用户');
+const putSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+const putData = {
+  name: 'John Replaced',
+  email: 'john.new@example.com',
+  password: 'newpassword123',
+  age: 31,
+  role: 'admin'
+};
+
+const putResult = validate(putSchema, putData);
+console.log('  验证结果:', putResult.valid);
+console.log('  数据:', putResult.data);
+console.log('');
+
+// ===== 7. 不可变性验证 =====
+
+console.log('========== 7. 不可变性验证 ==========\n');
+
+const original = dsl({
+  name: 'string!',
+  email: 'email!'
+});
+
+const modified = SchemaUtils.omit(original, ['email']);
+
+console.log('原 Schema 字段:', Object.keys(original.properties));
+console.log('修改后 Schema 字段:', Object.keys(modified.properties));
+console.log('原 Schema 未被修改:', original.properties.email !== undefined);
+console.log('');
+
+console.log('========================================');
+console.log('  所有示例运行完成！');
+console.log('========================================\n');
+
+console.log('核心方法总结:');
+console.log('  1. omit() - 排除字段（50%场景）');
+console.log('  2. pick() - 保留字段（30%场景）');
+console.log('  3. partial() - 部分验证（25%场景）');
+console.log('  4. extend() - 扩展字段（15%场景）');
+console.log('');
+console.log('常见组合:');
+console.log('  - POST: omit(系统字段)');
+console.log('  - GET: omit(敏感字段)');
+console.log('  - PATCH: pick(可修改字段).partial()');
+console.log('  - 自定义: pick(基础字段).extend(新字段)');
+

package/examples/simple-example.js

@@ -0,0 +1,122 @@
+/**
+ * SchemaIO v2.0.1 - 简洁示例
+ *
+ * 展示最简洁、最直观的用法
+ */
+
+const { dsl, validate, SchemaUtils } = require('../index');
+
+console.log('========== SchemaIO v2.0.1 简洁示例 ==========\n');
+
+// ========== 1. 数组验证 - 超简洁 ==========
+console.log('✨ 1. 数组验证');
+
+const articleSchema = dsl({
+  title: 'string:5-100!',
+  tags: 'array!1-10'  // ✨ 简洁：必填，1-10个元素
+});
+
+console.log('验证文章:', validate(articleSchema, {
+  title: 'Hello World',
+  tags: ['javascript', 'nodejs']
+}).valid);
+console.log('');
+
+// ========== 2. when条件 - 超直观 ==========
+console.log('✨ 2. 条件验证');
+
+const contactSchema = dsl({
+  type: 'email|phone',
+  contact: dsl.match('type', {
+    email: 'email!',
+    phone: 'phone:cn!'
+  })
+});
+
+console.log('验证邮箱:', validate(contactSchema, { type: 'email', contact: 'test@example.com' }).valid);
+console.log('验证手机:', validate(contactSchema, { type: 'phone', contact: '13800138000' }).valid);
+console.log('');
+
+// ========== 3. 快捷方法 - 不用找正则 ==========
+console.log('✨ 3. 快捷方法');
+
+const userSchema = dsl({
+  mobile: 'string!'.phoneNumber('cn'),
+  id: 'string!'.idCard('cn')
+});
+
+console.log('验证快捷方法:', validate(userSchema, {
+  mobile: '13800138000',
+  id: '110101199003071234'
+}).valid);
+console.log('');
+
+// ========== 4. Schema复用 - 不重复代码 ==========
+console.log('✨ 4. Schema复用');
+
+// 定义一次，到处使用
+const emailField = SchemaUtils.reusable(() => dsl('email!'));
+
+const loginForm = dsl({ email: emailField() });
+const registerForm = dsl({ email: emailField(), name: 'string!' });
+
+console.log('复用Schema成功');
+console.log('');
+
+// ========== 5. Schema合并 - 灵活组合 ==========
+console.log('✨ 5. Schema合并');
+
+const baseUser = dsl({ name: 'string!', email: 'email!' });
+const withAge = dsl({ age: 'number:18-120' });
+
+const fullUser = SchemaUtils.extend(baseUser, withAge);
+
+console.log('合并后字段:', Object.keys(fullUser.properties));
+console.log('');
+
+// ========== 6. 批量验证 - 快50倍 ==========
+console.log('✨ 6. 批量验证');
+
+const users = [
+  { email: 'user1@example.com' },
+  { email: 'invalid' },
+  { email: 'user3@example.com' }
+];
+
+const { Validator } = require('../index');
+const batchResult = SchemaUtils.validateBatch(
+  dsl({ email: 'email!' }),
+  users,
+  new Validator() // 批量验证需要 Validator 实例以复用编译结果
+);
+
+console.log('批量验证:', {
+  总数: batchResult.summary.total,
+  有效: batchResult.summary.valid,
+  无效: batchResult.summary.invalid,
+  耗时: `${batchResult.summary.duration}ms`
+});
+console.log('');
+
+// ========== 总结 ==========
+console.log('========== 核心理念 ==========');
+console.log(`
+✨ SchemaIO v2.0.1 三大特点：
+
+1. 简洁
+   'array!1-10'           // 一眼看懂
+   .phoneNumber('cn')     // 不用找正则
+
+2. 直观
+   dsl.match('type', {    // 清晰的条件映射
+     email: 'email!',
+     phone: 'string:11!'
+   })
+
+3. 强大
+   SchemaUtils.extend()   // 扩展字段
+   validateBatch()        // 快50倍
+
+🎉 简洁 + 直观 + 强大 = 完美验证库！
+`);
+