schema-dsl 1.0.9 → 1.1.1

package/examples/conditional-non-object.js

@@ -0,0 +1,129 @@
+/**
+ * ConditionalBuilder 非对象类型示例
+ *
+ * 展示如何直接验证字符串、数组、布尔值等非对象类型
+ */
+
+const { dsl, validate } = require('../index');
+
+console.log('========================================');
+console.log('ConditionalBuilder - 非对象类型示例');
+console.log('========================================\n');
+
+// ============================================
+// 示例1：直接验证字符串
+// ============================================
+console.log('【示例1】直接验证字符串');
+console.log('----------------------------');
+
+const stringSchema = dsl.if((data) => typeof data === 'string' && data.includes('@'))
+  .then('email!')
+  .else('string:1-50');
+
+const r1 = validate(stringSchema, 'test@example.com');
+console.log('✅ 邮箱格式:', r1.valid ? '验证通过' : '验证失败');
+
+const r2 = validate(stringSchema, 'just a text');
+console.log('✅ 普通文本:', r2.valid ? '验证通过' : '验证失败');
+
+// ============================================
+// 示例2：直接验证数组
+// ============================================
+console.log('\n【示例2】直接验证数组');
+console.log('----------------------------');
+
+const arraySchema = dsl.if((data) => Array.isArray(data) && data.length > 5)
+  .message('数组最多5个元素');
+
+const r3 = validate(arraySchema, [1, 2, 3]);
+console.log('✅ 3个元素:', r3.valid ? '验证通过' : '验证失败');
+
+const r4 = validate(arraySchema, [1, 2, 3, 4, 5, 6]);
+console.log('❌ 6个元素:', r4.valid ? '验证通过' : '验证失败');
+if (!r4.valid) {
+  console.log('   错误:', r4.errors[0].message);
+}
+
+// ============================================
+// 示例3：直接验证数字
+// ============================================
+console.log('\n【示例3】直接验证数字');
+console.log('----------------------------');
+
+const numberSchema = dsl.if((data) => typeof data === 'number' && data < 0)
+  .message('不允许负数')
+  .else(null); // 不需要额外验证
+
+const r5 = validate(numberSchema, 10);
+console.log('✅ 正数:', r5.valid ? '验证通过' : '验证失败');
+
+const r6 = validate(numberSchema, -5);
+console.log('❌ 负数:', r6.valid ? '验证通过' : '验证失败');
+if (!r6.valid) {
+  console.log('   错误:', r6.errors[0].message);
+}
+
+// ============================================
+// 示例4：字符串类型判断（邮箱或手机号）
+// ============================================
+console.log('\n【示例4】自动识别邮箱或手机号');
+console.log('----------------------------');
+
+const contactSchema = dsl.if((data) => typeof data === 'string' && data.includes('@'))
+  .then('email!')
+  .else('string:11!');
+
+const r7 = validate(contactSchema, 'user@example.com');
+console.log('✅ 邮箱:', r7.valid ? '验证通过' : '验证失败');
+
+const r8 = validate(contactSchema, '13800138000');
+console.log('✅ 手机号:', r8.valid ? '验证通过' : '验证失败');
+
+const r9 = validate(contactSchema, 'invalid');
+console.log('❌ 无效输入:', r9.valid ? '验证通过' : '验证失败');
+if (!r9.valid) {
+  console.log('   错误:', r9.errors[0].message);
+}
+
+// ============================================
+// 示例5：复杂条件组合
+// ============================================
+console.log('\n【示例5】字符串长度 + 内容组合判断');
+console.log('----------------------------');
+
+const complexSchema = dsl.if((data) => typeof data === 'string' && data.length > 20)
+  .and((data) => data.includes('@'))
+  .then('email!')
+  .else('string:1-50');
+
+const r10 = validate(complexSchema, 'short');
+console.log('✅ 短字符串:', r10.valid ? '验证通过' : '验证失败');
+
+const r11 = validate(complexSchema, 'this-is-a-long-email@example.com');
+console.log('✅ 长邮箱:', r11.valid ? '验证通过' : '验证失败');
+
+const r12 = validate(complexSchema, 'this is a very long string without at symbol');
+console.log('✅ 长文本（无@）:', r12.valid ? '验证通过' : '验证失败');
+
+// ============================================
+// 示例6：边界值处理
+// ============================================
+console.log('\n【示例6】边界值处理');
+console.log('----------------------------');
+
+const boundarySchema = dsl.if((data) => data === null || data === undefined || data === '')
+  .message('值不能为空');
+
+const r13 = validate(boundarySchema, 'valid value');
+console.log('✅ 有效值:', r13.valid ? '验证通过' : '验证失败');
+
+const r14 = validate(boundarySchema, '');
+console.log('❌ 空字符串:', r14.valid ? '验证通过' : '验证失败');
+if (!r14.valid) {
+  console.log('   错误:', r14.errors[0].message);
+}
+
+console.log('\n========================================');
+console.log('示例运行完成！');
+console.log('========================================');
+

package/examples/conditional-validate-example.js

@@ -0,0 +1,321 @@
+/**
+ * ConditionalBuilder 快捷验证方法示例
+ *
+ * 展示 .validate() 和 .check() 方法的使用
+ */
+
+const { dsl } = require('../index');
+
+console.log('========================================');
+console.log('ConditionalBuilder - 快捷验证方法示例');
+console.log('========================================\n');
+
+// ============================================
+// 示例1：一行代码验证
+// ============================================
+console.log('【示例1】一行代码验证');
+console.log('----------------------------');
+
+const result1 = dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .validate({ age: 16 });
+
+console.log('验证未成年用户:', result1.valid ? '✅ 通过' : '❌ 失败');
+if (!result1.valid) {
+  console.log('错误:', result1.errors[0].message);
+}
+
+const result2 = dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .validate({ age: 20 });
+
+console.log('验证成年用户:', result2.valid ? '✅ 通过' : '❌ 失败');
+
+// ============================================
+// 示例2：复用验证器
+// ============================================
+console.log('\n【示例2】复用验证器');
+console.log('----------------------------');
+
+const ageValidator = dsl.if(d => d.age < 18).message('未成年用户不能注册');
+
+const users = [
+  { name: '张三', age: 16 },
+  { name: '李四', age: 20 },
+  { name: '王五', age: 17 },
+  { name: '赵六', age: 25 }
+];
+
+users.forEach(user => {
+  const result = ageValidator.validate(user);
+  console.log(`${user.name}(${user.age}岁):`, result.valid ? '✅ 可以注册' : '❌ 不能注册');
+});
+
+// ============================================
+// 示例3：.check() 快速判断
+// ============================================
+console.log('\n【示例3】.check() 快速判断');
+console.log('----------------------------');
+
+const canRegister = dsl.if(d => d.age < 18)
+  .or(d => d.status === 'blocked')
+  .message('不允许注册');
+
+const testUsers = [
+  { name: '用户A', age: 16, status: 'active' },
+  { name: '用户B', age: 20, status: 'blocked' },
+  { name: '用户C', age: 20, status: 'active' }
+];
+
+testUsers.forEach(user => {
+  const isValid = canRegister.check(user);
+  console.log(`${user.name}:`, isValid ? '✅ 允许注册' : '❌ 禁止注册');
+});
+
+// ============================================
+// 示例4：then/else 动态验证
+// ============================================
+console.log('\n【示例4】then/else 动态验证');
+console.log('----------------------------');
+
+const emailValidator = dsl.if(d => d.userType === 'admin')
+  .then('email!')  // 管理员必填
+  .else('email');  // 普通用户可选
+
+// 管理员有邮箱
+const r1 = emailValidator.validate({
+  userType: 'admin',
+  email: 'admin@example.com'
+});
+console.log('管理员有邮箱:', r1.valid ? '✅ 通过' : '❌ 失败');
+
+// 管理员无邮箱
+const r2 = emailValidator.validate({
+  userType: 'admin',
+  email: ''
+});
+console.log('管理员无邮箱:', r2.valid ? '✅ 通过' : '❌ 失败');
+
+// 普通用户无邮箱
+const r3 = emailValidator.validate({
+  userType: 'user',
+  email: ''
+});
+console.log('普通用户无邮箱:', r3.valid ? '✅ 通过' : '❌ 失败');
+
+// ============================================
+// 示例5：非对象类型验证
+// ============================================
+console.log('\n【示例5】非对象类型验证');
+console.log('----------------------------');
+
+// 验证字符串
+const stringValidator = dsl.if(d => typeof d === 'string' && d.includes('@'))
+  .then('email!')
+  .else('string:1-50');
+
+const r4 = stringValidator.validate('test@example.com');
+console.log('邮箱格式:', r4.valid ? '✅ 通过' : '❌ 失败');
+
+const r5 = stringValidator.validate('just a text');
+console.log('普通文本:', r5.valid ? '✅ 通过' : '❌ 失败');
+
+// 验证数组
+const arrayValidator = dsl.if(d => Array.isArray(d) && d.length > 5)
+  .message('数组最多5个元素');
+
+const r6 = arrayValidator.validate([1, 2, 3]);
+console.log('3个元素:', r6.valid ? '✅ 通过' : '❌ 失败');
+
+const r7 = arrayValidator.validate([1, 2, 3, 4, 5, 6]);
+console.log('6个元素:', r7.valid ? '✅ 通过' : '❌ 失败');
+if (!r7.valid) {
+  console.log('错误:', r7.errors[0].message);
+}
+
+// ============================================
+// 示例6：多语言支持
+// ============================================
+console.log('\n【示例6】多语言支持');
+console.log('----------------------------');
+
+const i18nValidator = dsl.if(d => d.age < 18)
+  .message('conditional.underAge');
+
+// 中文
+const r8 = i18nValidator.validate({ age: 16 }, { locale: 'zh-CN' });
+console.log('中文:', r8.valid ? '✅ 通过' : '❌ 失败');
+if (!r8.valid) {
+  console.log('错误:', r8.errors[0].message);
+}
+
+// 英文
+const r9 = i18nValidator.validate({ age: 16 }, { locale: 'en-US' });
+console.log('英文:', r9.valid ? '✅ 通过' : '❌ 失败');
+if (!r9.valid) {
+  console.log('错误:', r9.errors[0].message);
+}
+
+// ============================================
+// 示例7：实际业务场景
+// ============================================
+console.log('\n【示例7】实际业务场景 - 用户注册');
+console.log('----------------------------');
+
+// 创建多个验证器
+const validators = {
+  age: dsl.if(d => d.age < 18)
+    .message('未成年用户不能注册'),
+
+  email: dsl.if(d => d.userType === 'admin')
+    .then('email!')
+    .else('email'),
+
+  phone: dsl.if(d => d.userType === 'vip')
+    .then('string:11!')
+    .else(null)
+};
+
+// 验证用户
+function validateUser(userData) {
+  console.log(`\n验证用户: ${userData.username}`);
+
+  // 年龄检查
+  if (!validators.age.check(userData)) {
+    console.log('❌ 年龄验证失败');
+    return false;
+  }
+
+  // 邮箱检查
+  const emailResult = validators.email.validate(userData);
+  if (!emailResult.valid) {
+    console.log('❌ 邮箱验证失败:', emailResult.errors[0].message);
+    return false;
+  }
+
+  // 手机号检查
+  const phoneResult = validators.phone.validate(userData);
+  if (!phoneResult.valid) {
+    console.log('❌ 手机号验证失败:', phoneResult.errors[0].message);
+    return false;
+  }
+
+  console.log('✅ 所有验证通过');
+  return true;
+}
+
+// 测试数据
+const userData1 = {
+  username: 'admin1',
+  age: 25,
+  userType: 'admin',
+  email: 'admin@example.com'
+};
+
+const userData2 = {
+  username: 'user1',
+  age: 16,
+  userType: 'user',
+  email: ''
+};
+
+validateUser(userData1);
+validateUser(userData2);
+
+// ============================================
+// 示例8：异步验证 - .validateAsync()
+// ============================================
+console.log('\n【示例8】异步验证 - .validateAsync()');
+console.log('----------------------------');
+
+async function asyncRegister() {
+  const ageValidator = dsl.if(d => d.age < 18)
+    .message('未成年用户不能注册');
+
+  // 验证通过
+  try {
+    const data1 = await ageValidator.validateAsync({ age: 20, name: '张三' });
+    console.log('✅ 验证通过:', data1.name);
+  } catch (error) {
+    console.log('❌ 验证失败:', error.message);
+  }
+
+  // 验证失败
+  try {
+    await ageValidator.validateAsync({ age: 16, name: '李四' });
+  } catch (error) {
+    console.log('❌ 验证失败:', error.message);
+  }
+}
+
+asyncRegister();
+
+// ============================================
+// 示例9：断言验证 - .assert()
+// ============================================
+console.log('\n【示例9】断言验证 - .assert()');
+console.log('----------------------------');
+
+function createUser(userData) {
+  try {
+    // 断言验证，失败直接抛错
+    dsl.if(d => d.age < 18)
+      .message('未成年用户不能注册')
+      .assert(userData);
+
+    dsl.if(d => !d.email || d.email.length === 0)
+      .message('邮箱不能为空')
+      .assert(userData);
+
+    console.log(`✅ 用户 ${userData.name} 创建成功`);
+    return { success: true, user: userData };
+  } catch (error) {
+    console.log(`❌ 用户 ${userData.name} 创建失败: ${error.message}`);
+    return { success: false, error: error.message };
+  }
+}
+
+createUser({ name: '张三', age: 20, email: 'zhangsan@example.com' });
+createUser({ name: '李四', age: 16, email: 'lisi@example.com' });
+createUser({ name: '王五', age: 20, email: '' });
+
+// ============================================
+// 示例10：Express 中间件场景（模拟）
+// ============================================
+console.log('\n【示例10】Express 中间件场景（模拟）');
+console.log('----------------------------');
+
+// 模拟 Express 中间件
+async function checkPermission(req, res, next) {
+  try {
+    await dsl.if(d => d.role !== 'admin' && d.role !== 'moderator')
+      .message('权限不足')
+      .validateAsync(req.user);
+
+    console.log('✅ 权限验证通过');
+    next();
+  } catch (error) {
+    console.log('❌ 权限不足:', error.message);
+    res.status = 403;
+    res.error = error.message;
+  }
+}
+
+// 模拟请求
+const mockReq1 = { user: { name: 'admin', role: 'admin' } };
+const mockReq2 = { user: { name: 'user', role: 'user' } };
+const mockRes = { status: 200, error: null };
+const mockNext = () => console.log('   继续处理请求...');
+
+(async () => {
+  console.log('请求1 - 管理员:');
+  await checkPermission(mockReq1, mockRes, mockNext);
+
+  console.log('请求2 - 普通用户:');
+  await checkPermission(mockReq2, mockRes, mockNext);
+})();
+
+console.log('\n========================================');
+console.log('示例运行完成！');
+console.log('========================================');
+

package/examples/i18n-error.examples.js

@@ -0,0 +1,181 @@
+/**
+ * I18nError 使用示例
+ *
+ * 统一的多语言错误抛出机制
+ *
+ * @version 1.1.1
+ */
+
+const { I18nError, dsl, Locale } = require('../index');
+
+console.log('=== I18nError 使用示例 ===\n');
+
+// ========== 1. 基础用法 ==========
+console.log('1. 基础用法：');
+try {
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  console.log('错误:', error.message); // "账户不存在"
+  console.log('代码:', error.code); // "account.notFound"
+}
+
+// ========== 2. 带参数的错误 ==========
+console.log('\n2. 带参数的错误：');
+try {
+  throw I18nError.create('account.insufficientBalance', {
+    balance: 50,
+    required: 100
+  });
+} catch (error) {
+  console.log('错误:', error.message); // "余额不足，当前余额50，需要100"
+}
+
+// ========== 3. 使用 throw 方法 ==========
+console.log('\n3. 使用 throw 方法（直接抛错）：');
+try {
+  I18nError.throw('user.noPermission');
+} catch (error) {
+  console.log('错误:', error.message); // "没有管理员权限"
+}
+
+// ========== 4. 使用 assert 断言 ==========
+console.log('\n4. 使用 assert 断言：');
+const account = { balance: 50 };
+
+try {
+  I18nError.assert(account.balance >= 100, 'account.insufficientBalance', {
+    balance: account.balance,
+    required: 100
+  });
+} catch (error) {
+  console.log('错误:', error.message);
+}
+
+// ========== 5. dsl.error 快捷方法 ==========
+console.log('\n5. dsl.error 快捷方法：');
+try {
+  dsl.error.throw('order.notPaid');
+} catch (error) {
+  console.log('错误:', error.message); // "订单未支付"
+}
+
+// ========== 6. 多语言支持 ==========
+console.log('\n6. 多语言支持：');
+try {
+  // 中文
+  Locale.setLocale('zh-CN');
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  console.log('中文:', error.message); // "账户不存在"
+}
+
+try {
+  // 英文
+  Locale.setLocale('en-US');
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  console.log('英文:', error.message); // "Account not found"
+}
+
+// 恢复中文
+Locale.setLocale('zh-CN');
+
+// ========== 7. 实际业务场景 =========
+console.log('\n7. 实际业务场景：');
+
+// 场景1：账户验证函数
+function getAccount(id) {
+  const account = id === '123' ? { id: '123', balance: 50, status: 'active' } : null;
+
+  // 断言账户存在
+  I18nError.assert(account, 'account.notFound');
+
+  // 断言账户状态
+  I18nError.assert(account.status === 'active', 'account.inactive');
+
+  // 断言余额充足
+  I18nError.assert(
+    account.balance >= 100,
+    'account.insufficientBalance',
+    { balance: account.balance, required: 100 }
+  );
+
+  return account;
+}
+
+try {
+  getAccount('123');
+} catch (error) {
+  console.log('业务错误:', error.message);
+  console.log('错误代码:', error.code);
+}
+
+// 场景2：与 dsl.if 结合
+console.log('\n8. 与 dsl.if 结合使用：');
+function validateUser(user) {
+  // 使用 dsl.if 进行数据验证
+  dsl.if(d => !d)
+    .message('user.notFound')
+    .and(d => !d.isVerified)
+    .message('user.notVerified')
+    .assert(user);
+
+  // 使用 I18nError 进行业务逻辑验证
+  I18nError.assert(user.role === 'admin', 'user.noPermission');
+}
+
+try {
+  validateUser({ isVerified: true, role: 'user' });
+} catch (error) {
+  console.log('验证错误:', error.message);
+}
+
+// ========== 9. Express/Koa 中间件 ==========
+console.log('\n9. Express/Koa 错误处理：');
+
+// Express 错误处理中间件
+function expressErrorHandler(error, req, res, next) {
+  if (error instanceof I18nError) {
+    return res.status(error.statusCode).json(error.toJSON());
+  }
+  next(error);
+}
+
+// 模拟使用
+const mockError = I18nError.create('account.notFound', {}, 404);
+const mockRes = {
+  status: (code) => {
+    console.log('HTTP Status:', code);
+    return mockRes;
+  },
+  json: (data) => {
+    console.log('Response:', JSON.stringify(data, null, 2));
+    return mockRes;
+  }
+};
+
+expressErrorHandler(mockError, {}, mockRes, () => {});
+
+// ========== 10. 自定义状态码 ==========
+console.log('\n10. 自定义状态码：');
+try {
+  throw I18nError.create('user.notFound', {}, 404);
+} catch (error) {
+  console.log('状态码:', error.statusCode); // 404
+  console.log('错误:', error.message);
+}
+
+// ========== 11. 错误检查 ==========
+console.log('\n11. 错误类型检查：');
+try {
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  if (error instanceof I18nError) {
+    console.log('是 I18nError:', true);
+    console.log('是账户不存在:', error.is('account.notFound'));
+    console.log('是用户不存在:', error.is('user.notFound'));
+  }
+}
+
+console.log('\n=== 示例完成 ===');
+