schema-dsl 1.0.5 → 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

@@ -220,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_]+$/, '只能包含字母、数字和下划线')
@@ -256,10 +256,13 @@ try {
 }
 ```
 
-**为什么要用 `dsl()` 包裹？**
+**为什么必须用 `dsl()` 包裹？**
 - ✅ 完整的类型推导和 IDE 自动提示
-- ✅ 避免 TypeScript 严格模式警告
-- ✅ 更好的开发体验
+- ✅ 避免污染原生 String 类型（v1.0.6+ 重要改进）
+- ✅ 保证 `trim()`、`toLowerCase()` 等原生方法类型正确
+- ✅ 更好的开发体验和类型安全
+
+**JavaScript 用户不受影响**：在 JavaScript 中仍然可以直接使用 `'email!'.label('邮箱')` 语法。
 
 **详细说明**: 请查看 [TypeScript 使用指南](./docs/typescript-guide.md)
 

package/docs/typescript-guide.md

@@ -1,7 +1,8 @@
 # TypeScript 使用指南
 
-> **版本**: schema-dsl v1.0.4+  
-> **更新日期**: 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

package/index.d.ts

@@ -814,256 +814,47 @@ declare module 'schema-dsl' {
    * });
    * ```
    */
-  global {
-    interface String {
-      /**
-       * 添加正则验证
-       * @deprecated TypeScript 用户请使用 dsl(string).pattern()
-       */
-      pattern(regex: RegExp | string, message?: string): DslBuilder;
-
-      /**
-       * 设置字段标签
-       * @deprecated TypeScript 用户请使用 dsl(string).label()
-       */
-      label(text: string): DslBuilder;
-
-      /**
-       * 自定义错误消息
-       * @deprecated TypeScript 用户请使用 dsl(string).messages()
-       */
-      messages(messages: ErrorMessages): DslBuilder;
-
-      /**
-       * 设置描述
-       * @deprecated TypeScript 用户请使用 dsl(string).description()
-       */
-      description(text: string): DslBuilder;
-
-      /**
-       * 自定义验证器
-       * @deprecated TypeScript 用户请使用 dsl(string).custom()
-       */
-      custom(validator: (value: any) => boolean | Promise<boolean> | { error: string; message: string }): DslBuilder;
-
-      /**
-       * 条件验证
-       * @deprecated TypeScript 用户请使用 dsl(string).when()
-       */
-      when(refField: string, options: { is: any; then: DslBuilder | JSONSchema; otherwise?: DslBuilder | JSONSchema }): DslBuilder;
-
-      /**
-       * 设置默认值
-       * @deprecated TypeScript 用户请使用 dsl(string).default()
-       */
-      default(value: any): DslBuilder;
-
-      /**
-       * 转为 JSON Schema
-       * @deprecated TypeScript 用户请使用 dsl(string).toSchema()
-       */
-      toSchema(): JSONSchema;
-
-      /**
-       * 用户名验证
-       * @deprecated TypeScript 用户请使用 dsl(string).username()
-       */
-      username(preset?: 'short' | 'medium' | 'long' | string): DslBuilder;
-
-      /**
-       * 密码强度验证
-       * @deprecated TypeScript 用户请使用 dsl(string).password()
-       */
-      password(strength?: 'weak' | 'medium' | 'strong' | 'veryStrong'): DslBuilder;
-
-      /**
-       * 手机号验证
-       * @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;
-    }
-  }
+
+  // ========== String 扩展说明 ==========
+
+  /**
+   * ⚠️ String 原型扩展的 TypeScript 限制
+   *
+   * 本库在运行时扩展了 String.prototype，允许在 JavaScript 中直接链式调用：
+   * ```javascript
+   * const schema = dsl({ email: 'email!'.label('邮箱') });  // ✅ JavaScript 中完全正常
+   * ```
+   *
+   * 但在 TypeScript 中，为了**避免污染全局 String 类型**（会导致原生方法如 trim() 的类型推断错误），
+   * 我们**不提供**全局 String 接口扩展。
+   *
+   * TypeScript 用户请使用以下方式：
+   *
+   * @example
+   * ```typescript
+   * import { dsl } from 'schema-dsl';
+   *
+   * // ✅ 推荐：使用 dsl() 函数获得完整类型提示
+   * const schema = dsl({
+   *   email: dsl('email!').label('邮箱').pattern(/custom/)
+   * });
+   *
+   * // ✅ 或者先定义再使用
+   * const emailField = dsl('email!').label('邮箱');
+   * const schema = dsl({ email: emailField });
+   *
+   * // ❌ 避免：在 TypeScript 中直接对字符串字面量链式调用
+   * // 这在运行时可以工作，但 TypeScript 无法提供类型提示
+   * const schema = dsl({
+   *   email: 'email!'.label('邮箱')  // TypeScript: 类型错误
+   * });
+   * ```
+   *
+   * 📝 说明：
+   * - JavaScript 用户不受影响，可以直接使用字符串链式调用
+   * - TypeScript 用户应使用 dsl() 函数包裹字符串以获得类型提示
+   * - 移除全局 String 扩展是为了防止污染原生 String 方法的类型定义
+   */
 
   // ========== dsl() 函数 ==========
 
@@ -2955,3 +2746,4 @@ declare module 'schema-dsl' {
   export default dsl;
 }
 
+

package/package.json

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