schema-dsl 1.0.8 → 1.1.0

package/index.d.ts

@@ -112,6 +112,35 @@ declare module 'schema-dsl' {
     field?: string;
   }
 
+  /**
+   * 验证选项
+   *
+   * @description validate() 和 Validator.validate() 的配置选项
+   *
+   * @example
+   * ```typescript
+   * const options: ValidateOptions = {
+   *   format: true,
+   *   locale: 'zh-CN',
+   *   messages: {
+   *     min: '至少需要 {{#limit}} 个字符'
+   *   }
+   * };
+   *
+   * const result = validate(schema, data, options);
+   * ```
+   */
+  export interface ValidateOptions {
+    /** 是否格式化错误（默认true） */
+    format?: boolean;
+    /** 动态指定语言（如 'zh-CN', 'en-US', 'ja-JP', 'es-ES', 'fr-FR'） */
+    locale?: string;
+    /** 自定义错误消息 */
+    messages?: ErrorMessages;
+    /** 扩展选项 */
+    [key: string]: any;
+  }
+
   /**
    * 错误消息对象
    * 
@@ -189,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);
@@ -302,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;
 
     /**
      * 设置默认值
@@ -1257,9 +1351,27 @@ declare module 'schema-dsl' {
      * 验证数据
      * @param schema - JSON Schema对象
      * @param data - 要验证的数据
+     * @param options - 验证选项
      * @returns 验证结果
+     *
+     * @example
+     * ```typescript
+     * const validator = new Validator();
+     *
+     * // 使用默认语言
+     * const result1 = validator.validate(schema, data);
+     *
+     * // 动态指定语言
+     * const result2 = validator.validate(schema, data, { locale: 'zh-CN' });
+     *
+     * // 自定义错误消息
+     * const result3 = validator.validate(schema, data, {
+     *   locale: 'zh-CN',
+     *   messages: { min: '至少{{#limit}}个字符' }
+     * });
+     * ```
      */
-    validate<T = any>(schema: JSONSchema, data: any): ValidationResult<T>;
+    validate<T = any>(schema: JSONSchema, data: any, options?: ValidateOptions): ValidationResult<T>;
 
     /**
      * 获取底层ajv实例
@@ -1300,14 +1412,25 @@ declare module 'schema-dsl' {
    * import { dsl, validate } from 'schema-dsl';
    *
    * const schema = dsl({ email: 'email!' });
-   * const result = validate(schema, { email: 'test@example.com' });
-   * 
-   * if (result.valid) {
+   *
+   * // 基本验证
+   * const result1 = validate(schema, { email: 'test@example.com' });
+   *
+   * // 指定语言
+   * const result2 = validate(schema, { email: 'invalid' }, { locale: 'zh-CN' });
+   *
+   * if (result2.valid) {
    *   console.log('验证通过');
+   * } else {
+   *   console.log('错误:', result2.errors); // 中文错误消息
    * }
    * ```
    */
-  export function validate<T = any>(schema: JSONSchema | SchemaIO, data: any): ValidationResult<T>;
+  export function validate<T = any>(
+    schema: JSONSchema | SchemaIO,
+    data: any,
+    options?: ValidateOptions
+  ): ValidationResult<T>;
 
   /**
    * 便捷异步验证方法（推荐）
@@ -2730,6 +2853,266 @@ 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 条件（与前一个条件组合）
+     * @param condition - 条件函数
+     * @returns 当前实例（支持链式调用）
+     */
+    and(condition: (data: any) => boolean): this;
+
+    /**
+     * 添加 OR 条件（与前一个条件组合）
+     * @param condition - 条件函数
+     * @returns 当前实例（支持链式调用）
+     */
+    or(condition: (data: any) => boolean): this;
+
+    /**
+     * 添加 else-if 分支
+     * @param condition - 条件函数
+     * @returns 当前实例（支持链式调用）
+     */
+    elseIf(condition: (data: any) => boolean): this;
+
+    /**
+     * 设置错误消息（支持多语言 key）
+     * 条件为 true 时自动抛出此错误
+     * @param msg - 错误消息或多语言 key
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * // 如果是未成年人（条件为true），抛出错误
+     * dsl.if((data) => data.age < 18)
+     *   .message('未成年用户不能注册')
+     * ```
+     */
+    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函数）
    * 

package/index.js

@@ -15,6 +15,7 @@ const ErrorFormatter = require('./lib/core/ErrorFormatter');
 const CacheManager = require('./lib/core/CacheManager');
 const DslBuilder = require('./lib/core/DslBuilder');
 const PluginManager = require('./lib/core/PluginManager');
+const ConditionalBuilder = require('./lib/core/ConditionalBuilder');
 
 // ========== 错误消息系统 ==========
 const ErrorCodes = require('./lib/core/ErrorCodes');
@@ -29,7 +30,23 @@ const dsl = require('./lib/adapters/DslAdapter');
 
 // 挂载静态方法 (v2.1.0)
 dsl.match = dsl.DslAdapter.match;
-dsl.if = dsl.DslAdapter.if;
+
+// ✅ 智能 dsl.if：根据参数类型选择实现
+dsl.if = function(...args) {
+  // 如果第一个参数是函数 → 使用新的 ConditionalBuilder（链式API）
+  if (typeof args[0] === 'function') {
+    return ConditionalBuilder.start(args[0]);
+  }
+
+  // 如果第一个参数是字符串且有3个参数 → 使用原有的字段条件实现
+  // dsl.if('fieldName', thenSchema, elseSchema)
+  if (typeof args[0] === 'string' && args.length >= 2) {
+    return dsl.DslAdapter.if(args[0], args[1], args[2]);
+  }
+
+  // 其他情况 → 调用 ConditionalBuilder 让它抛出正确的错误
+  return ConditionalBuilder.start(args[0]);
+};
 
 /**
  * 全局配置
@@ -128,16 +145,25 @@ function getDefaultValidator() {
  * 便捷验证方法（使用默认Validator）
  * @param {Object} schema - JSON Schema对象
  * @param {*} data - 待验证数据
+ * @param {Object} [options] - 验证选项
+ * @param {boolean} [options.format=true] - 是否格式化错误
+ * @param {string} [options.locale] - 动态指定语言（如 'zh-CN', 'en-US'）
+ * @param {Object} [options.messages] - 自定义错误消息
  * @returns {Object} 验证结果
  *
  * @example
  * const { validate, dsl } = require('schema-dsl');
  *
  * const schema = dsl({ email: 'email!' });
- * const result = validate(schema, { email: 'test@example.com' });
+ *
+ * // 基本验证
+ * const result1 = validate(schema, { email: 'test@example.com' });
+ *
+ * // 指定语言
+ * const result2 = validate(schema, { email: 'invalid' }, { locale: 'zh-CN' });
  */
-function validate(schema, data) {
-  return getDefaultValidator().validate(schema, data);
+function validate(schema, data, options) {
+  return getDefaultValidator().validate(schema, data, options);
 }
 
 // ========== 工具函数 ==========
@@ -177,6 +203,7 @@ module.exports = {
   // 核心类
   JSONSchemaCore,
   Validator,
+  DslBuilder,                  // v1.1.0 新增：导出DslBuilder供插件使用
 
   // 便捷方法（推荐）
   validate,                    // 便捷验证（单例）

package/lib/adapters/DslAdapter.js

@@ -349,7 +349,7 @@ class DslAdapter {
         // 占位Schema，确保字段存在
         fieldSchema = { description: `Depends on ${value.field}` };
       }
-      // 2. If 结构 (dsl.if)
+      // 2. If 结构 (dsl.if - 旧版本)
       else if (value && value._isIf) {
         const ifSchema = this._buildIfSchema(value.condition, fieldKey, value.then, value.else);
         if (ifSchema) {
@@ -358,20 +358,29 @@ class DslAdapter {
         }
         fieldSchema = { description: `Conditional field based on ${value.condition}` };
       }
-      // 3. DslBuilder 实例（链式调用结果）
+      // 3. ConditionalBuilder 结构 (dsl.if - 新版本)
+      else if (value && value._isConditional) {
+        // 调用 toSchema() 转换为 Schema 对象
+        const conditionalSchema = typeof value.toSchema === 'function'
+          ? value.toSchema()
+          : value;
+        // 保存条件链，留待 Validator 执行
+        fieldSchema = conditionalSchema;
+      }
+      // 4. DslBuilder 实例（链式调用结果）
       else if (value instanceof DslBuilder) {
         fieldSchema = value.toSchema();
       }
-      // 4. 纯字符串 DSL
+      // 5. 纯字符串 DSL
       else if (typeof value === 'string') {
         const builder = new DslBuilder(value);
         fieldSchema = builder.toSchema();
       }
-      // 5. 嵌套对象
+      // 6. 嵌套对象
       else if (typeof value === 'object' && !Array.isArray(value) && value !== null) {
         fieldSchema = this.parseObject(value);
       }
-      // 6. 其他类型（保留原样）
+      // 7. 其他类型（保留原样）
       else {
         fieldSchema = value;
       }