schema-dsl 1.0.0

package/examples/custom-extension.js

@@ -0,0 +1,85 @@
+/**
+ * 扩展自定义类型示例
+ *
+ * 演示如何在项目中扩展 SchemaIO 的功能：
+ * 1. 扩展 DSL 方法 (DslBuilder.prototype)
+ * 2. 添加自定义格式 (Validator.addFormat)
+ * 3. 添加自定义关键字 (Validator.addKeyword)
+ */
+
+const { dsl, Validator, DslBuilder } = require('../index');
+
+// ========== 1. 扩展 DSL 方法 ==========
+
+// 扩展 .zipCode() 方法
+DslBuilder.prototype.zipCode = function(country = 'cn') {
+  const patterns = {
+    cn: /^[1-9]\d{5}$/,
+    us: /^\d{5}(-\d{4})?$/
+  };
+
+  const pattern = patterns[country];
+  if (!pattern) throw new Error(`Unsupported country: ${country}`);
+
+  return this.pattern(pattern)
+    .messages({ 'pattern': `无效的邮政编码 (${country})` });
+};
+
+// 扩展 .isEven() 方法 (自定义验证逻辑)
+DslBuilder.prototype.isEven = function() {
+  return this.custom(value => {
+    if (typeof value === 'number' && value % 2 !== 0) {
+      return '必须是偶数';
+    }
+  });
+};
+
+// ========== 2. 添加自定义格式 (Validator) ==========
+
+const validator = new Validator();
+
+// 添加 'ipv4-cidr' 格式
+validator.ajv.addFormat('ipv4-cidr', {
+  type: 'string',
+  validate: (ip) => {
+    const parts = ip.split('/');
+    if (parts.length !== 2) return false;
+    const [addr, mask] = parts;
+    // 简单验证 (实际应使用更严谨的正则)
+    return /^\d{1,3}(\.\d{1,3}){3}$/.test(addr) &&
+           Number(mask) >= 0 && Number(mask) <= 32;
+  }
+});
+
+// ========== 3. 使用扩展功能 ==========
+
+const schema = dsl({
+  // 使用扩展的 DSL 方法 (注意：自定义方法需要用 dsl() 包裹，或者手动扩展 String.prototype)
+  zip: dsl('string!').zipCode('cn'),
+  count: dsl('integer!').isEven(),
+
+  // 使用自定义格式 (通过 string 类型 + format)
+  network: 'string'.format('ipv4-cidr')
+});
+
+// ========== 4. 测试验证 ==========
+
+const data = {
+  zip: '123',       // 无效
+  count: 3,         // 无效 (奇数)
+  network: 'invalid' // 无效
+};
+
+const result = validator.validate(schema, data);
+
+console.log('验证结果:', result.valid);
+if (!result.valid) {
+  result.errors.forEach(e => console.log(`- ${e.path}: ${e.message}`));
+}
+
+// 输出预期:
+// - zip: 无效的邮政编码 (cn)
+// - count: 必须是偶数
+// - network: must match format "ipv4-cidr"
+
+

package/examples/dsl-match-example.js

@@ -0,0 +1,74 @@
+/**
+ * DSL Match 语法示例 (v2.1.0)
+ *
+ * 展示如何使用 dsl.match 和 dsl.if 进行条件验证
+ */
+
+const { dsl, validate } = require('../index');
+const fs = require('fs');
+
+function log(msg) {
+  console.log(msg);
+  fs.appendFileSync('dsl-match-output.txt', msg + '\n');
+}
+
+log('Start example...');
+
+log('========== DSL Match 语法示例 ==========\n');
+
+// 1. 基本用法：根据类型验证格式
+log('✨ 1. 基本用法');
+
+const contactSchema = dsl({
+  contactType: 'email|phone',
+
+  // 根据 contactType 的值决定 contact 的验证规则
+  contact: dsl.match('contactType', {
+    email: 'email!',
+    phone: 'string:11!',
+    _default: 'string'
+  })
+});
+
+const data1 = { contactType: 'email', contact: 'test@example.com' };
+log('Email验证: ' + (validate(contactSchema, data1).valid ? '✅ 通过' : '❌ 失败'));
+
+const data2 = { contactType: 'phone', contact: '13800138000' };
+log('Phone验证: ' + (validate(contactSchema, data2).valid ? '✅ 通过' : '❌ 失败'));
+
+const data3 = { contactType: 'phone', contact: '123456789012' }; // 12位，超过11
+log('错误验证: ' + (validate(contactSchema, data3).valid ? '✅ 通过' : '❌ 失败'));
+log('');
+
+
+// 2. 处理中文和特殊字符
+log('✨ 2. 中文和特殊字符');
+
+const discountSchema = dsl({
+  level: 'string',
+
+  discount: dsl.match('level', {
+    '普通用户': 'number:0-5',
+    'VIP-1':   'number:0-20',
+    '100':     'number:0-50'
+  })
+});
+
+log('普通用户: ' + validate(discountSchema, { level: '普通用户', discount: 3 }).valid);
+log('VIP-1: ' + validate(discountSchema, { level: 'VIP-1', discount: 15 }).valid);
+log('');
+
+
+// 3. dsl.if 简单条件
+log('✨ 3. dsl.if 简单条件');
+
+const vipSchema = dsl({
+  isVip: 'boolean',
+  // 如果是VIP，折扣0-50，否则0-10
+  discount: dsl.if('isVip', 'number:0-50', 'number:0-10')
+});
+
+log('VIP折扣: ' + validate(vipSchema, { isVip: true, discount: 40 }).valid);
+log('非VIP折扣: ' + validate(vipSchema, { isVip: false, discount: 40 }).valid); // false
+log('');
+

package/examples/dsl-style.js

@@ -0,0 +1,118 @@
+/**
+ * DSL风格API示例 v2.0
+ *
+ * 演示新的DSL Builder Pattern：
+ * - 简单场景：纯字符串DSL
+ * - 复杂场景：字符串直接链式调用（✨ 无需 dsl() 包裹）
+ */
+
+const { dsl, Validator } = require('../index');
+
+// ========== 1. 简单场景：纯字符串DSL ==========
+
+const simpleSchema = dsl({
+  username: 'string:3-32!',    // 必填字符串，长度3-32
+  email: 'email!',              // 必填邮箱
+  age: 'number:18-120',         // 可选数字，范围18-120
+  status: 'active|inactive|pending', // 枚举值
+  tags: 'array<string:1-20>',   // 字符串数组，每项长度1-20
+});
+
+console.log('========== 简单Schema（纯DSL）==========');
+console.log(JSON.stringify(simpleSchema, null, 2));
+
+// ========== 2. 复杂场景：字符串直接链式调用 ✨ ==========
+
+const complexSchema = dsl({
+  // ✨ 超简洁！字符串直接调用链式方法，无需 dsl() 包裹
+  username: 'string:3-32!'
+    .pattern(/^[a-zA-Z0-9_]+$/)
+    .messages({
+      'pattern': '只能包含字母、数字和下划线'
+    })
+    .label('用户名')
+    .description('用户登录名'),
+
+  // ✨ 邮箱：直接链式
+  email: 'email!'
+    .label('邮箱地址')
+    .messages({
+      'format': '请输入有效的邮箱地址'
+    }),
+
+  // ✨ 密码：复杂正则 + 自定义消息
+  password: 'string:8-64!'
+    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
+    .messages({
+      'min': '密码长度不能少于8位',
+      'pattern': '密码必须包含大小写字母和数字'
+    })
+    .label('密码'),
+
+  // 年龄：简单约束（无需链式）
+  age: 'number:18-120',
+
+  // 角色：枚举（无需链式）
+  role: 'user|admin|moderator',
+
+  // 嵌套对象：混合使用
+  profile: {
+    bio: 'string:500',          // 简单：纯DSL
+    website: 'url'              // ✨ 也可以链式
+      .description('个人主页'),
+    avatar: 'url'
+      .label('头像URL')
+  }
+});
+
+console.log('\n========== 复杂Schema（DSL + 链式）==========');
+console.log(JSON.stringify(complexSchema, null, 2));
+
+// ========== 3. 验证数据 ==========
+
+const { validate } = require('../index');
+
+const testData = {
+  username: 'john_doe',
+  email: 'john@example.com',
+  password: 'Password123',
+  age: 25,
+  role: 'user',
+  profile: {
+    bio: 'Full-stack developer',
+    website: 'https://example.com',
+    avatar: 'https://example.com/avatar.jpg'
+  }
+};
+
+console.log('\n========== 验证数据 ==========');
+const result = validate(complexSchema, testData);
+console.log('验证结果:', result.valid ? '✅ 通过' : '❌ 失败');
+if (!result.valid) {
+  console.log('错误:', result.errors);
+}
+
+// ========== 4. 展示API优势 ==========
+
+console.log('\n========== API对比 ==========');
+
+// v1.0: 需要 dsl() 包裹
+console.log('❌ v1.0（需要 dsl()）:');
+console.log(`  email: dsl('email!')
+    .pattern(/custom/)
+    .messages({ 'pattern': '格式不正确' })
+    .label('邮箱地址')`);
+
+// v2.0: 字符串直接链式
+console.log('\n✅ v2.0（字符串直接链式）:');
+console.log(`  email: 'email!'
+    .pattern(/custom/)
+    .messages({ 'pattern': '格式不正确' })
+    .label('邮箱地址')`);
+
+console.log('\n✅ DSL v2.0 示例运行完成！');
+console.log('💡 提示：简单字段用纯DSL，复杂字段直接链式调用');
+console.log('🎉 特色：字符串直接调用方法，无需 dsl() 包裹！');
+
+
+

package/examples/dynamic-locale-configuration.js

@@ -0,0 +1,348 @@
+/**
+ * 动态多语言配置完整示例
+ *
+ * 演示如何在各种场景下动态配置和切换语言
+ */
+
+const { dsl, validate, Locale } = require('../index');
+
+console.log('========== 动态多语言配置示例 ==========\n');
+
+// ========================================
+// 示例 1: 基本的语言切换
+// ========================================
+console.log('【示例 1】基本的语言切换\n');
+
+const userSchema = dsl({
+  email: 'email!',
+  age: 'number:18-120!'
+});
+
+// 中文环境
+Locale.setLocale('zh-CN');
+let result = validate(userSchema, { email: 'invalid', age: 10 });
+console.log('中文错误:', result.errors.map(e => e.message).join(', '));
+
+// 切换到英文
+Locale.setLocale('en-US');
+result = validate(userSchema, { email: 'invalid', age: 10 });
+console.log('英文错误:', result.errors.map(e => e.message).join(', '));
+
+console.log('\n' + '='.repeat(60) + '\n');
+
+// ========================================
+// 示例 2: 使用 dsl.config() 批量配置语言包
+// ========================================
+console.log('【示例 2】使用 dsl.config() 批量配置\n');
+
+dsl.config({
+  locales: {
+    'zh-CN': {
+      'custom.tooYoung': '{{#label}}年龄太小，需满18岁',
+      'custom.emailTaken': '{{#label}}已被占用'
+    },
+    'en-US': {
+      'custom.tooYoung': '{{#label}} is too young, must be 18+',
+      'custom.emailTaken': '{{#label}} is already taken'
+    }
+  }
+});
+
+// 测试自定义消息
+Locale.setLocale('zh-CN');
+console.log('中文自定义:', Locale.getMessage('custom.tooYoung'));
+
+Locale.setLocale('en-US');
+console.log('英文自定义:', Locale.getMessage('custom.tooYoung'));
+
+console.log('\n' + '='.repeat(60) + '\n');
+
+// ========================================
+// 示例 3: 模拟前端语言切换
+// ========================================
+console.log('【示例 3】模拟前端语言切换\n');
+
+class LanguageManager {
+  constructor() {
+    this.locale = 'en-US';
+    this.storage = {}; // 模拟 localStorage
+  }
+
+  // 获取用户偏好语言
+  getUserPreference() {
+    return this.storage.userLanguage || this.detectBrowserLanguage();
+  }
+
+  // 检测浏览器语言（模拟）
+  detectBrowserLanguage() {
+    // 模拟 navigator.language
+    const browserLang = 'zh-CN';
+    const langMap = {
+      'zh': 'zh-CN',
+      'zh-CN': 'zh-CN',
+      'en': 'en-US',
+      'en-US': 'en-US'
+    };
+    return langMap[browserLang] || langMap[browserLang.split('-')[0]] || 'en-US';
+  }
+
+  // 切换语言
+  changeLanguage(newLocale) {
+    console.log(`切换语言: ${this.locale} → ${newLocale}`);
+    this.locale = newLocale;
+    this.storage.userLanguage = newLocale;
+    Locale.setLocale(newLocale);
+  }
+
+  // 初始化
+  init() {
+    const preferredLang = this.getUserPreference();
+    console.log(`初始化语言: ${preferredLang}`);
+    this.changeLanguage(preferredLang);
+  }
+}
+
+const langManager = new LanguageManager();
+langManager.init();
+
+// 验证（使用检测到的语言）
+result = validate(userSchema, { email: 'test', age: 15 });
+console.log('当前语言:', Locale.getLocale());
+console.log('错误消息:', result.errors.map(e => e.message).join(', '));
+
+// 用户手动切换
+langManager.changeLanguage('en-US');
+result = validate(userSchema, { email: 'test', age: 15 });
+console.log('错误消息:', result.errors.map(e => e.message).join(', '));
+
+console.log('\n' + '='.repeat(60) + '\n');
+
+// ========================================
+// 示例 4: 模拟服务端请求语言切换
+// ========================================
+console.log('【示例 4】服务端请求语言切换（安全模式）\n');
+
+function validateWithLocale(schema, data, requestLocale) {
+  // 保存原始语言
+  const originalLocale = Locale.getLocale();
+
+  try {
+    // 临时切换到请求的语言
+    Locale.setLocale(requestLocale);
+
+    // 执行验证
+    const result = validate(schema, data);
+
+    return {
+      locale: requestLocale,
+      errors: result.errors
+    };
+  } finally {
+    // 恢复原始语言（重要！）
+    Locale.setLocale(originalLocale);
+  }
+}
+
+// 模拟多个并发请求
+console.log('请求1 (中文):');
+const req1 = validateWithLocale(userSchema, { email: 'bad' }, 'zh-CN');
+console.log('  语言:', req1.locale);
+console.log('  错误:', req1.errors.map(e => e.message).join(', '));
+
+console.log('\n请求2 (英文):');
+const req2 = validateWithLocale(userSchema, { email: 'bad' }, 'en-US');
+console.log('  语言:', req2.locale);
+console.log('  错误:', req2.errors.map(e => e.message).join(', '));
+
+console.log('\n请求3 (日文):');
+const req3 = validateWithLocale(userSchema, { email: 'bad' }, 'ja-JP');
+console.log('  语言:', req3.locale);
+console.log('  错误:', req3.errors.map(e => e.message).join(', '));
+
+console.log('\n全局语言未被污染:', Locale.getLocale());
+
+console.log('\n' + '='.repeat(60) + '\n');
+
+// ========================================
+// 示例 5: 动态加载语言包（模拟）
+// ========================================
+console.log('【示例 5】动态加载语言包\n');
+
+class LocaleLoader {
+  constructor() {
+    this.loadedLocales = new Set(['en-US']); // 默认已加载
+  }
+
+  // 模拟异步加载语言包
+  async loadLocale(locale) {
+    if (this.loadedLocales.has(locale)) {
+      console.log(`语言包 "${locale}" 已加载，跳过`);
+      return;
+    }
+
+    console.log(`正在加载语言包 "${locale}"...`);
+
+    // 模拟网络延迟
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // 模拟语言包内容
+    const mockLanguagePacks = {
+      'fr-FR': {
+        'required': '{{#label}} est requis',
+        'format.email': '{{#label}} doit être une adresse e-mail valide'
+      },
+      'de-DE': {
+        'required': '{{#label}} ist erforderlich',
+        'format.email': '{{#label}} muss eine gültige E-Mail-Adresse sein'
+      }
+    };
+
+    const messages = mockLanguagePacks[locale];
+    if (messages) {
+      Locale.addLocale(locale, messages);
+      this.loadedLocales.add(locale);
+      console.log(`✅ 语言包 "${locale}" 加载成功`);
+    } else {
+      console.log(`❌ 语言包 "${locale}" 不存在，回退到英文`);
+      return 'en-US';
+    }
+  }
+
+  // 切换语言（带自动加载）
+  async changeLanguage(locale) {
+    await this.loadLocale(locale);
+    Locale.setLocale(locale);
+    console.log(`当前语言: ${Locale.getLocale()}\n`);
+  }
+}
+
+const loader = new LocaleLoader();
+
+(async () => {
+  // 加载法语
+  await loader.changeLanguage('fr-FR');
+  result = validate(userSchema, { email: 'mauvais' });
+  console.log('法语错误:', result.errors.map(e => e.message).join(', '));
+
+  console.log('');
+
+  // 加载德语
+  await loader.changeLanguage('de-DE');
+  result = validate(userSchema, { email: 'schlecht' });
+  console.log('德语错误:', result.errors.map(e => e.message).join(', '));
+
+  console.log('\n' + '='.repeat(60) + '\n');
+
+  // ========================================
+  // 示例 6: 同时获取多种语言的错误消息
+  // ========================================
+  console.log('【示例 6】同时获取多种语言的错误消息\n');
+
+  const ErrorFormatter = require('../lib/core/ErrorFormatter');
+  const Validator = require('../lib/core/Validator');
+
+  const validator = new Validator();
+  const invalidData = { email: 'invalid-email', age: 10 };
+
+  // 执行验证
+  const validationResult = validator.validate(userSchema, invalidData);
+
+  // 获取多种语言的错误消息
+  const languages = ['zh-CN', 'en-US', 'ja-JP'];
+  const multiLangErrors = {};
+
+  languages.forEach(lang => {
+    const formatter = new ErrorFormatter(lang);
+    multiLangErrors[lang] = formatter.formatDetailed(validationResult.errors);
+  });
+
+  console.log('多语言错误消息:');
+  console.log(JSON.stringify(multiLangErrors, null, 2));
+
+  console.log('\n' + '='.repeat(60) + '\n');
+
+  // ========================================
+  // 示例 7: 完整的前端应用场景
+  // ========================================
+  console.log('【示例 7】完整的前端应用场景\n');
+
+  class FormValidator {
+    constructor() {
+      this.schema = dsl({
+        username: 'string:3-20!'.label('username'),
+        email: 'email!'.label('email'),
+        password: 'string:8-32!'.label('password')
+      });
+
+      // 初始化语言
+      this.initLanguage();
+    }
+
+    initLanguage() {
+      // 1. 从 localStorage 恢复
+      const savedLang = this.getStoredLanguage();
+
+      // 2. 如果没有保存，检测浏览器语言
+      const lang = savedLang || this.detectBrowserLanguage();
+
+      // 3. 设置语言
+      this.changeLanguage(lang);
+
+      console.log(`应用启动，语言初始化为: ${lang}`);
+    }
+
+    getStoredLanguage() {
+      // 模拟 localStorage.getItem
+      return null; // 首次访问
+    }
+
+    detectBrowserLanguage() {
+      // 模拟 navigator.language
+      return 'zh-CN';
+    }
+
+    changeLanguage(lang) {
+      console.log(`用户选择语言: ${lang}`);
+      Locale.setLocale(lang);
+      // 模拟 localStorage.setItem
+    }
+
+    validateForm(formData) {
+      const result = validate(this.schema, formData);
+
+      return {
+        valid: result.valid,
+        errors: result.errors.map(err => ({
+          field: err.path,
+          message: err.message
+        }))
+      };
+    }
+  }
+
+  const formValidator = new FormValidator();
+
+  // 模拟表单提交
+  console.log('\n提交表单（中文环境）:');
+  let formResult = formValidator.validateForm({
+    username: 'ab',
+    email: 'bad',
+    password: '123'
+  });
+  console.log('验证结果:', JSON.stringify(formResult, null, 2));
+
+  // 用户切换语言
+  console.log('\n用户切换到英文:');
+  formValidator.changeLanguage('en-US');
+
+  console.log('\n再次提交表单（英文环境）:');
+  formResult = formValidator.validateForm({
+    username: 'ab',
+    email: 'bad',
+    password: '123'
+  });
+  console.log('验证结果:', JSON.stringify(formResult, null, 2));
+
+  console.log('\n========== 所有示例完成 ==========');
+})();
+