schema-dsl 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -11,6 +11,9 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.0.6](#v106) | 2026-01-04 | 🚨 紧急修复：TypeScript 类型污染 | [查看详情](#v106) |
+| [v1.0.5](#v105) | 2026-01-04 | 测试覆盖率提升至 97% | [查看详情](#v105) |
+| [v1.0.5](#v105) | 2026-01-04 | 测试覆盖率提升至 97% | [查看详情](#v105) |
 | [v1.0.4](#v104) | 2025-12-31 | TypeScript 完整支持、validateAsync、ValidationError | [查看详情](#v104) |
 | [v1.0.3](#v103) | 2025-12-31 | ⚠️ 破坏性变更：单值语法修复 | [查看详情](#v103) |
 | [v1.0.2](#v102) | 2025-12-31 | 15个新增验证器、完整文档、75个测试 | [查看详情](#v102) |
@@ -19,6 +22,79 @@
 
 ---
 
+## [v1.0.6] - 2026-01-04
+
+### 🚨 Fixed (紧急修复)
+
+#### TypeScript 类型污染问题 ⭐⭐⭐
+
+**问题描述**：
+- v1.0.5 及更早版本中，`index.d.ts` 包含了全局 `interface String` 扩展（第 816-1065 行，共 209 行代码）
+- 这导致 TypeScript 全局类型系统污染，原生 `String.prototype` 方法的类型被错误推断
+- **严重问题**：`String.prototype.trim()` 返回类型从 `string` 被错误推断为 `DslBuilder`
+- 影响所有使用 TypeScript 的项目，导致类型安全问题
+
+**修复内容**：
+- ✅ **完全删除**全局 `interface String` 扩展（移除 209 行类型污染代码）
+- ✅ 添加详细的 TypeScript 使用说明文档
+- ✅ 保证原生 String 方法的类型推断正确（`trim()` 正确返回 `string`）
+
+**对用户的影响**：
+
+1. **JavaScript 用户** ✅ **完全不受影响**
+   ```javascript
+   // 仍然可以正常使用 String 扩展
+   const schema = dsl({ email: 'email!'.label('邮箱') });
+   ```
+
+2. **TypeScript 用户** ⚠️ **需要调整用法**
+   ```typescript
+   // ❌ v1.0.5 及之前（有类型污染 bug）
+   const schema = dsl({ email: 'email!'.label('邮箱') });
+   
+   // ✅ v1.0.6 推荐写法（获得正确类型提示）
+   const schema = dsl({ 
+     email: dsl('email!').label('邮箱') 
+   });
+   ```
+
+**技术细节**：
+- 文件变化：`index.d.ts` 从 2958 行减少到 2749 行
+- 测试状态：所有 677 个测试通过 ✅
+- 类型验证：原生 `String.prototype.trim()` 现在正确返回 `string` 类型
+
+**迁移指南**：
+- JavaScript 项目：无需任何修改
+- TypeScript 项目：使用 `dsl()` 函数包裹字符串字面量获得类型提示
+- 详见：[TypeScript 使用指南](./docs/typescript-guide.md)
+
+---
+
+## [v1.0.5] - 2026-01-04
+
+### Added (新增功能)
+
+#### 测试覆盖率大幅提升 ⭐
+
+- ✅ **新增 5 个核心类的完整测试**
+  - `CacheManager.test.js` - 24 个测试（缓存管理）
+  - `ErrorFormatter.test.js` - 9 个测试（错误格式化）
+  - `JSONSchemaCore.test.js` - 10 个测试（JSON Schema 核心）
+  - `MarkdownExporter.test.js` - 3 个测试（Markdown 导出）
+  - `ErrorCodes.test.js` - 4 个测试（错误代码）
+
+- ✅ **测试统计**
+  - 总测试数：651 → 677（+26 个测试）
+  - 测试覆盖率：92% → 97%（+5%）
+  - 所有核心类现在都有完整测试覆盖
+
+### Fixed (修复)
+
+- ✅ 修复缓存配置支持（4 个参数完整支持）
+- ✅ 简化 i18n 配置（从 3 个方法简化为 2 个）
+
+---
+
 ## [v1.0.4] - 2025-12-31
 
 ### Added (新增功能)

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);
 ```
 
 **✅ 独家功能**：从验证规则直接生成数据库结构！
@@ -215,12 +220,12 @@ console.log(result2.errors);   // 错误列表
 
 ### 1.5 TypeScript 用法 ⭐
 
-**重要**: TypeScript 中使用链式调用需要用 `dsl()` 包裹字符串以获得完整的类型推导：
+**重要**: TypeScript 中**必须**使用 `dsl()` 包裹字符串以获得类型提示（v1.0.6+ 移除了全局 String 类型扩展以避免类型污染）：
 
 ```typescript
 import { dsl, validateAsync, ValidationError } from 'schema-dsl';
 
-// ✅ 推荐：使用 dsl() 包裹字符串获得完整类型提示
+// ✅ 正确：使用 dsl() 包裹字符串获得完整类型提示
 const userSchema = dsl({
   username: dsl('string:3-32!')
     .pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')
@@ -251,10 +256,13 @@ try {
 }
 ```
 
-**为什么要用 `dsl()` 包裹？**
+**为什么必须用 `dsl()` 包裹？**
 - ✅ 完整的类型推导和 IDE 自动提示
-- ✅ 避免 TypeScript 严格模式警告
-- ✅ 更好的开发体验
+- ✅ 避免污染原生 String 类型（v1.0.6+ 重要改进）
+- ✅ 保证 `trim()`、`toLowerCase()` 等原生方法类型正确
+- ✅ 更好的开发体验和类型安全
+
+**JavaScript 用户不受影响**：在 JavaScript 中仍然可以直接使用 `'email!'.label('邮箱')` 语法。
 
 **详细说明**: 请查看 [TypeScript 使用指南](./docs/typescript-guide.md)
 
@@ -525,17 +533,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 +726,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 +764,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 +853,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,7 +1,8 @@
 # TypeScript 使用指南
 
-> **版本**: schema-dsl v1.0.3+  
-> **更新日期**: 2025-12-31
+> **版本**: schema-dsl v1.0.6+  
+> **更新日期**: 2026-01-04  
+> **重要**: v1.0.6 移除了全局 String 类型扩展以避免类型污染
 
 ---
 
@@ -53,28 +54,47 @@ if (result.valid) {
 
 ## 2. TypeScript 中的链式调用
 
-### 2.1 问题说明
+### 2.1 重要变更（v1.0.6）
 
-由于 TypeScript 对全局 `String.prototype` 扩展的类型推导限制，在 `.ts` 文件中直接使用字符串链式调用可能会缺少类型提示：
+**v1.0.6 移除了全局 `interface String` 扩展**，原因：
+- ❌ 全局类型扩展会污染原生 String 类型
+- ❌ 导致 `trim()`、`toLowerCase()` 等原生方法的类型推断错误
+- ❌ 影响所有使用 TypeScript 的项目的类型安全
+
+**结果**：在 TypeScript 中直接对字符串链式调用会报类型错误：
 
 ```typescript
-// ❌ TypeScript 可能无法正确推导类型
+// ❌ TypeScript 中会报错（v1.0.6+）
+const schema = dsl({
+  email: 'email!'.label('邮箱')  // 类型错误：Property 'label' does not exist on type 'string'
+});
+
+// ✅ JavaScript 中仍然可以正常使用
 const schema = dsl({
-  email: 'email!'.label('邮箱')  // 可能报错或无类型提示
+  email: 'email!'.label('邮箱')  // 运行时完全正常
 });
 ```
 
-### 2.2 推荐解决方案 ⭐
+### 2.2 正确用法 ⭐⭐⭐
 
-**使用 `dsl()` 函数包裹字符串**，可以获得完整的类型推导和 IDE 提示：
+**TypeScript 中必须使用 `dsl()` 函数包裹字符串**，才能获得类型提示和链式调用：
 
 ```typescript
-// ✅ 推荐：使用 dsl() 包裹
+// ✅ 正确：使用 dsl() 包裹（v1.0.6+ 必须）
 const schema = dsl({
   email: dsl('email!').label('邮箱').pattern(/custom/)
 });
+
+// ✅ 也可以先定义再使用
+const emailField = dsl('email!').label('邮箱');
+const schema = dsl({ email: emailField });
 ```
 
+**好处**：
+- ✅ 获得完整的类型推导和 IDE 自动提示
+- ✅ 不污染原生 String 类型（`trim()` 正确返回 `string`）
+- ✅ 更好的类型安全和开发体验
+
 ### 2.3 工作原理
 
 ```typescript
@@ -550,5 +570,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
+  }
 });
 ```