schema-dsl 1.0.9 → 1.1.1

package/index.d.ts

@@ -218,14 +218,82 @@ declare module 'schema-dsl' {
    * ```
    */
   export class DslBuilder {
+    /**
+     * 注册自定义类型（供插件使用）
+     * @param name - 类型名称
+     * @param schema - JSON Schema对象或生成函数
+     * @static
+     * @since v1.1.0
+     *
+     * @example
+     * ```typescript
+     * // 注册自定义类型
+     * DslBuilder.registerType('phone-cn', {
+     *   type: 'string',
+     *   pattern: '^1[3-9]\\d{9}$',
+     *   minLength: 11,
+     *   maxLength: 11
+     * });
+     *
+     * // 在DSL中使用
+     * const schema = dsl({ phone: 'phone-cn!' });
+     * const schema2 = dsl({ contact: 'types:email|phone-cn' });
+     * ```
+     */
+    static registerType(name: string, schema: JSONSchema | (() => JSONSchema)): void;
+
+    /**
+     * 检查类型是否已注册
+     * @param type - 类型名称
+     * @returns 是否已注册
+     * @static
+     * @since v1.1.0
+     *
+     * @example
+     * ```typescript
+     * DslBuilder.hasType('string');     // true (内置)
+     * DslBuilder.hasType('phone-cn');   // false (未注册)
+     * DslBuilder.registerType('phone-cn', { ... });
+     * DslBuilder.hasType('phone-cn');   // true (已注册)
+     * ```
+     */
+    static hasType(type: string): boolean;
+
+    /**
+     * 获取所有已注册的自定义类型
+     * @returns 自定义类型名称数组
+     * @static
+     * @since v1.1.0
+     *
+     * @example
+     * ```typescript
+     * const types = DslBuilder.getCustomTypes();
+     * console.log(types); // ['phone-cn', 'order-id', ...]
+     * ```
+     */
+    static getCustomTypes(): string[];
+
+    /**
+     * 清除所有自定义类型（主要用于测试）
+     * @static
+     * @since v1.1.0
+     *
+     * @example
+     * ```typescript
+     * DslBuilder.clearCustomTypes();
+     * ```
+     */
+    static clearCustomTypes(): void;
+
     /**
      * 构造函数
-     * @param dslString - DSL字符串（如 'email!', 'string:3-32!'）
-     * 
+     * @param dslString - DSL字符串（如 'email!', 'string:3-32!', 'types:string|number'）
+     *
      * @example
      * ```typescript
      * const builder = new DslBuilder('email!');
      * const builder2 = new DslBuilder('string:3-32');
+     * const builder3 = new DslBuilder('types:string|number');
      * ```
      */
     constructor(dslString: string);
@@ -331,11 +399,8 @@ declare module 'schema-dsl' {
      * });
      * ```
      */
-    when(refField: string, options: {
-      is: any;
-      then: DslBuilder | JSONSchema;
-      otherwise?: DslBuilder | JSONSchema;
-    }): this;
+    // ⚠️ DEPRECATED: .when() method removed - use dsl.if() instead
+    // when(refField: string, options: { is: any; then: DslBuilder | JSONSchema; otherwise?: DslBuilder | JSONSchema; }): this;
 
     /**
      * 设置默认值
@@ -1184,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 };
 
@@ -1507,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实例（单例）
    * 
@@ -2788,6 +3088,354 @@ declare module 'schema-dsl' {
    */
   export const VERSION: string;
 
+  /**
+   * 链式条件构建器
+   *
+   * @description 提供流畅的条件判断 API，类似 JavaScript if-else 语句
+   *
+   * @example
+   * ```typescript
+   * import { dsl } from 'schema-dsl';
+   *
+   * // 简单条件 + 错误消息
+   * const schema = dsl({
+   *   email: dsl.if((data) => data.age >= 18)
+   *     .message('未成年用户不能注册')
+   * });
+   *
+   * // 多条件 and
+   * const schema2 = dsl({
+   *   email: dsl.if((data) => data.age >= 18)
+   *     .and((data) => data.userType === 'admin')
+   *     .then('email!')
+   * });
+   *
+   * // 多条件 or
+   * const schema3 = dsl({
+   *   status: dsl.if((data) => data.age < 18)
+   *     .or((data) => data.isBlocked)
+   *     .message('不允许注册')
+   * });
+   * ```
+   */
+  export class ConditionalBuilder {
+    /**
+     * 开始条件判断
+     * @param condition - 条件函数，接收完整数据对象
+     * @returns 当前实例（支持链式调用）
+     */
+    if(condition: (data: any) => boolean): this;
+
+    /**
+     * 添加 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;
+
+    /**
+     * 添加 else-if 分支
+     * @param condition - 条件函数
+     * @returns 当前实例（支持链式调用）
+     */
+    elseIf(condition: (data: any) => boolean): this;
+
+    /**
+     * 设置错误消息（支持多语言 key）
+     *
+     * @version 1.1.1 支持为 .and() 和 .or() 条件设置独立消息
+     *
+     * 条件为 true 时自动抛出此错误
+     *
+     * @param msg - 错误消息或多语言 key
+     * @returns 当前实例（支持链式调用）
+     *
+     * @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;
+
+    /**
+     * 设置满足条件时的 Schema
+     * @param schema - DSL 字符串或 Schema 对象
+     * @returns 当前实例（支持链式调用）
+     */
+    then(schema: string | DslBuilder | JSONSchema): this;
+
+    /**
+     * 设置默认 Schema（所有条件都不满足时）
+     * 可选：不写 else 就是不验证
+     * @param schema - DSL 字符串、Schema 对象或 null
+     * @returns 当前实例（支持链式调用）
+     */
+    else(schema: string | DslBuilder | JSONSchema | null): this;
+
+    /**
+     * 快捷验证方法 - 返回完整验证结果
+     * @param data - 待验证的数据（任意类型）
+     * @param options - 验证选项（可选）
+     * @returns 验证结果 { valid, errors, data }
+     *
+     * @example
+     * ```typescript
+     * // 一行代码验证
+     * const result = dsl.if(d => d.age < 18)
+     *   .message('未成年')
+     *   .validate({ age: 16 });
+     *
+     * // 复用验证器
+     * const validator = dsl.if(d => d.age < 18).message('未成年');
+     * const r1 = validator.validate({ age: 16 });
+     * const r2 = validator.validate({ age: 20 });
+     * ```
+     */
+    validate<T = any>(data: T, options?: ValidateOptions): ValidationResult<T>;
+
+    /**
+     * 异步验证方法 - 失败自动抛出异常
+     * @param data - 待验证的数据
+     * @param options - 验证选项（可选）
+     * @returns 验证通过返回数据，失败抛出异常
+     * @throws ValidationError 验证失败抛出异常
+     *
+     * @example
+     * ```typescript
+     * // 异步验证，失败自动抛错
+     * try {
+     *   const data = await dsl.if(d => d.age < 18)
+     *     .message('未成年')
+     *     .validateAsync({ age: 16 });
+     * } catch (error) {
+     *   console.log(error.message);
+     * }
+     *
+     * // Express 中间件
+     * app.post('/register', async (req, res, next) => {
+     *   try {
+     *     await dsl.if(d => d.age < 18)
+     *       .message('未成年用户不能注册')
+     *       .validateAsync(req.body);
+     *     // 验证通过，继续处理...
+     *   } catch (error) {
+     *     next(error);
+     *   }
+     * });
+     * ```
+     */
+    validateAsync<T = any>(data: T, options?: ValidateOptions): Promise<T>;
+
+    /**
+     * 断言方法 - 同步验证，失败直接抛错
+     * @param data - 待验证的数据
+     * @param options - 验证选项（可选）
+     * @returns 验证通过返回数据
+     * @throws Error 验证失败抛出错误
+     *
+     * @example
+     * ```typescript
+     * // 断言验证，失败直接抛错
+     * try {
+     *   dsl.if(d => d.age < 18)
+     *     .message('未成年')
+     *     .assert({ age: 16 });
+     * } catch (error) {
+     *   console.log(error.message);
+     * }
+     *
+     * // 函数中快速断言
+     * function registerUser(userData: any) {
+     *   dsl.if(d => d.age < 18)
+     *     .message('未成年用户不能注册')
+     *     .assert(userData);
+     *
+     *   // 验证通过，继续处理...
+     *   return createUser(userData);
+     * }
+     * ```
+     */
+    assert<T = any>(data: T, options?: ValidateOptions): T;
+
+    /**
+     * 快捷检查方法 - 只返回 boolean
+     * @param data - 待验证的数据
+     * @returns 验证是否通过
+     *
+     * @example
+     * ```typescript
+     * // 快速判断
+     * const isValid = dsl.if(d => d.age < 18)
+     *   .message('未成年')
+     *   .check({ age: 16 });
+     * // => false
+     *
+     * // 断言场景
+     * if (!validator.check(userData)) {
+     *   console.log('验证失败');
+     * }
+     * ```
+     */
+    check(data: any): boolean;
+  }
+
+  /**
+   * dsl 函数扩展：条件判断（支持两种方式）
+   */
+  export interface DslFunction {
+    /**
+     * 方式一：函数条件（运行时动态判断）
+     *
+     * 创建链式条件构建器，在验证时根据实际数据动态判断
+     *
+     * @param condition - 条件函数，接收完整数据对象
+     * @returns ConditionalBuilder 实例
+     *
+     * @example 简单条件 + 错误消息
+     * ```typescript
+     * const schema = dsl({
+     *   age: 'number!',
+     *   status: dsl.if((data) => data.age < 18)
+     *     .message('未成年用户不能注册')
+     * });
+     * ```
+     *
+     * @example 条件 + then/else（动态Schema）
+     * ```typescript
+     * const schema = dsl({
+     *   userType: 'string!',
+     *   email: dsl.if((data) => data.userType === 'admin')
+     *     .then('email!')  // 管理员必填
+     *     .else('email')   // 普通用户可选
+     * });
+     * ```
+     *
+     * @example 多条件组合
+     * ```typescript
+     * const schema = dsl({
+     *   email: dsl.if((data) => data.age >= 18)
+     *     .and((data) => data.userType === 'admin')
+     *     .then('email!')
+     *     .else('email')
+     * });
+     * ```
+     */
+    if(condition: (data: any) => boolean): ConditionalBuilder;
+
+    /**
+     * 方式二：字段条件（Schema 定义时静态判断）
+     *
+     * 基于字段值的静态布尔条件判断
+     *
+     * @param conditionField - 条件字段名
+     * @param thenSchema - 条件为 true 时的 Schema
+     * @param elseSchema - 条件为 false 时的 Schema
+     * @returns 条件结构对象
+     *
+     * @example 基于字段值的条件
+     * ```typescript
+     * const schema = dsl({
+     *   isVip: 'boolean',
+     *   discount: dsl.if('isVip', 'number:0-50', 'number:0-10')
+     * });
+     * ```
+     */
+    if(conditionField: string, thenSchema: string | DslBuilder | JSONSchema, elseSchema?: string | DslBuilder | JSONSchema): any;
+  }
+
   /**
    * 默认导出（dsl函数）
    *