schema-dsl 1.0.9 → 1.1.1

package/lib/core/DslBuilder.js

@@ -23,6 +23,87 @@ const Locale = require('./Locale');
 const patterns = require('../config/patterns');
 
 class DslBuilder {
+  /**
+   * 静态属性：存储用户自定义类型（插件注册）
+   * @private
+   * @type {Map<string, Object|Function>}
+   */
+  static _customTypes = new Map();
+
+  /**
+   * 注册自定义类型（供插件使用）
+   * @param {string} name - 类型名称
+   * @param {Object|Function} schema - JSON Schema对象 或 生成函数
+   * @throws {Error} 类型名称无效时抛出错误
+   *
+   * @example
+   * // 插件中注册自定义类型
+   * DslBuilder.registerType('phone-cn', {
+   *   type: 'string',
+   *   pattern: '^1[3-9]\\d{9}$'
+   * });
+   *
+   * // 在DSL中使用
+   * dsl('phone-cn!')  // ✅ 可用
+   * dsl('types:string|phone-cn')  // ✅ 可用
+   */
+  static registerType(name, schema) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Type name must be a non-empty string');
+    }
+
+    if (!schema || (typeof schema !== 'object' && typeof schema !== 'function')) {
+      throw new Error('Schema must be an object or function');
+    }
+
+    this._customTypes.set(name, schema);
+  }
+
+  /**
+   * 检查类型是否已注册（内置或自定义）
+   * @param {string} type - 类型名称
+   * @returns {boolean}
+   *
+   * @example
+   * DslBuilder.hasType('string')  // true (内置)
+   * DslBuilder.hasType('phone-cn')  // false (未注册)
+   *
+   * DslBuilder.registerType('phone-cn', { ... });
+   * DslBuilder.hasType('phone-cn')  // true (已注册)
+   */
+  static hasType(type) {
+    // 检查自定义类型
+    if (this._customTypes.has(type)) {
+      return true;
+    }
+
+    // 检查内置类型
+    const builtInTypes = [
+      'string', 'number', 'integer', 'boolean', 'object', 'array', 'null',
+      'email', 'url', 'uuid', 'date', 'datetime', 'time',
+      'ipv4', 'ipv6', 'binary', 'objectId', 'hexColor', 'macAddress',
+      'cron', 'slug', 'alphanum', 'lower', 'upper', 'json', 'port',
+      'phone', 'idCard', 'creditCard', 'licensePlate', 'postalCode', 'passport', 'any'
+    ];
+
+    return builtInTypes.includes(type);
+  }
+
+  /**
+   * 获取所有已注册的自定义类型
+   * @returns {Array<string>}
+   */
+  static getCustomTypes() {
+    return Array.from(this._customTypes.keys());
+  }
+
+  /**
+   * 清除所有自定义类型（主要用于测试）
+   */
+  static clearCustomTypes() {
+    this._customTypes.clear();
+  }
+
   /**
    * 创建 DslBuilder 实例
    * @param {string} dslString - DSL字符串，如 'string:3-32!' 或 'email!'
@@ -63,6 +144,26 @@ class DslBuilder {
    * @returns {Object} JSON Schema对象
    */
   _parseSimple(dsl) {
+    // 🔴 处理跨类型联合：types:type1|type2|type3
+    if (dsl.startsWith('types:')) {
+      const typesStr = dsl.substring(6); // 去掉 'types:' 前缀
+      const types = typesStr.split('|').map(t => t.trim()).filter(t => t);
+
+      if (types.length === 0) {
+        throw new Error('types: requires at least one type');
+      }
+
+      if (types.length === 1) {
+        // 只有一个类型，直接解析（避免不必要的oneOf）
+        return this._parseSimple(types[0]);
+      }
+
+      // 多个类型，生成oneOf结构
+      return {
+        oneOf: types.map(type => this._parseSimple(type))
+      };
+    }
+
     // 处理数组类型：array:1-10 或 array<string>
     if (dsl.startsWith('array')) {
       const schema = { type: 'array' };
@@ -233,6 +334,18 @@ class DslBuilder {
    * @private
    */
   _getBaseType(type) {
+    // 🔴 优先查询自定义类型（插件注册的）
+    if (DslBuilder._customTypes.has(type)) {
+      const customSchema = DslBuilder._customTypes.get(type);
+      // 如果是函数，调用它生成Schema
+      if (typeof customSchema === 'function') {
+        return customSchema();
+      }
+      // 否则返回Schema对象的深拷贝（避免污染）
+      return JSON.parse(JSON.stringify(customSchema));
+    }
+
+    // 🔴 查询内置类型
     const typeMap = {
       'string': { type: 'string' },
       'number': { type: 'number' },

package/lib/core/Locale.js

@@ -63,12 +63,16 @@ class Locale {
 
   /**
    * 获取错误消息模板
-   * @param {string} type - 错误类型
+   * @param {string} type - 错误类型或消息字符串
    * @param {Object} [customMessages] - 自定义消息
+   * @param {string} [locale] - 指定语言（可选，默认使用当前语言）
    * @returns {string} 消息模板
    */
-  static getMessage(type, customMessages = {}) {
-    // 优先级: 自定义消息 > 全局自定义消息 > 语言包 > 默认消息
+  static getMessage(type, customMessages = {}, locale = null) {
+    // 使用指定的语言或当前全局语言
+    const targetLocale = locale || this.currentLocale;
+
+    // 优先级: 自定义消息 > 全局自定义消息 > 语言包 > ErrorCodes > 原字符串
 
     // 1. 自定义消息
     if (customMessages[type]) {
@@ -80,8 +84,8 @@ class Locale {
       return this.customMessages[type];
     }
 
-    // 3. 语言包
-    const localeMessages = this.locales[this.currentLocale];
+    // 3. 语言包（使用指定的语言）
+    const localeMessages = this.locales[targetLocale];
     if (localeMessages && localeMessages[type]) {
       return localeMessages[type];
     }
@@ -89,9 +93,10 @@ class Locale {
     // 4. 默认消息（从ErrorCodes获取）
     const errorInfo = getErrorInfo(type);
 
-    // 5. 如果是未知错误，尝试从语言包获取本地化的UNKNOWN_ERROR消息
-    if (errorInfo.code === 'UNKNOWN_ERROR' && localeMessages && localeMessages['UNKNOWN_ERROR']) {
-      return localeMessages['UNKNOWN_ERROR'];
+    // 5. 如果是未知错误，说明不是预定义的错误码
+    if (errorInfo.code === 'UNKNOWN_ERROR') {
+      // ✅ 向后兼容：直接返回原字符串（支持硬编码消息）
+      return type;
     }
 
     return errorInfo.message;

package/lib/core/Validator.js

@@ -135,6 +135,24 @@ class Validator {
       schema = this.dslSchemaCache.get(schema);
     }
 
+    // ✅ 处理 ConditionalBuilder 条件链（运行时条件判断）
+    if (schema && schema._isConditional) {
+      // 顶层 ConditionalBuilder（直接作为 Schema 使用）
+      // 此时验证的是整个数据对象
+      return this._validateConditional(schema, data, null, data, options);
+    }
+
+    // ✅ 预处理包含 ConditionalBuilder 的 Schema
+    if (schema && schema.properties) {
+      const hasConditional = Object.values(schema.properties).some(
+        fieldSchema => fieldSchema && fieldSchema._isConditional
+      );
+
+      if (hasConditional) {
+        return this._validateWithConditionals(schema, data, options);
+      }
+    }
+
     // 检查是否需要移除额外字段 (clean 模式)
     if (schema && schema._removeAdditional) {
       // 创建新的 Validator 实例，启用 removeAdditional
@@ -369,9 +387,239 @@ class Validator {
   }
 
   /**
-   * 静态方法：创建验证器实例
+   * 验证包含 ConditionalBuilder 字段的 Schema
+   * @private
+   * @param {Object} schema - Schema 对象
+   * @param {*} data - 待验证的数据
+   * @param {Object} options - 验证选项
+   * @returns {Object} 验证结果
+   */
+  _validateWithConditionals(schema, data, options = {}) {
+    const errors = [];
+
+    // 深拷贝 schema，避免修改原始对象
+    const cleanSchema = JSON.parse(JSON.stringify(schema));
+    const conditionalFields = {};
+
+    // 提取所有条件字段
+    for (const [fieldName, fieldSchema] of Object.entries(schema.properties || {})) {
+      if (fieldSchema && fieldSchema._isConditional) {
+        conditionalFields[fieldName] = fieldSchema;
+        // 从 cleanSchema 中删除条件字段
+        delete cleanSchema.properties[fieldName];
+      }
+    }
+
+    // 先验证非条件字段
+    const baseResult = this._validateInternal(cleanSchema, data, options);
+    if (!baseResult.valid) {
+      errors.push(...baseResult.errors);
+    }
+
+    // 然后验证每个条件字段
+    for (const [fieldName, conditionalSchema] of Object.entries(conditionalFields)) {
+      // ✅ 传递字段名和完整数据对象
+      const fieldResult = this._validateConditional(
+        conditionalSchema,
+        data,
+        fieldName,
+        data[fieldName],
+        options
+      );
+
+      if (!fieldResult.valid) {
+        // 添加字段路径信息
+        fieldResult.errors.forEach(error => {
+          if (!error.path || error.path === '') {
+            error.path = fieldName;
+          }
+          errors.push(error);
+        });
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      data
+    };
+  }
+
+  /**
+   * 验证条件链（ConditionalBuilder）
+   * @private
+   * @param {Object} conditionalSchema - 条件 Schema 对象
+   * @param {*} data - 完整数据对象（用于条件判断）
+   * @param {string} fieldName - 字段名
+   * @param {*} fieldValue - 字段值（用于验证）
+   * @param {Object} options - 验证选项
+   * @returns {Object} 验证结果
+   */
+  _validateConditional(conditionalSchema, data, fieldName, fieldValue, options = {}) {
+    const locale = options.locale || Locale.getLocale();
+
+    try {
+      // ✅ 遍历条件链，执行第一个匹配的条件
+      // 对于 if/elseIf 链，只执行第一个满足条件的分支
+      for (let i = 0; i < conditionalSchema.conditions.length; i++) {
+        const cond = conditionalSchema.conditions[i];
+
+        // 执行组合条件（支持 and/or），获取结果和失败消息
+        const evaluation = conditionalSchema._evaluateCondition(cond, data);
+        const matched = evaluation.result;
+        const failedMessage = evaluation.failedMessage;
+
+        if (cond.action === 'throw') {
+          // ✅ message 模式：条件为 true 时抛错，条件为 false 时通过
+          if (matched) {
+            // ✅ 条件满足（true），抛出错误
+            // 优先使用具体的失败消息，如果没有则使用整体消息
+            const errorMsg = failedMessage || cond.message;
+            // 支持多语言：如果 message 是 key（如 'conditional.underAge'），从语言包获取翻译
+            // 传递 locale 参数以支持动态语言切换
+            const errorMessage = Locale.getMessage(errorMsg, options.messages || {}, locale);
+
+            return {
+              valid: false,
+              errors: [{
+                message: errorMessage,
+                path: '',
+                keyword: 'conditional',
+                params: { condition: cond.type }
+              }],
+              data
+            };
+          }
+          // 条件不满足（false），继续验证
+          continue;
+        }
+
+        // ✅ then/else 模式：找到第一个满足的条件就执行并返回
+        if (matched) {
+          // 条件满足，执行 then Schema
+          if (cond.then !== undefined && cond.then !== null) {
+            return this._executeThenBranch(cond.then, data, fieldValue, fieldName, options);
+          }
+
+          // 条件满足但没有 then，表示验证通过
+          return {
+            valid: true,
+            errors: [],
+            data
+          };
+        }
+
+        // ✅ 如果是 if/elseIf 条件不满足，继续检查下一个 elseIf
+        // 这样就支持了 if...elseIf...elseIf...else 链
+      }
+
+      // ✅ 所有条件都不满足，执行 else
+      if (conditionalSchema.else !== undefined) {
+        if (conditionalSchema.else === null) {
+          // else 为 null，表示跳过验证
+          return {
+            valid: true,
+            errors: [],
+            data
+          };
+        }
+
+        // 执行 else Schema
+        return this._executeThenBranch(conditionalSchema.else, data, fieldValue, fieldName, options);
+      }
+
+      // 没有 else，表示不验证
+      return {
+        valid: true,
+        errors: [],
+        data
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [{
+          message: `Conditional validation error: ${error.message}`,
+          path: '',
+          keyword: 'conditional'
+        }],
+        data
+      };
+    }
+  }
+
+  /**
+   * 执行 then 分支（提取公共逻辑）
+   * @private
+   * @param {*} thenSchema - then 分支的 Schema
+   * @param {*} data - 完整数据对象（用于嵌套条件判断）
+   * @param {*} fieldValue - 字段值（用于验证）
+   * @param {string} fieldName - 字段名
+   * @param {Object} options - 验证选项
+   */
+  _executeThenBranch(thenSchema, data, fieldValue, fieldName, options) {
+    const DslBuilder = require('./DslBuilder');
+
+    // ✅ 如果是 ConditionalBuilder 实例（未调用 toSchema），先转换
+    if (thenSchema && typeof thenSchema.toSchema === 'function') {
+      thenSchema = thenSchema.toSchema();
+    }
+
+    // ✅ 处理嵌套的 ConditionalBuilder（已转换为 Schema 对象）
+    if (thenSchema && thenSchema._isConditional) {
+      // 嵌套的条件构建器，递归处理
+      // 传递完整数据对象用于条件判断，传递字段值用于验证
+      return this._validateConditional(thenSchema, data, fieldName, fieldValue, options);
+    }
+
+    // 如果是字符串，解析为 Schema
+    if (typeof thenSchema === 'string') {
+      const builder = new DslBuilder(thenSchema);
+      thenSchema = builder.toSchema();
+    }
+
+    // ✅ 验证字段值
+    return this._validateFieldValue(thenSchema, fieldValue, fieldName, options);
+  }
+
+  /**
+   * 验证字段值（处理空字符串和 undefined）
+   * @private
+   * @param {Object} schema - Schema 对象
+   * @param {*} fieldValue - 字段值
+   * @param {string} fieldName - 字段名
+   * @param {Object} options - 验证选项
+   * @returns {Object} 验证结果
+   */
+  _validateFieldValue(schema, fieldValue, fieldName, options = {}) {
+    // ✅ 检查字段是否必填
+    const isRequired = schema && schema._required === true;
+
+    // ✅ 处理 undefined：可选字段缺失时跳过验证
+    if (!isRequired && fieldValue === undefined) {
+      return {
+        valid: true,
+        errors: [],
+        data: fieldValue
+      };
+    }
+
+    // ✅ 处理空字符串：可选字段的空字符串视为未提供
+    if (!isRequired && fieldValue === '') {
+      return {
+        valid: true,
+        errors: [],
+        data: fieldValue
+      };
+    }
+
+    // 正常验证
+    return this._validateInternal(schema, fieldValue, options);
+  }
+
+  /**
+   * 静态工厂方法
    * @static
-   * @param {Object} options - 配置选项
+   * @param {Object} options - ajv配置选项
    * @returns {Validator} Validator实例
    */
   static create(options) {

package/lib/errors/I18nError.js

@@ -0,0 +1,222 @@
+/**
+ * I18nError - 多语言错误工具类
+ *
+ * 提供统一的多语言错误抛出机制，支持：
+ * - 多语言 key 自动翻译
+ * - 参数插值（如 {{field}}, {{limit}}）
+ * - 自定义错误代码
+ * - Express/Koa 集成
+ *
+ * @module lib/errors/I18nError
+ * @version 1.1.1
+ *
+ * @example 基础用法
+ * const { I18nError } = require('schema-dsl');
+ *
+ * // 抛出多语言错误
+ * throw I18nError.create('error.notFound', { resource: '账户' });
+ * // 中文: "找不到账户"
+ * // 英文: "Account not found"
+ *
+ * @example 业务代码中使用
+ * function getAccount(id) {
+ *   const account = db.findAccount(id);
+ *   if (!account) {
+ *     throw I18nError.create('account.notFound', { accountId: id });
+ *   }
+ *   if (account.balance < 100) {
+ *     throw I18nError.create('account.insufficientBalance', {
+ *       balance: account.balance,
+ *       required: 100
+ *     });
+ *   }
+ *   return account;
+ * }
+ *
+ * @example Express 中间件
+ * app.use((error, req, res, next) => {
+ *   if (error instanceof I18nError) {
+ *     return res.status(error.statusCode).json(error.toJSON());
+ *   }
+ *   next(error);
+ * });
+ */
+
+const Locale = require('../core/Locale');
+const MessageTemplate = require('../core/MessageTemplate');
+
+/**
+ * 多语言错误类
+ *
+ * @class I18nError
+ * @extends Error
+ *
+ * @property {string} name - 错误名称（固定为 'I18nError'）
+ * @property {string} message - 错误消息（已翻译）
+ * @property {string} code - 错误代码（多语言 key）
+ * @property {Object} params - 错误参数（用于插值）
+ * @property {number} statusCode - HTTP 状态码（默认 400）
+ * @property {string} locale - 使用的语言环境
+ */
+class I18nError extends Error {
+  /**
+   * 构造函数
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数（用于插值）
+   * @param {number} statusCode - HTTP 状态码（默认 400）
+   * @param {string} locale - 语言环境（默认使用当前语言）
+   */
+  constructor(code, params = {}, statusCode = 400, locale = null) {
+    // 获取翻译后的消息模板
+    const actualLocale = locale || Locale.getLocale();
+    const template = Locale.getMessage(code, {}, actualLocale);
+
+    // 使用 MessageTemplate 进行参数插值
+    const messageTemplate = new MessageTemplate(template);
+    const message = messageTemplate.render(params || {});
+
+    super(message);
+
+    this.name = 'I18nError';
+    this.code = code;
+    this.params = params || {};
+    this.statusCode = statusCode;
+    this.locale = actualLocale;
+
+    // 保持堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, I18nError);
+    }
+  }
+
+  /**
+   * 静态工厂方法 - 创建并抛出错误
+   *
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @returns {I18nError} 错误实例
+   *
+   * @example
+   * // 创建错误（不抛出）
+   * const error = I18nError.create('error.notFound', { resource: '用户' });
+   *
+   * @example
+   * // 直接抛出
+   * throw I18nError.create('error.notFound', { resource: '用户' });
+   */
+  static create(code, params = {}, statusCode = 400) {
+    return new I18nError(code, params, statusCode);
+  }
+
+  /**
+   * 静态工厂方法 - 快速抛出错误
+   *
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 直接抛出错误
+   *
+   * @example
+   * I18nError.throw('error.notFound', { resource: '用户' });
+   * // 等同于：throw I18nError.create('error.notFound', { resource: '用户' });
+   */
+  static throw(code, params = {}, statusCode = 400) {
+    throw new I18nError(code, params, statusCode);
+  }
+
+  /**
+   * 断言方法 - 条件不满足时抛错
+   *
+   * @param {boolean} condition - 条件表达式
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 条件为 false 时抛出错误
+   *
+   * @example
+   * I18nError.assert(account, 'account.notFound', { accountId: id });
+   * // 等同于：if (!account) throw I18nError.create('account.notFound', { accountId: id });
+   *
+   * @example
+   * I18nError.assert(
+   *   account.balance >= 100,
+   *   'account.insufficientBalance',
+   *   { balance: account.balance, required: 100 }
+   * );
+   */
+  static assert(condition, code, params = {}, statusCode = 400) {
+    if (!condition) {
+      throw new I18nError(code, params, statusCode);
+    }
+  }
+
+  /**
+   * 检查错误是否为指定代码
+   *
+   * @param {string} code - 错误代码
+   * @returns {boolean} 是否匹配
+   *
+   * @example
+   * try {
+   *   // ...
+   * } catch (error) {
+   *   if (error instanceof I18nError && error.is('account.notFound')) {
+   *     // 处理账户不存在的情况
+   *   }
+   * }
+   */
+  is(code) {
+    return this.code === code;
+  }
+
+  /**
+   * 转换为 JSON 格式（用于 API 响应）
+   *
+   * @returns {Object} JSON 对象
+   * @returns {string} return.error - 错误名称
+   * @returns {string} return.code - 错误代码
+   * @returns {string} return.message - 错误消息（已翻译）
+   * @returns {Object} return.params - 错误参数
+   * @returns {number} return.statusCode - 状态码
+   * @returns {string} return.locale - 语言环境
+   *
+   * @example
+   * const json = error.toJSON();
+   * res.status(error.statusCode).json(json);
+   * // {
+   * //   error: 'I18nError',
+   * //   code: 'account.notFound',
+   * //   message: '找不到账户',
+   * //   params: { accountId: '123' },
+   * //   statusCode: 404,
+   * //   locale: 'zh-CN'
+   * // }
+   */
+  toJSON() {
+    return {
+      error: this.name,
+      code: this.code,
+      message: this.message,
+      params: this.params,
+      statusCode: this.statusCode,
+      locale: this.locale
+    };
+  }
+
+  /**
+   * 转换为字符串
+   *
+   * @returns {string} 格式化的错误信息
+   *
+   * @example
+   * console.log(error.toString());
+   * // "I18nError [account.notFound]: 找不到账户"
+   */
+  toString() {
+    return `${this.name} [${this.code}]: ${this.message}`;
+  }
+}
+
+module.exports = I18nError;
+