schema-dsl 1.1.0 → 1.1.1

package/index.d.ts

@@ -1249,6 +1249,86 @@ declare module 'schema-dsl' {
      * 
      * JavaScript 用户请直接使用 `dsl.if()`
      * TypeScript 用户可以使用 `dsl['if']()` 或 `dsl._if()`
+     *
+     * @alias _if
+     */
+    export const _if: (condition: any, thenSchema: any, elseSchema?: any) => any;
+
+    /**
+     * 多语言错误快捷方法 (v1.1.1+)
+     *
+     * @description 统一的多语言错误抛出机制
+     *
+     * @example
+     * ```typescript
+     * import { dsl } from 'schema-dsl';
+     *
+     * // 创建错误
+     * const error = dsl.error.create('account.notFound');
+     *
+     * // 直接抛出
+     * dsl.error.throw('account.notFound');
+     *
+     * // 断言风格
+     * dsl.error.assert(account, 'account.notFound');
+     * dsl.error.assert(
+     *   account.balance >= 100,
+     *   'account.insufficientBalance',
+     *   { balance: account.balance, required: 100 }
+     * );
+     * ```
+     */
+    export const error: {
+      /**
+       * 创建多语言错误（不抛出）
+       * @param code - 错误代码（多语言 key）
+       * @param params - 错误参数
+       * @param statusCode - HTTP 状态码
+       * @returns 错误实例
+       */
+      create(
+        code: string,
+        params?: Record<string, any>,
+        statusCode?: number
+      ): I18nError;
+
+      /**
+       * 抛出多语言错误
+       * @param code - 错误代码（多语言 key）
+       * @param params - 错误参数
+       * @param statusCode - HTTP 状态码
+       * @throws I18nError
+       */
+      throw(
+        code: string,
+        params?: Record<string, any>,
+        statusCode?: number
+      ): never;
+
+      /**
+       * 断言方法 - 条件不满足时抛错
+       * @param condition - 条件表达式
+       * @param code - 错误代码（多语言 key）
+       * @param params - 错误参数
+       * @param statusCode - HTTP 状态码
+       * @throws I18nError 条件为 false 时抛出
+       */
+      assert(
+        condition: any,
+        code: string,
+        params?: Record<string, any>,
+        statusCode?: number
+      ): asserts condition;
+    };
+  }
+
+  /**
+   * 条件规则的别名（用于 TypeScript）
+   *
+   * @description 因为 TypeScript 中 `if` 是保留字，提供 `_if` 作为别名
+   *
+   * JavaScript 用户请直接使用 `dsl.if()`
+   * TypeScript 用户可以使用 `dsl['if']()` 或 `dsl._if()`
      */
     export { _if as if };
 
@@ -1572,6 +1652,161 @@ declare module 'schema-dsl' {
     getErrorCount(): number;
   }
 
+  /**
+   * I18nError - 多语言错误类
+   *
+   * @version 1.1.1
+   *
+   * @description 统一的多语言错误抛出机制，支持：
+   * - 多语言 key 自动翻译
+   * - 参数插值（如 {{#balance}}, {{#required}}）
+   * - 自定义错误代码
+   * - Express/Koa 集成
+   *
+   * @example 基础用法
+   * ```typescript
+   * import { I18nError } from 'schema-dsl';
+   *
+   * // 直接抛出
+   * throw I18nError.create('account.notFound');
+   * // 中文: "账户不存在"
+   * // 英文: "Account not found"
+   * ```
+   *
+   * @example 带参数
+   * ```typescript
+   * I18nError.throw('account.insufficientBalance', {
+   *   balance: 50,
+   *   required: 100
+   * });
+   * // 输出: "余额不足，当前余额50，需要100"
+   * ```
+   *
+   * @example 断言风格
+   * ```typescript
+   * function getAccount(id: string) {
+   *   const account = db.findAccount(id);
+   *   I18nError.assert(account, 'account.notFound');
+   *   I18nError.assert(
+   *     account.balance >= 100,
+   *     'account.insufficientBalance',
+   *     { balance: account.balance, required: 100 }
+   *   );
+   *   return account;
+   * }
+   * ```
+   *
+   * @example Express 集成
+   * ```typescript
+   * app.use((error, req, res, next) => {
+   *   if (error instanceof I18nError) {
+   *     return res.status(error.statusCode).json(error.toJSON());
+   *   }
+   *   next(error);
+   * });
+   * ```
+   */
+  export class I18nError extends Error {
+    /** 错误名称（固定为 'I18nError'） */
+    readonly name: 'I18nError';
+
+    /** 错误消息（已翻译） */
+    message: string;
+
+    /** 错误代码（多语言 key） */
+    code: string;
+
+    /** 错误参数（用于插值） */
+    params: Record<string, any>;
+
+    /** HTTP 状态码 */
+    statusCode: number;
+
+    /** 使用的语言环境 */
+    locale: string;
+
+    /**
+     * 构造函数
+     * @param code - 错误代码（多语言 key）
+     * @param params - 错误参数（用于插值）
+     * @param statusCode - HTTP 状态码（默认 400）
+     * @param locale - 语言环境（默认使用当前语言）
+     */
+    constructor(
+      code: string,
+      params?: Record<string, any>,
+      statusCode?: number,
+      locale?: string
+    );
+
+    /**
+     * 静态工厂方法 - 创建错误（不抛出）
+     * @param code - 错误代码
+     * @param params - 错误参数
+     * @param statusCode - HTTP 状态码
+     * @returns 错误实例
+     */
+    static create(
+      code: string,
+      params?: Record<string, any>,
+      statusCode?: number
+    ): I18nError;
+
+    /**
+     * 静态工厂方法 - 直接抛出错误
+     * @param code - 错误代码
+     * @param params - 错误参数
+     * @param statusCode - HTTP 状态码
+     * @throws I18nError
+     */
+    static throw(
+      code: string,
+      params?: Record<string, any>,
+      statusCode?: number
+    ): never;
+
+    /**
+     * 断言方法 - 条件不满足时抛错
+     * @param condition - 条件表达式
+     * @param code - 错误代码
+     * @param params - 错误参数
+     * @param statusCode - HTTP 状态码
+     * @throws I18nError 条件为 false 时抛出
+     */
+    static assert(
+      condition: any,
+      code: string,
+      params?: Record<string, any>,
+      statusCode?: number
+    ): asserts condition;
+
+    /**
+     * 检查错误是否为指定代码
+     * @param code - 错误代码
+     * @returns 是否匹配
+     */
+    is(code: string): boolean;
+
+    /**
+     * 转为 JSON 格式（用于 API 响应）
+     * @returns JSON 对象
+     */
+    toJSON(): {
+      error: string;
+      code: string;
+      message: string;
+      params: Record<string, any>;
+      statusCode: number;
+      locale: string;
+    };
+
+    /**
+     * 转为字符串
+     * @returns 格式化的错误信息
+     */
+    toString(): string;
+  }
+
   /**
    * 获取默认Validator实例（单例）
    * 
@@ -2893,15 +3128,74 @@ declare module 'schema-dsl' {
 
     /**
      * 添加 AND 条件（与前一个条件组合）
+     *
+     * @version 1.1.1 支持为每个 .and() 条件设置独立的错误消息
+     *
      * @param condition - 条件函数
      * @returns 当前实例（支持链式调用）
+     *
+     * @example 基础用法（传统 AND 逻辑）
+     * ```typescript
+     * // 所有条件都为 true 才失败
+     * dsl.if(d => d.age >= 18)
+     *   .and(d => d.userType === 'admin')
+     *   .then('email!')
+     * ```
+     *
+     * @example v1.1.0+ 独立消息（推荐）
+     * ```typescript
+     * // 每个条件都有自己的错误消息
+     * dsl.if(d => !d)
+     *   .message('ACCOUNT_NOT_FOUND')
+     *   .and(d => d.balance < 100)
+     *   .message('INSUFFICIENT_BALANCE')
+     *   .assert(account);
+     *
+     * // 工作原理：链式检查模式
+     * // - 第一个条件失败 → 返回 'ACCOUNT_NOT_FOUND'
+     * // - 第二个条件失败 → 返回 'INSUFFICIENT_BALANCE'
+     * // - 所有条件通过 → 验证成功
+     * ```
+     *
+     * @example 多个 .and() 条件
+     * ```typescript
+     * dsl.if(d => !d)
+     *   .message('NOT_FOUND')
+     *   .and(d => d.status !== 'active')
+     *   .message('INACTIVE')
+     *   .and(d => d.balance < 100)
+     *   .message('INSUFFICIENT')
+     *   .assert(account);
+     * // 依次检查，第一个失败的返回其消息
+     * ```
      */
     and(condition: (data: any) => boolean): this;
 
     /**
      * 添加 OR 条件（与前一个条件组合）
+     *
+     * @version 1.1.1 支持为 .or() 条件设置独立的错误消息
+     *
      * @param condition - 条件函数
      * @returns 当前实例（支持链式调用）
+     *
+     * @example 基础用法
+     * ```typescript
+     * // 任一条件为 true 就失败
+     * dsl.if((data) => data.age < 18)
+     *   .or((data) => data.isBlocked)
+     *   .message('不允许注册')
+     * ```
+     *
+     * @example v1.1.0+ 独立消息
+     * ```typescript
+     * dsl.if(d => d.age < 18)
+     *   .message('未成年用户不能注册')
+     *   .or(d => d.isBlocked)
+     *   .message('账户已被封禁')
+     *   .assert(data);
+     * // 哪个条件为 true 就返回哪个消息
+     * ```
      */
     or(condition: (data: any) => boolean): this;
 
@@ -2914,16 +3208,45 @@ declare module 'schema-dsl' {
 
     /**
      * 设置错误消息（支持多语言 key）
+     *
+     * @version 1.1.1 支持为 .and() 和 .or() 条件设置独立消息
+     *
      * 条件为 true 时自动抛出此错误
+     *
      * @param msg - 错误消息或多语言 key
      * @returns 当前实例（支持链式调用）
      *
-     * @example
+     * @example 基础用法
      * ```typescript
      * // 如果是未成年人（条件为true），抛出错误
      * dsl.if((data) => data.age < 18)
      *   .message('未成年用户不能注册')
      * ```
+     *
+     * @example v1.1.0+ 为 .and() 设置独立消息
+     * ```typescript
+     * dsl.if((data) => !data)
+     *   .message('账户不存在')
+     *   .and((data) => data.balance < 100)
+     *   .message('余额不足')
+     *   .assert(account);
+     * // 每个条件都有自己的错误消息
+     * ```
+     *
+     * @example 链式检查模式说明
+     * ```typescript
+     * // 启用条件：
+     * // 1. 使用 .message() 模式（不是 .then()/.else()）
+     * // 2. root 条件有 .message()
+     * // 3. 有 .and() 条件
+     * // 4. 没有 .or() 条件
+     *
+     * // ✅ 启用链式检查
+     * dsl.if(d => !d).message('A').and(d => d < 100).message('B')
+     *
+     * // ❌ 不启用（有 .or()）
+     * dsl.if(d => !d).message('A').and(d => d < 100).or(d => d > 200).message('B')
+     * ```
      */
     message(msg: string): this;
 

package/index.js

@@ -22,6 +22,10 @@ const ErrorCodes = require('./lib/core/ErrorCodes');
 const MessageTemplate = require('./lib/core/MessageTemplate');
 const Locale = require('./lib/core/Locale');
 
+// ========== 错误类 ==========
+const ValidationError = require('./lib/errors/ValidationError');
+const I18nError = require('./lib/errors/I18nError');
+
 // ========== String 扩展 ==========
 const { installStringExtensions, uninstallStringExtensions } = require('./lib/core/StringExtensions');
 
@@ -48,6 +52,36 @@ dsl.if = function(...args) {
   return ConditionalBuilder.start(args[0]);
 };
 
+// ✅ dsl.error：统一的多语言错误抛出（v1.1.1+）
+dsl.error = {
+  /**
+   * 创建多语言错误（不抛出）
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @returns {I18nError} 错误实例
+   */
+  create: (code, params, statusCode) => I18nError.create(code, params, statusCode),
+
+  /**
+   * 抛出多语言错误
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 直接抛出错误
+   */
+  throw: (code, params, statusCode) => I18nError.throw(code, params, statusCode),
+
+  /**
+   * 断言方法 - 条件不满足时抛错
+   * @param {boolean} condition - 条件表达式
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   */
+  assert: (condition, code, params, statusCode) => I18nError.assert(condition, code, params, statusCode)
+};
+
 /**
  * 全局配置
  * @param {Object} options - 配置选项
@@ -182,8 +216,6 @@ installStringExtensions(dsl);
 
 // ========== 导出 ==========
 
-// 导入 ValidationError
-const ValidationError = require('./lib/errors/ValidationError');
 
 // 导入 validateAsync
 const { validateAsync } = require('./lib/adapters/DslAdapter');
@@ -214,6 +246,7 @@ module.exports = {
 
   // 错误类 (v2.1.0 新增)
   ValidationError,
+  I18nError,                   // v1.1.1 新增：多语言错误类
 
   // 错误消息系统
   ErrorCodes,

package/lib/core/ConditionalBuilder.js

@@ -59,7 +59,7 @@ class ConditionalBuilder {
     this._conditions.push({
       type: 'if',
       condition: conditionFn,
-      combinedConditions: [{ op: 'root', fn: conditionFn }]
+      combinedConditions: [{ op: 'root', fn: conditionFn, message: null }]
     });
 
     return this;
@@ -73,6 +73,7 @@ class ConditionalBuilder {
    * @example
    * dsl.if((data) => data.age >= 18)
    *   .and((data) => data.userType === 'admin')
+   *   .message('必须是管理员')
    *   .then('email!')
    */
   and(conditionFn) {
@@ -85,7 +86,7 @@ class ConditionalBuilder {
       throw new Error('.and() must follow .if() or .elseIf()');
     }
 
-    last.combinedConditions.push({ op: 'and', fn: conditionFn });
+    last.combinedConditions.push({ op: 'and', fn: conditionFn, message: null });
     return this;
   }
 
@@ -109,7 +110,7 @@ class ConditionalBuilder {
       throw new Error('.or() must follow .if() or .elseIf()');
     }
 
-    last.combinedConditions.push({ op: 'or', fn: conditionFn });
+    last.combinedConditions.push({ op: 'or', fn: conditionFn, message: null });
     return this;
   }
 
@@ -136,7 +137,7 @@ class ConditionalBuilder {
     this._conditions.push({
       type: 'elseIf',
       condition: conditionFn,
-      combinedConditions: [{ op: 'root', fn: conditionFn }]
+      combinedConditions: [{ op: 'root', fn: conditionFn, message: null }]
     });
 
     return this;
@@ -144,7 +145,7 @@ class ConditionalBuilder {
 
   /**
    * 设置错误消息（支持多语言 key）
-t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
+   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
    *
    * @param {string} msg - 错误消息或多语言 key
    * @returns {ConditionalBuilder} 当前实例（支持链式调用）
@@ -153,6 +154,13 @@ t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
    * // 如果是未成年人，抛出错误
    * dsl.if((data) => data.age < 18)
    *   .message('未成年用户不能注册')
+   *
+   * @example
+   * // 为 and 条件设置独立消息
+   * dsl.if((data) => !data)
+   *   .message('账户不存在')
+   *   .and((data) => data.balance < 100)
+   *   .message('余额不足')
    */
   message(msg) {
     if (typeof msg !== 'string') {
@@ -164,6 +172,14 @@ t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
       throw new Error('.message() must follow .if() or .elseIf()');
     }
 
+    // 找到最后一个添加的条件（可能是 root、and 或 or）
+    const lastCombined = last.combinedConditions[last.combinedConditions.length - 1];
+    if (lastCombined) {
+      // 为最后一个组合条件设置消息
+      lastCombined.message = msg;
+    }
+
+    // 同时设置整体消息（作为后备）
     last.message = msg;
     last.action = 'throw';  // 有 message 就自动 throw
     return this;
@@ -216,31 +232,117 @@ t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
    * @private
    * @param {Object} conditionObj - 条件对象
    * @param {*} data - 待验证数据对象
-   * @returns {boolean} 条件结果
+   * @returns {Object} { result: boolean, failedMessage: string|null } 条件结果和失败消息
+   *
+   * 语义说明：
+   * - 传统 AND 模式：所有条件都为 true 才失败
+   * - 链式检查模式：root 有 message，且任何 .and() 也有独立 message 时
+   *   → 依次检查，第一个为 true 的失败
    */
   _evaluateCondition(conditionObj, data) {
     try {
+      // 检查是否是链式检查模式：
+      // 1. 必须是 message 模式（action='throw'）
+      // 2. root 条件有 message
+      // 3. 有 .and() 条件（不管是否有独立 message）
+      // 4. 没有 .or() 条件（有 OR 就使用传统逻辑）
+      const isMessageMode = conditionObj.action === 'throw';
+      const rootHasMessage = conditionObj.combinedConditions[0]?.message != null;
+      const hasAndConditions = conditionObj.combinedConditions.some(c => c.op === 'and');
+      const hasOrConditions = conditionObj.combinedConditions.some(c => c.op === 'or');
+      const isChainCheckMode = isMessageMode && rootHasMessage && hasAndConditions && !hasOrConditions;
+
       let result = false;
+      let failedMessage = null;
 
       for (let i = 0; i < conditionObj.combinedConditions.length; i++) {
         const combined = conditionObj.combinedConditions[i];
+        let conditionResult = false;
 
         if (combined.op === 'root') {
           // 第一个条件
-          result = combined.fn(data);
+          conditionResult = combined.fn(data);
+          result = conditionResult;
+
+          if (isChainCheckMode) {
+            // 链式检查模式：第一个条件为 true 就失败
+            if (result) {
+              failedMessage = combined.message || conditionObj.message;
+              return { result: true, failedMessage };
+            }
+          } else {
+            // 传统模式
+            failedMessage = combined.message || conditionObj.message;
+
+            // 如果第一个条件为 false，检查是否有 OR 条件
+            if (!result) {
+              const hasOrConditions = conditionObj.combinedConditions.some(c => c.op === 'or');
+              if (!hasOrConditions) {
+                // 没有 OR 条件，直接通过
+                return { result: false, failedMessage: null };
+              }
+              // 有 OR 条件，继续检查
+            }
+          }
         } else if (combined.op === 'and') {
-          // AND 组合
-          result = result && combined.fn(data);
+          conditionResult = combined.fn(data);
+
+          if (isChainCheckMode) {
+            // 链式检查模式：任一条件为 true 就失败
+            if (conditionResult) {
+              // 使用独立消息，如果没有则使用整体消息
+              failedMessage = combined.message || conditionObj.message;
+              return { result: true, failedMessage };
+            }
+            // 条件为 false，继续检查下一个条件
+          } else {
+            // 传统 AND 模式：所有条件都必须为 true 才失败
+            if (!conditionResult) {
+              // AND 条件为 false
+              // 检查是否有 OR 条件
+              if (hasOrConditions) {
+                // 有 OR 条件，将 result 设为 false，继续检查 OR
+                result = false;
+              } else {
+                // 没有 OR 条件，任一 AND 条件为 false 就验证通过
+                return { result: false, failedMessage: null };
+              }
+            } else {
+              // AND 条件为 true，继续累积
+              result = true;
+            }
+          }
         } else if (combined.op === 'or') {
-          // OR 组合
-          result = result || combined.fn(data);
+          // OR 逻辑：任一条件为 true 就失败
+          if (!result) {
+            conditionResult = combined.fn(data);
+
+            if (conditionResult) {
+              // OR 条件为 true
+              result = true;  // 更新 result
+
+              if (isMessageMode) {
+                // message 模式：立即返回失败
+                failedMessage = combined.message || conditionObj.message;
+                return { result: true, failedMessage };
+              }
+              // then/else 模式：继续累积 result（已经设置为true）
+            }
+          }
         }
       }
 
-      return result;
+      // 返回最终结果
+      if (isChainCheckMode) {
+        // 链式检查模式：所有条件都为 false，验证通过
+        return { result: false, failedMessage: null };
+      } else {
+        // 传统模式：返回累积结果
+        return { result, failedMessage };
+      }
     } catch (error) {
       // 条件函数执行出错，视为不满足
-      return false;
+      return { result: false, failedMessage: null };
     }
   }
 

package/lib/core/Validator.js

@@ -464,16 +464,20 @@ class Validator {
       for (let i = 0; i < conditionalSchema.conditions.length; i++) {
         const cond = conditionalSchema.conditions[i];
 
-        // 执行组合条件（支持 and/or）
-        const matched = conditionalSchema._evaluateCondition(cond, data);
+        // 执行组合条件（支持 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(cond.message, options.messages || {}, locale);
+            const errorMessage = Locale.getMessage(errorMsg, options.messages || {}, locale);
 
             return {
               valid: false,