schema-dsl 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-02-02
+> **最后更新**: 2026-02-06
 
 ---
 
@@ -9,7 +9,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
-| [v1.2.0](./changelogs/v1.2.0.md) | 2026-02-02 | 🔧 TypeScript修复：never类型保证 - 修复 throw 方法类型检查 | [查看](./changelogs/v1.2.0.md) |
+| [v1.2.2](./changelogs/v1.2.2.md) | 2026-02-06 | 🚀 重大功能：智能类型转换 - 字符串数字自动转换，完美支持 Web API | [查看](./changelogs/v1.2.2.md) |
 | [v1.1.8](./changelogs/v1.1.8.md) | 2026-01-30 | 🚀 新功能：智能参数识别 - 支持简化语法 `dsl.error.throw('key', 'locale')` | [查看](./changelogs/v1.1.8.md) |
 | [v1.1.7](./changelogs/v1.1.7.md) | 2026-01-27 | 🐛 Bug修复：错误消息路径显示优化 - 所有错误类型的 message 只显示字段名 | [查看](./changelogs/v1.1.7.md) |
 | [v1.1.6](./changelogs/v1.1.6.md) | 2026-01-23 | 🐛 Bug修复：enum和additionalProperties错误消息模板变量未替换 | [查看](./changelogs/v1.1.6.md) |
@@ -31,7 +31,7 @@
 | [v1.0.0](./changelogs/v1.0.0.md) | 2025-12-29 | 初始发布版本 | [查看](./changelogs/v1.0.0.md) |
 
 > 💡 **提示**: 重要版本的详细变更记录在 [changelogs/](./changelogs/) 目录中。  
-> 当前已有详细文档的版本：v1.2.0, v1.1.8, v1.1.7, v1.1.6, v1.1.5, v1.1.4, v1.1.3, v1.1.2, v1.1.1, v1.1.0, v1.0.9, v1.0.0  
+> 当前已有详细文档的版本：v1.2.2, v1.1.8, v1.1.7, v1.1.6, v1.1.5, v1.1.4, v1.1.3, v1.1.2, v1.1.1, v1.1.0, v1.0.9, v1.0.0  
 > 其他版本的详细变更信息请参考项目提交历史或联系维护者。
 
 ---
@@ -40,51 +40,63 @@
 
 | 版本系列 | 版本数 | 主要改进方向 |
 |---------|-------|------------|
-| v1.2.x | 1 | TypeScript类型系统完善 |
-| v1.1.x | 9 | 智能参数识别、Bug修复、错误消息优化、错误配置增强、多语言支持、数字运算符、联合类型 |
+| v1.2.x | 1 | 智能类型转换、Web API 完美支持 |
+| v1.1.x | 9 | 智能参数识别、Bug修复、错误消息优化、错误配置增强、TypeScript类型完善、多语言支持、数字运算符、联合类型 |
 | v1.0.x | 10 | 核心功能、验证器、测试覆盖、文档完善 |
 
 ---
 
 ## 里程碑版本
 
-### v1.2.0 - TypeScript never 类型修复 🔧
+### v1.2.2 - 智能类型转换 🚀
 
-**发布日期**: 2026-02-02  
-**重要性**: ⭐⭐⭐
+**发布日期**: 2026-02-06  
+**重要性**: ⭐⭐⭐⭐⭐
 
 **主要改进**:
-- 🔧 修复 TypeScript `never` 类型编译检查问题
-- ✅ 在 `I18nError.throw()` 和 `dsl.error.throw()` 中添加 unreachable 保证
-- ✅ 确保函数永不返回，满足 TypeScript 类型系统要求
-- ✅ 所有 782 个测试通过，零破坏性变更
-- ✅ 向后兼容，不影响现有功能
-
-**技术细节**:
-- 在两个 `throw` 方法末尾添加 `throw new Error('unreachable')`
-- 使用 `eslint-disable-next-line no-unreachable` 禁用 ESLint 警告
-- 修改文件：`lib/errors/I18nError.js` (L211), `index.js` (L94-97)
-- `assert` 方法使用 `asserts condition` 类型，无需修改
+- 🚀 新增智能类型转换功能，自动将字符串数字转换为 number 类型
+- ✅ 默认启用，零配置，开箱即用
+- ✅ 完美支持 Web API 项目（Express、Koa 等）
+- ✅ 保持类型安全（枚举字段不转换）
+- ✅ 支持禁用选项 `validate(schema, data, { coerce: false })`
+- ✅ 新增 23 个测试用例，100% 通过率
 
-**问题背景**:
-TypeScript 的 `never` 类型表示函数永不返回。虽然函数内部有 `throw` 语句，但编译器需要明确的保证。添加第二个 `throw` 语句（永远不会执行）满足了类型系统的要求。
+**核心特性**:
+- 智能判断：只转换字符串→数字（且必须是有效数字）
+- 类型安全：string 字段保持字符串，boolean 被正确拒绝
+- 枚举保护：数字枚举 `1|2|3` 不接受字符串 `"1"`
+- 边界处理：支持小数、负数、零、trim 等
 
 **使用示例**:
-```typescript
-function test(id: string | null) {
-  if (!id) {
-    dsl.error.throw('account.notFound');
-    // ✅ TypeScript 知道这里永不返回
-  }
-  // ✅ TypeScript 知道 id 一定不是 null，不需要 ! 断言
-  console.log(id.toUpperCase());
-}
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+const schema = dsl({
+  userId: 'number!',
+  page: 'number?',
+  email: 'email!'
+});
+
+// ✅ 字符串自动转换为数字
+const result = validate(schema, {
+  userId: '123',  // → 123 (number)
+  page: '2',      // → 2 (number)
+  email: 'test@example.com'
+});
+
+console.log(result.valid);       // true
+console.log(typeof result.data.userId); // 'number'
 ```
 
-**修复验证**:
-- ✅ TypeScript 编译检查通过（`npx tsc --noEmit`）
-- ✅ 控制流分析正确推断变量类型
-- ✅ 所有现有测试通过
+**技术细节**:
+- 新增 `smartCoerceTypes()` 函数（约 60 行）
+- 修改文件：`index.js`
+- 测试文件：`test/unit/smart-coerce.test.js`（23 个测试）
+- 零性能损失，运行时开销可忽略不计
+
+**详细信息**: [查看 changelogs/v1.2.2.md](./changelogs/v1.2.2.md)
+
+---
 
 ### v1.1.8 - 智能参数识别 🚀