schema-dsl 1.0.4 → 1.0.5

package/README.md

@@ -96,6 +96,8 @@ validate(schema, data, { locale: 'en-US' });
 **一份定义，多处使用**
 
 ```javascript
+const { dsl, exporters } = require('schema-dsl');
+
 const schema = dsl({ 
   username: 'string:3-32!',
   email: 'email!',
@@ -103,13 +105,16 @@ const schema = dsl({
 });
 
 // 导出 MongoDB Schema
-schema.exportTo('mongodb', { collectionName: 'users' });
+const mongoExporter = new exporters.MongoDBExporter();
+const mongoSchema = mongoExporter.export(schema);
 
 // 导出 MySQL 建表语句
-schema.exportTo('mysql', { tableName: 'users' });
+const mysqlExporter = new exporters.MySQLExporter();
+const mysqlDDL = mysqlExporter.export('users', schema);
 
 // 导出 PostgreSQL 建表语句
-schema.exportTo('postgresql', { tableName: 'users' });
+const pgExporter = new exporters.PostgreSQLExporter();
+const pgDDL = pgExporter.export('users', schema);
 ```
 
 **✅ 独家功能**：从验证规则直接生成数据库结构！
@@ -525,17 +530,82 @@ dsl({
   email: 'email!'.label('用户邮箱'),
   
   // 字段描述
-  bio: 'string:10-500'.description('用户简介，10-500字符'),
+  bio: 'string:10-500'.description('用户简介，10-500字符')
+})
+```
+
+### 条件验证 - dsl.match 和 dsl.if
+
+**根据其他字段的值动态决定验证规则**
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// 1. dsl.match - 根据字段值匹配不同规则（类似 switch-case）
+const contactSchema = dsl({
+  contactType: 'email|phone|wechat',
   
-  // 条件验证
-  discount: 'number'.when('vip', {
-    is: true,
-    then: 'number:10-50!',  // VIP 用户折扣必填
-    otherwise: 'number'      // 普通用户可选
+  // 根据 contactType 的值决定 contact 字段的验证规则
+  contact: dsl.match('contactType', {
+    email: 'email!',           // contactType='email' 时验证邮箱格式
+    phone: 'string:11!',       // contactType='phone' 时验证11位手机号
+    wechat: 'string:6-20!',    // contactType='wechat' 时验证微信号
+    _default: 'string'         // 默认规则（可选）
   })
-})
+});
+
+// ✅ 验证通过
+validate(contactSchema, { contactType: 'email', contact: 'user@example.com' });
+validate(contactSchema, { contactType: 'phone', contact: '13800138000' });
+
+// ❌ 验证失败
+validate(contactSchema, { contactType: 'email', contact: 'invalid' });
+
+
+// 2. dsl.if - 简单条件分支（类似 if-else）
+const vipSchema = dsl({
+  isVip: 'boolean!',
+  
+  // 如果是 VIP，折扣必须在 10-50 之间；否则在 0-10 之间
+  discount: dsl.if('isVip', 'number:10-50!', 'number:0-10')
+});
+
+// ✅ VIP 用户
+validate(vipSchema, { isVip: true, discount: 30 });
+
+// ❌ 非 VIP 用户折扣超过 10
+validate(vipSchema, { isVip: false, discount: 15 });
+
+
+// 3. 实际应用场景：订单验证
+const orderSchema = dsl({
+  paymentMethod: 'alipay|wechat|card|cod',  // cod = 货到付款
+  
+  // 根据支付方式决定支付信息格式
+  paymentInfo: dsl.match('paymentMethod', {
+    alipay: 'email!',                        // 支付宝：邮箱
+    wechat: 'string:20-30',                  // 微信：支付串
+    card: 'string:16-19',                    // 银行卡：卡号
+    cod: 'string:0-0',                       // 货到付款：无需支付信息
+    _default: 'string'
+  }),
+  
+  // 货到付款需要详细地址
+  address: dsl.if('paymentMethod', 
+    'string:10-200!',   // cod = 货到付款时地址必填
+    'string:10-200'     // 其他支付方式地址可选
+  )
+});
 ```
 
+**💡 使用场景**:
+- ✅ 多种联系方式验证（邮箱/手机/微信）
+- ✅ VIP 和普通用户不同的折扣范围
+- ✅ 不同支付方式的支付信息格式
+- ✅ 根据用户类型决定必填字段
+
+**查看完整示例**: [examples/dsl-match-example.js](./examples/dsl-match-example.js)
+
 ---
 
 ## 🔧 核心功能
@@ -653,32 +723,36 @@ const markdown = exporters.MarkdownExporter.export(userSchema, {
 ### 4. 多语言支持
 
 ```javascript
-const { dsl, Locale } = require('schema-dsl');
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
+
+// 方式 1: 从目录加载语言包（推荐）
+dsl.config({
+  i18n: path.join(__dirname, 'i18n/dsl')  // 直接传字符串路径
+});
 
-// 配置语言包
+// 方式 2: 直接传入语言包对象
 dsl.config({
   i18n: {
-    locales: {
-      'zh-CN': {
-        'label.username': '用户名',
-        'label.email': '邮箱地址',
-        'required': '{{#label}}不能为空',
-        'string.min': '{{#label}}长度不能少于{{#limit}}个字符'
-      },
-      'en-US': {
-        'label.username': 'Username',
-        'label.email': 'Email Address',
-        'required': '{{#label}} is required',
-        'string.min': '{{#label}} must be at least {{#limit}} characters'
-      }
+    'zh-CN': {
+      'label.username': '用户名',
+      'label.email': '邮箱地址',
+      'required': '{{#label}}不能为空',
+      'string.min': '{{#label}}长度不能少于{{#limit}}个字符'
+    },
+    'en-US': {
+      'label.username': 'Username',
+      'label.email': 'Email Address',
+      'required': '{{#label}} is required',
+      'string.min': '{{#label}} must be at least {{#limit}} characters'
     }
   }
 });
 
 // 使用 Label Key
 const schema = dsl({
-  username: 'string:3-32!'.label('label.username'),
-  email: 'email!'.label('label.email')
+  username: dsl('string:3-32!').label('label.username'),
+  email: dsl('email!').label('label.email')
 });
 
 // 验证时指定语言
@@ -687,16 +761,44 @@ const result1 = validate(schema, data, { locale: 'zh-CN' });
 
 const result2 = validate(schema, data, { locale: 'en-US' });
 // 错误消息：Username must be at least 3 characters
+```
 
-// 从文件加载语言包
-dsl.config({
-  i18n: {
-    localesPath: './i18n'  // 自动加载 ./i18n/*.js 或 *.json
+### 5. 缓存配置 (v1.0.4+)
+
+```javascript
+const { dsl, config } = require('schema-dsl');
+
+// 配置缓存选项（推荐在使用 DSL 之前调用）
+config({
+  cache: {
+    maxSize: 1000,        // 最大缓存条目数（默认：100）
+    ttl: 7200000,         // 缓存过期时间（毫秒，默认：3600000，即1小时）
+    enabled: true,        // 是否启用缓存（默认：true）
+    statsEnabled: true    // 是否启用统计（默认：true）
   }
 });
+
+// 之后创建的 Schema 将使用新的缓存配置
+const schema = dsl({ name: 'string!' });
+
+// 也可以在 Validator 创建后动态修改配置（向后兼容）
+const { getDefaultValidator } = require('schema-dsl');
+const validator = getDefaultValidator();
+console.log('当前缓存配置:', validator.cache.options);
+
+// 动态修改
+config({
+  cache: { maxSize: 5000 }  // 只修改某个参数
+});
 ```
 
-### 5. 插件系统
+**缓存说明**：
+- Schema 编译结果会被缓存以提高性能
+- 使用 LRU（最近最少使用）淘汰策略
+- 支持 TTL（生存时间）自动过期
+- 可通过 `validator.cache.getStats()` 查看缓存统计信息
+
+### 6. 插件系统
 
 ```javascript
 const { PluginManager } = require('schema-dsl');
@@ -748,7 +850,7 @@ const schema = dsl({
 });
 ```
 
-### 6. 错误处理
+### 7. 错误处理
 
 ```javascript
 const { validate, ValidationError } = require('schema-dsl');

package/docs/i18n.md

@@ -19,12 +19,12 @@ schema-dsl 支持完整的多语言功能，允许你自定义字段标签和错
 const { dsl, validate } = require('schema-dsl');
 const path = require('path');
 
-// 方式 1: 从目录加载（推荐）
+// ✅ 方式 1: 从目录加载（推荐）
 dsl.config({
-  i18n: path.join(__dirname, 'i18n/dsl')
+  i18n: path.join(__dirname, 'i18n/dsl')  // 直接传字符串路径
 });
 
-// 方式 2: 直接传入对象
+// ✅ 方式 2: 直接传入对象
 dsl.config({
   i18n: {
     'zh-CN': require('./i18n/dsl/zh-CN'),

package/docs/performance-benchmark-report.md

@@ -3,7 +3,7 @@
 ## 📋 测试概述
 
 **测试日期**: 2024-01-XX  
-**测试版本**: v1.0.3  
+**测试版本**: v1.0.4  
 **测试环境**: Node.js (运行环境)  
 **对比库**: Joi, Yup, Zod, Ajv  
 

package/docs/typescript-guide.md

@@ -1,6 +1,6 @@
 # TypeScript 使用指南
 
-> **版本**: schema-dsl v1.0.3+  
+> **版本**: schema-dsl v1.0.4+  
 > **更新日期**: 2025-12-31
 
 ---
@@ -550,5 +550,5 @@ dsl.config({
 ---
 
 **更新日期**: 2025-12-31  
-**文档版本**: v1.0.3
+**文档版本**: v1.0.4
 

package/docs/validate-async.md

@@ -474,7 +474,7 @@ new ValidationError(errors, data)
 
 ---
 
-**版本**: v1.0.3  
+**版本**: v1.0.4  
 **更新日期**: 2025-12-29  
 **作者**: SchemaIO Team
 

package/docs/validation-rules-v1.0.2.md

@@ -61,10 +61,17 @@ const schema = {
   }
 };
 
-// 方式2: DSL 语法 (推荐)
+// 方式2: DSL 语法 + 约束（v1.0.3+）
 const schema2 = dsl({
-  code: 'string!',
-  exactLength: 6
+  code: 'string:6!'  // 精确长度 6
+});
+
+// 方式3: 链式调用 JSON Schema
+const schema3 = dsl({
+  code: {
+    type: 'string',
+    exactLength: 6
+  }
 });
 ```
 

package/index.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for schema-dsl v1.0.3
+// Type definitions for schema-dsl v1.0.4
 // Project: https://github.com/vextjs/schema-dsl
 // Definitions by: schema-dsl Team
 
@@ -405,6 +405,381 @@ declare module 'schema-dsl' {
      * ```
      */
     phone(country?: 'cn' | 'us' | 'uk' | 'hk' | 'tw' | 'international'): this;
+
+    /**
+     * 设置格式
+     * @param format - 格式名称 (email, url, uuid, date, date-time, time, ipv4, ipv6等)
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.format('email');
+     * builder.format('uuid');
+     * builder.format('date-time');
+     * ```
+     */
+    format(format: string): this;
+
+    /**
+     * 手机号别名（phoneNumber是phone的别名）
+     * @param country - 国家代码
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.phoneNumber('cn');  // 等同于 phone('cn')
+     * ```
+     */
+    phoneNumber(country?: 'cn' | 'us' | 'uk' | 'hk' | 'tw' | 'international'): this;
+
+    /**
+     * 身份证验证
+     * @param country - 国家代码（目前仅支持 'cn'）
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.idCard('cn');  // 中国身份证18位
+     * ```
+     */
+    idCard(country?: 'cn'): this;
+
+    /**
+     * URL Slug 验证（只能包含小写字母、数字和连字符）
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.slug();  // my-blog-post, hello-world-123
+     * ```
+     */
+    slug(): this;
+
+    /**
+     * 信用卡验证
+     * @param type - 卡类型
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.creditCard('visa');
+     * builder.creditCard('mastercard');
+     * builder.creditCard('amex');
+     * ```
+     */
+    creditCard(type?: 'visa' | 'mastercard' | 'amex' | 'discover' | 'jcb' | 'unionpay'): this;
+
+    /**
+     * 车牌号验证
+     * @param country - 国家代码
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.licensePlate('cn');  // 中国车牌号
+     * ```
+     */
+    licensePlate(country?: 'cn' | 'us' | 'uk'): this;
+
+    /**
+     * 邮政编码验证
+     * @param country - 国家代码
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.postalCode('cn');  // 中国邮政编码6位
+     * builder.postalCode('us');  // 美国邮政编码
+     * ```
+     */
+    postalCode(country?: 'cn' | 'us' | 'uk'): this;
+
+    /**
+     * 护照号码验证
+     * @param country - 国家代码
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * builder.passport('cn');  // 中国护照号
+     * ```
+     */
+    passport(country?: 'cn' | 'us' | 'uk'): this;
+
+    /**
+     * String 最小长度（使用AJV原生minLength）
+     * @param n - 最小长度
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').min(3);  // 最少3个字符
+     * ```
+     */
+    min(n: number): this;
+
+    /**
+     * String 最大长度（使用AJV原生maxLength）
+     * @param n - 最大长度
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').max(32);  // 最多32个字符
+     * ```
+     */
+    max(n: number): this;
+
+    /**
+     * String 精确长度
+     * @param n - 精确长度
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').length(11);  // 必须是11个字符
+     * ```
+     */
+    length(n: number): this;
+
+    /**
+     * String 只能包含字母和数字
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').alphanum();  // 只能是字母和数字
+     * ```
+     */
+    alphanum(): this;
+
+    /**
+     * String 不能包含前后空格
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').trim();  // 不能有前后空格
+     * ```
+     */
+    trim(): this;
+
+    /**
+     * String 必须是小写
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').lowercase();  // 必须全小写
+     * ```
+     */
+    lowercase(): this;
+
+    /**
+     * String 必须是大写
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').uppercase();  // 必须全大写
+     * ```
+     */
+    uppercase(): this;
+
+    /**
+     * Number 小数位数限制
+     * @param n - 最大小数位数
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('number!').precision(2);  // 最多2位小数
+     * ```
+     */
+    precision(n: number): this;
+
+    /**
+     * Number 倍数验证（使用AJV原生multipleOf）
+     * @param n - 必须是此数的倍数
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('number!').multiple(5);  // 必须是5的倍数
+     * ```
+     */
+    multiple(n: number): this;
+
+    /**
+     * Number 端口号验证（1-65535）
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('integer!').port();  // 必须是有效端口号
+     * ```
+     */
+    port(): this;
+
+    /**
+     * Object 要求所有属性都必须存在
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl({ name: 'string', age: 'number' }).requireAll();
+     * ```
+     */
+    requireAll(): this;
+
+    /**
+     * Object 严格模式，不允许额外属性
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl({ name: 'string!' }).strict();
+     * ```
+     */
+    strict(): this;
+
+    /**
+     * Array 不允许稀疏数组
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('array<string>').noSparse();
+     * ```
+     */
+    noSparse(): this;
+
+    /**
+     * Array 必须包含指定元素
+     * @param items - 必须包含的元素数组
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('array<string>').includesRequired(['admin', 'user']);
+     * ```
+     */
+    includesRequired(items: any[]): this;
+
+    /**
+     * Date 自定义日期格式验证
+     * @param fmt - 日期格式（YYYY-MM-DD, YYYY/MM/DD, DD-MM-YYYY, DD/MM/YYYY, ISO8601）
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').dateFormat('YYYY-MM-DD');
+     * ```
+     */
+    dateFormat(fmt: 'YYYY-MM-DD' | 'YYYY/MM/DD' | 'DD-MM-YYYY' | 'DD/MM/YYYY' | 'ISO8601' | string): this;
+
+    /**
+     * Date 必须晚于指定日期
+     * @param date - 比较日期
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('date!').after('2024-01-01');
+     * ```
+     */
+    after(date: string): this;
+
+    /**
+     * Date 必须早于指定日期
+     * @param date - 比较日期
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('date!').before('2025-12-31');
+     * ```
+     */
+    before(date: string): this;
+
+    /**
+     * Pattern 域名验证
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').domain();  // example.com, sub.example.com
+     * ```
+     */
+    domain(): this;
+
+    /**
+     * Pattern IP地址验证（IPv4或IPv6）
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').ip();  // 192.168.1.1 或 2001:0db8:85a3::8a2e:0370:7334
+     * ```
+     */
+    ip(): this;
+
+    /**
+     * Pattern Base64编码验证
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').base64();
+     * ```
+     */
+    base64(): this;
+
+    /**
+     * Pattern JWT令牌验证
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').jwt();
+     * ```
+     */
+    jwt(): this;
+
+    /**
+     * Pattern JSON字符串验证
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').json();
+     * ```
+     */
+    json(): this;
+
+    /**
+     * 日期大于验证
+     * @param date - 对比日期
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').dateGreater('2025-01-01');
+     * ```
+     */
+    dateGreater(date: string): this;
+
+    /**
+     * 日期小于验证
+     * @param date - 对比日期
+     * @returns 当前实例（支持链式调用）
+     *
+     * @example
+     * ```typescript
+     * dsl('string!').dateLess('2025-12-31');
+     * ```
+     */
+    dateLess(date: string): this;
   }
 
   // ========== String 扩展 ==========
@@ -506,6 +881,187 @@ declare module 'schema-dsl' {
        * @deprecated TypeScript 用户请使用 dsl(string).phone()
        */
       phone(country?: 'cn' | 'us' | 'uk' | 'hk' | 'tw' | 'international'): DslBuilder;
+
+      /**
+       * 设置格式
+       * @deprecated TypeScript 用户请使用 dsl(string).format()
+       */
+      format(format: string): DslBuilder;
+
+      /**
+       * 手机号别名
+       * @deprecated TypeScript 用户请使用 dsl(string).phoneNumber()
+       */
+      phoneNumber(country?: 'cn' | 'us' | 'uk' | 'hk' | 'tw' | 'international'): DslBuilder;
+
+      /**
+       * 身份证验证
+       * @deprecated TypeScript 用户请使用 dsl(string).idCard()
+       */
+      idCard(country?: 'cn'): DslBuilder;
+
+      /**
+       * 信用卡验证
+       * @deprecated TypeScript 用户请使用 dsl(string).creditCard()
+       */
+      creditCard(type?: 'visa' | 'mastercard' | 'amex' | 'discover' | 'jcb' | 'unionpay'): DslBuilder;
+
+      /**
+       * 车牌号验证
+       * @deprecated TypeScript 用户请使用 dsl(string).licensePlate()
+       */
+      licensePlate(country?: 'cn' | 'us' | 'uk'): DslBuilder;
+
+      /**
+       * 邮政编码验证
+       * @deprecated TypeScript 用户请使用 dsl(string).postalCode()
+       */
+      postalCode(country?: 'cn' | 'us' | 'uk'): DslBuilder;
+
+      /**
+       * 护照号码验证
+       * @deprecated TypeScript 用户请使用 dsl(string).passport()
+       */
+      passport(country?: 'cn' | 'us' | 'uk'): DslBuilder;
+
+      /**
+       * String 最小长度
+       * @deprecated TypeScript 用户请使用 dsl(string).min()
+       */
+      min(n: number): DslBuilder;
+
+      /**
+       * String 最大长度
+       * @deprecated TypeScript 用户请使用 dsl(string).max()
+       */
+      max(n: number): DslBuilder;
+
+
+      /**
+       * String 只能包含字母和数字
+       * @deprecated TypeScript 用户请使用 dsl(string).alphanum()
+       */
+      alphanum(): DslBuilder;
+
+      /**
+       * String 不能包含前后空格
+       * @deprecated TypeScript 用户请使用 dsl(string).trim()
+       */
+      trim(): DslBuilder;
+
+      /**
+       * String 必须是小写
+       * @deprecated TypeScript 用户请使用 dsl(string).lowercase()
+       */
+      lowercase(): DslBuilder;
+
+      /**
+       * String 必须是大写
+       * @deprecated TypeScript 用户请使用 dsl(string).uppercase()
+       */
+      uppercase(): DslBuilder;
+
+      /**
+       * Number 小数位数限制
+       * @deprecated TypeScript 用户请使用 dsl(string).precision()
+       */
+      precision(n: number): DslBuilder;
+
+      /**
+       * Number 倍数验证
+       * @deprecated TypeScript 用户请使用 dsl(string).multiple()
+       */
+      multiple(n: number): DslBuilder;
+
+      /**
+       * Number 端口号验证
+       * @deprecated TypeScript 用户请使用 dsl(string).port()
+       */
+      port(): DslBuilder;
+
+      /**
+       * Object 要求所有属性都必须存在
+       * @deprecated TypeScript 用户请使用 dsl(obj).requireAll()
+       */
+      requireAll(): DslBuilder;
+
+      /**
+       * Object 严格模式
+       * @deprecated TypeScript 用户请使用 dsl(obj).strict()
+       */
+      strict(): DslBuilder;
+
+      /**
+       * Array 不允许稀疏数组
+       * @deprecated TypeScript 用户请使用 dsl(string).noSparse()
+       */
+      noSparse(): DslBuilder;
+
+      /**
+       * Array 必须包含指定元素
+       * @deprecated TypeScript 用户请使用 dsl(string).includesRequired()
+       */
+      includesRequired(items: any[]): DslBuilder;
+
+      /**
+       * Date 自定义日期格式验证
+       * @deprecated TypeScript 用户请使用 dsl(string).dateFormat()
+       */
+      dateFormat(fmt: string): DslBuilder;
+
+      /**
+       * Date 必须晚于指定日期
+       * @deprecated TypeScript 用户请使用 dsl(string).after()
+       */
+      after(date: string): DslBuilder;
+
+      /**
+       * Date 必须早于指定日期
+       * @deprecated TypeScript 用户请使用 dsl(string).before()
+       */
+      before(date: string): DslBuilder;
+
+      /**
+       * Pattern 域名验证
+       * @deprecated TypeScript 用户请使用 dsl(string).domain()
+       */
+      domain(): DslBuilder;
+
+      /**
+       * Pattern IP地址验证
+       * @deprecated TypeScript 用户请使用 dsl(string).ip()
+       */
+      ip(): DslBuilder;
+
+      /**
+       * Pattern Base64编码验证
+       * @deprecated TypeScript 用户请使用 dsl(string).base64()
+       */
+      base64(): DslBuilder;
+
+      /**
+       * Pattern JWT令牌验证
+       * @deprecated TypeScript 用户请使用 dsl(string).jwt()
+       */
+      jwt(): DslBuilder;
+
+      /**
+       * Pattern JSON字符串验证
+       * @deprecated TypeScript 用户请使用 dsl(string).json()
+       */
+      json(): DslBuilder;
+
+      /**
+       * 日期大于验证
+       * @deprecated TypeScript 用户请使用 dsl(string).dateGreater()
+       */
+      dateGreater(date: string): DslBuilder;
+
+      /**
+       * 日期小于验证
+       * @deprecated TypeScript 用户请使用 dsl(string).dateLess()
+       */
+      dateLess(date: string): DslBuilder;
     }
   }
 
@@ -764,24 +1320,53 @@ declare module 'schema-dsl' {
     export function match(value: any, cases: Record<string, any>): any;
 
     /**
-     * 条件规则
+     * 条件规则 (if)
      * 
-     * @description 根据条件选择不同的Schema（JavaScript中使用 dsl.if）
+     * @description 根据条件字段的值选择不同的Schema
+     * 
+     * JavaScript 中使用: `dsl.if(condition, thenSchema, elseSchema)`
+     * TypeScript 中使用: `dsl['if'](condition, thenSchema, elseSchema)` 或 `dsl._if(...)`
+     * 
+     * @param condition - 条件字段名
+     * @param thenSchema - 条件为 true 时的 Schema
+     * @param elseSchema - 条件为 false 时的 Schema（可选）
      * 
      * @example
      * ```typescript
+     * // TypeScript 中因为 if 是保留字，需要用字符串索引或 _if
      * const schema = dsl({
+     *   isVip: 'boolean',
+     *   discount: dsl['if']('isVip', 'number:10-50!', 'number:0-10')
+     * });
+     * 
+     * // 或者使用 _if 别名
+     * const schema2 = dsl({
      *   age: 'number',
-     *   license: dsl._if(
-     *     (data) => data.age >= 18,
-     *     { hasLicense: 'boolean!' },
-     *     { hasLicense: 'boolean' }
-     *   )
+     *   license: dsl._if('age', 'boolean!', 'boolean')
+     * });
+     * ```
+     * 
+     * @example
+     * ```javascript
+     * // JavaScript 中可以直接使用 dsl.if
+     * const schema = dsl({
+     *   isVip: 'boolean',
+     *   discount: dsl.if('isVip', 'number:10-50!', 'number:0-10')
      * });
      * ```
      */
     export const _if: (condition: any, thenSchema: any, elseSchema?: any) => any;
 
+    /**
+     * 条件规则的别名（用于 TypeScript）
+     * 
+     * @description 因为 TypeScript 中 `if` 是保留字，提供 `_if` 作为别名
+     * 
+     * JavaScript 用户请直接使用 `dsl.if()`
+     * TypeScript 用户可以使用 `dsl['if']()` 或 `dsl._if()`
+     */
+    export { _if as if };
+
     /**
      * 设置默认语言
      * 
@@ -1992,23 +2577,31 @@ declare module 'schema-dsl' {
    * // 添加自定义关键字通常通过 Validator 的 addKeyword 方法
    * const validator = new Validator();
    * const ajv = validator.getAjv();
-   *
-   * // 使用 ajv.addKeyword() 添加自定义关键字
-   * ```
-   */
-  export const CustomKeywords: any;
 
-  // ========== dsl.config 选项（v2.3.0+）==========
+  // ========== dsl.config 选项 ==========
 
   /**
-   * i18n 配置选项（v2.3.0+）
+   * i18n 配置选项
+   *
+   * @description 支持两种配置方式
+   *
+   * @example
+   * ```typescript
+   * // 方式1: 直接传字符串路径
+   * dsl.config({
+   *   i18n: './i18n/dsl'
+   * });
+   *
+   * // 方式2: 传入语言包对象
+   * dsl.config({
+   *   i18n: {
+   *     'zh-CN': { required: '必填' },
+   *     'en-US': { required: 'Required' }
+   *   }
+   * });
+   * ```
    */
-  export interface I18nConfig {
-    /** 语言包目录路径 */
-    localesPath?: string;
-    /** 直接传入的语言包 */
-    locales?: Record<string, ErrorMessages>;
-  }
+  export type I18nConfig = string | Record<string, ErrorMessages>;
 
   /**
    * 缓存配置选项（v2.3.0+）
@@ -2210,6 +2803,142 @@ declare module 'schema-dsl' {
 
   // ========== 默认导出 ==========
 
+  // ========== 验证器扩展 ==========
+
+  /**
+   * 自定义关键字
+   *
+   * @description 扩展ajv的自定义验证关键字
+   *
+   * @example
+   * ```typescript
+   * import { CustomKeywords, Validator } from 'schema-dsl';
+   *
+   * const validator = new Validator();
+   * const ajv = validator.getAjv();
+   * CustomKeywords.registerAll(ajv);
+   * ```
+   */
+  export const CustomKeywords: {
+    /**
+     * 注册所有自定义关键字到ajv实例
+     * @param ajv - ajv实例
+     */
+    registerAll(ajv: any): void;
+
+    /**
+     * 注册元数据关键字
+     * @param ajv - ajv实例
+     */
+    registerMetadataKeywords(ajv: any): void;
+
+    /**
+     * 注册字符串验证器
+     * @param ajv - ajv实例
+     */
+    registerStringValidators(ajv: any): void;
+
+    /**
+     * 注册数字验证器
+     * @param ajv - ajv实例
+     */
+    registerNumberValidators(ajv: any): void;
+
+    /**
+     * 注册对象验证器
+     * @param ajv - ajv实例
+     */
+    registerObjectValidators(ajv: any): void;
+
+    /**
+     * 注册数组验证器
+     * @param ajv - ajv实例
+     */
+    registerArrayValidators(ajv: any): void;
+
+    /**
+     * 注册日期验证器
+     * @param ajv - ajv实例
+     */
+    registerDateValidators(ajv: any): void;
+  };
+
+  // ========== 常量 ==========
+
+  /**
+   * SchemaIO 配置常量
+   *
+   * @description 所有魔法数字和配置项的统一定义
+   *
+   * @example
+   * ```typescript
+   * import { CONSTANTS } from 'schema-dsl';
+   *
+   * console.log(CONSTANTS.VALIDATION.MAX_RECURSION_DEPTH); // 100
+   * console.log(CONSTANTS.CACHE.SCHEMA_CACHE.MAX_SIZE);    // 5000
+   * ```
+   */
+  export const CONSTANTS: {
+    /** 验证配置 */
+    VALIDATION: {
+      /** 递归深度限制 */
+      MAX_RECURSION_DEPTH: number;
+      /** 数组大小限制 */
+      MAX_ARRAY_SIZE: number;
+      /** 字符串长度限制 */
+      MAX_STRING_LENGTH: number;
+      /** 对象属性数量限制 */
+      MAX_OBJECT_KEYS: number;
+      /** 验证超时时间（ms） */
+      DEFAULT_TIMEOUT: number;
+      /** 正则表达式超时（ms） */
+      REGEX_TIMEOUT: number;
+      /** 自定义验证函数超时（ms） */
+      CUSTOM_VALIDATOR_TIMEOUT: number;
+      /** 默认选项 */
+      DEFAULT_OPTIONS: {
+        abortEarly: boolean;
+        stripUnknown: boolean;
+        convert: boolean;
+        presence: string;
+        allowUnknown: boolean;
+        skipFunctions: boolean;
+      };
+    };
+    /** 缓存配置 */
+    CACHE: {
+      /** 缓存开关 */
+      ENABLED: boolean;
+      /** Schema编译缓存 */
+      SCHEMA_CACHE: {
+        /** 最大缓存条目 */
+        MAX_SIZE: number;
+        /** 缓存过期时间（ms） */
+        TTL: number;
+      };
+    };
+    /** 格式配置 */
+    FORMAT: Record<string, any>;
+    /** 类型配置 */
+    TYPES: Record<string, any>;
+    /** 错误配置 */
+    ERRORS: Record<string, any>;
+  };
+
+  /**
+   * 版本信息
+   *
+   * @description 当前schema-dsl版本号
+   *
+   * @example
+   * ```typescript
+   * import { VERSION } from 'schema-dsl';
+   *
+   * console.log(`schema-dsl version: ${VERSION}`); // schema-dsl version: 1.0.4
+   * ```
+   */
+  export const VERSION: string;
+
   /**
    * 默认导出（dsl函数）
    * 

package/index.js

@@ -5,7 +5,7 @@
  * 简洁 + 强大 = 完美平衡
  *
  * @module schema-dsl
- * @version 1.0.3
+ * @version 1.0.4
  */
 
 // ========== 核心层 ==========
@@ -36,6 +36,7 @@ dsl.if = dsl.DslAdapter.if;
  * @param {Object} options - 配置选项
  * @param {Object} options.patterns - 验证规则扩展 (phone, idCard, creditCard)
  * @param {string|Object} options.i18n - 多语言配置（目录路径或语言包对象）
+ * @param {Object} options.cache - 缓存配置
  */
 dsl.config = function (options = {}) {
   const patterns = require('./lib/config/patterns');
@@ -74,6 +75,29 @@ dsl.config = function (options = {}) {
       });
     }
   }
+
+  // 缓存配置 (v1.0.4+)
+  if (options.cache) {
+    // 如果 Validator 还未创建，保存配置供后续创建时使用
+    if (!_defaultValidator) {
+      _validatorOptions.cache = options.cache;
+    } else {
+      // 如果已创建，动态修改现有实例的配置（向后兼容）
+      const cacheOpts = _defaultValidator.cache.options;
+      if (options.cache.maxSize !== undefined) {
+        cacheOpts.maxSize = options.cache.maxSize;
+      }
+      if (options.cache.ttl !== undefined) {
+        cacheOpts.ttl = options.cache.ttl;
+      }
+      if (options.cache.enabled !== undefined) {
+        cacheOpts.enabled = options.cache.enabled;
+      }
+      if (options.cache.statsEnabled !== undefined) {
+        cacheOpts.statsEnabled = options.cache.statsEnabled;
+      }
+    }
+  }
 };
 
 // ========== 导出器层 ==========
@@ -87,6 +111,7 @@ Object.entries(defaultLocales).forEach(([locale, messages]) => {
 
 // ========== 单例Validator ==========
 let _defaultValidator = null;
+let _validatorOptions = {}; // 存储 Validator 配置选项
 
 /**
  * 获取默认Validator实例（单例）
@@ -94,7 +119,7 @@ let _defaultValidator = null;
  */
 function getDefaultValidator() {
   if (!_defaultValidator) {
-    _defaultValidator = new Validator();
+    _defaultValidator = new Validator(_validatorOptions);
   }
   return _defaultValidator;
 }
@@ -128,91 +153,6 @@ const CONSTANTS = require('./lib/config/constants');
 // ========== 自动安装 String 扩展 ==========
 installStringExtensions(dsl);
 
-// ========== 全局配置函数 ==========
-/**
- * 全局配置
- * @param {Object} options - 配置选项
- * @param {Object} options.i18n - 多语言配置
- * @param {string} options.i18n.localesPath - 用户语言包目录路径
- * @param {Object} options.i18n.locales - 直接传入的语言包对象
- * @param {Object} options.cache - 缓存配置
- * @param {number} options.cache.maxSize - 缓存最大条目数
- * @param {number} options.cache.ttl - 缓存过期时间（ms）
- *
- * @example
- * dsl.config({
- *   i18n: {
- *     localesPath: './i18n/labels'
- *   },
- *   cache: {
- *     maxSize: 10000,
- *     ttl: 7200000
- *   }
- * });
- */
-dsl.config = function (options = {}) {
-  // ========== 用户语言包配置 ==========
-  if (options.i18n) {
-    const { localesPath, locales } = options.i18n;
-
-    // 方式 1：从路径加载语言包文件
-    if (localesPath) {
-      const fs = require('fs');
-      const path = require('path');
-
-      const resolvedPath = path.resolve(localesPath);
-
-      if (fs.existsSync(resolvedPath)) {
-        const files = fs.readdirSync(resolvedPath);
-
-        files.forEach(file => {
-          if (file.endsWith('.js') || file.endsWith('.json')) {
-            const locale = path.basename(file, path.extname(file));
-            try {
-              const messages = require(path.join(resolvedPath, file));
-              Locale.addLocale(locale, messages);
-              if (process.env.DEBUG) {
-                console.log(`[schema-dsl] Loaded user locale: ${locale}`);
-              }
-            } catch (error) {
-              console.warn(`[schema-dsl] Failed to load locale ${locale}:`, error.message);
-            }
-          }
-        });
-      } else {
-        console.warn(`[schema-dsl] Locales path not found: ${resolvedPath}`);
-      }
-    }
-
-    // 方式 2：直接传入语言包对象
-    if (locales && typeof locales === 'object') {
-      Object.keys(locales).forEach(locale => {
-        Locale.addLocale(locale, locales[locale]);
-        if (process.env.DEBUG) {
-          console.log(`[schema-dsl] Added user locale: ${locale}`);
-        }
-      });
-    }
-  }
-
-  // ========== 缓存配置 ==========
-  if (options.cache) {
-    const { maxSize, ttl } = options.cache;
-
-    // 更新默认 Validator 的缓存配置
-    if (_defaultValidator) {
-      if (maxSize !== undefined) {
-        _defaultValidator.cache.options.maxSize = maxSize;
-      }
-      if (ttl !== undefined) {
-        _defaultValidator.cache.options.ttl = ttl;
-      }
-      if (process.env.DEBUG) {
-        console.log(`[schema-dsl] Updated cache config: maxSize=${maxSize || 'default'}, ttl=${ttl || 'default'}ms`);
-      }
-    }
-  }
-};
 
 // ========== 导出 ==========
 
@@ -227,6 +167,9 @@ module.exports = {
   dsl,
   DslBuilder,
 
+  // 配置函数 (v1.0.4+)
+  config: dsl.config,
+
   // String 扩展控制
   installStringExtensions: () => installStringExtensions(dsl),
   uninstallStringExtensions,
@@ -272,7 +215,7 @@ module.exports = {
   CONSTANTS,
 
   // 版本信息
-  VERSION: '1.0.3'
+  VERSION: '1.0.4'
 };
 
 

package/lib/core/Validator.js

@@ -28,6 +28,9 @@ class Validator {
    * @param {boolean} options.useDefaults - 是否使用默认值（默认true）
    * @param {boolean} options.coerceTypes - 是否自动类型转换（默认false）
    * @param {boolean} options.removeAdditional - 是否移除额外属性（默认false）
+   * @param {Object} options.cache - 缓存配置选项 (v1.0.4+)
+   * @param {number} options.cache.maxSize - 最大缓存条目数（默认100）
+   * @param {number} options.cache.ttl - 缓存过期时间（毫秒，默认3600000）
    */
   constructor(options = {}) {
     // ajv配置
@@ -49,11 +52,14 @@ class Validator {
     // 注册自定义关键字
     CustomKeywords.registerAll(this.ajv);
 
-    // 编译缓存
-    this.cache = new CacheManager({
-      maxSize: 100,
-      ttl: 3600000 // 1小时
-    });
+    // 编译缓存（支持自定义配置）
+    const cacheOptions = {
+      maxSize: options.cache?.maxSize ?? 100,
+      ttl: options.cache?.ttl ?? 3600000, // 1小时
+      enabled: options.cache?.enabled,
+      statsEnabled: options.cache?.statsEnabled
+    };
+    this.cache = new CacheManager(cacheOptions);
 
     // 错误格式化器
     this.errorFormatter = new ErrorFormatter();
@@ -395,7 +401,7 @@ class Validator {
 
 // Support calling without new
 const ValidatorProxy = new Proxy(Validator, {
-  apply: function(target, thisArg, argumentsList) {
+  apply: function (target, thisArg, argumentsList) {
     return new target(...argumentsList);
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-dsl",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
   "main": "index.js",
   "exports": {