schema-dsl 1.2.4 → 2.0.0

package/CHANGELOG.md

@@ -1,236 +1,113 @@
-# 变更日志 (CHANGELOG)
+# Changelog
 
-> **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-03-03
+All notable changes to this project will be documented in this file.
 
----
-
-## 版本概览
-
-| 版本 | 日期 | 变更摘要 | 详细 |
-|------|------|---------|------|
-| [v1.2.3](./changelogs/v1.2.3.md) | 2026-03-03 | 🚀 新功能：i18n 子目录合并 - 多人协作独立维护语言文件，自动递归合并 + 冲突检测 | [查看](./changelogs/v1.2.3.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) |
-| [v1.1.5](./changelogs/v1.1.5.md) | 2026-01-17 | 🚀 新功能：错误配置对象格式支持 - 语言包支持 `{ code, message }` 对象格式 | [查看](./changelogs/v1.1.5.md) |
-| [v1.1.4](./changelogs/v1.1.4.md) | 2026-01-13 | 🔧 TypeScript类型修复：移除重复函数签名 + 多语言文档完善 | [查看](./changelogs/v1.1.4.md) |
-| [v1.1.3](./changelogs/v1.1.3.md) | 2026-01-09 | 🐛 Bug修复：类型错误消息模板变量未替换 | [查看](./changelogs/v1.1.3.md) |
-| [v1.1.2](./changelogs/v1.1.2.md) | 2026-01-06 | 🎉 新功能：数字比较运算符 + Bug修复 | [查看](./changelogs/v1.1.2.md) |
-| [v1.1.1](./changelogs/v1.1.1.md) | 2026-01-06 | 🎉 新功能：ConditionalBuilder 独立消息支持 | [查看](./changelogs/v1.1.1.md) |
-| [v1.1.0](./changelogs/v1.1.0.md) | 2026-01-05 | 🎉 重大功能：跨类型联合验证 + 插件系统增强 | [查看](./changelogs/v1.1.0.md) |
-| [v1.0.9](./changelogs/v1.0.9.md) | 2026-01-04 | 🎉 重大改进：多语言支持完善 + TypeScript 类型完整 | [查看](./changelogs/v1.0.9.md) |
-| v1.0.8 | 2026-01-04 | 优化：错误消息过滤增强 | - |
-| v1.0.7 | 2026-01-04 | 修复：dsl.match/dsl.if 嵌套支持 dsl() 包裹 | - |
-| v1.0.6 | 2026-01-04 | 🚨 紧急修复：TypeScript 类型污染 | - |
-| v1.0.5 | 2026-01-04 | 测试覆盖率提升至 97% | - |
-| v1.0.4 | 2025-12-31 | TypeScript 完整支持、validateAsync、ValidationError | - |
-| v1.0.3 | 2025-12-31 | ⚠️ 破坏性变更：单值语法修复 | - |
-| v1.0.2 | 2025-12-31 | 15个新增验证器、完整文档、75个测试 | - |
-| v1.0.1 | 2025-12-31 | 枚举功能、自动类型识别、统一错误消息 | - |
-| [v1.0.0](./changelogs/v1.0.0.md) | 2025-12-29 | 初始发布版本 | [查看](./changelogs/v1.0.0.md) |
-
-> 💡 **提示**: 重要版本的详细变更记录在 [changelogs/](./changelogs/) 目录中。  
-> 当前已有详细文档的版本：v1.2.3, 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  
-> 其他版本的详细变更信息请参考项目提交历史或联系维护者。
-
----
-
-## 变更统计
-
-| 版本系列 | 版本数 | 主要改进方向 |
-|---------|-------|------------|
-| v1.2.x | 2 | i18n子目录合并、智能类型转换、Web API 完美支持 |
-| v1.1.x | 9 | 智能参数识别、Bug修复、错误消息优化、错误配置增强、TypeScript类型完善、多语言支持、数字运算符、联合类型 |
-| v1.0.x | 10 | 核心功能、验证器、测试覆盖、文档完善 |
-
----
-
-## 里程碑版本
-
-### v1.2.2 - 智能类型转换 🚀
-
-**发布日期**: 2026-02-06  
-**重要性**: ⭐⭐⭐⭐⭐
-
-**主要改进**:
-- 🚀 新增智能类型转换功能，自动将字符串数字转换为 number 类型
-- ✅ 默认启用，零配置，开箱即用
-- ✅ 完美支持 Web API 项目（Express、Koa 等）
-- ✅ 保持类型安全（枚举字段不转换）
-- ✅ 支持禁用选项 `validate(schema, data, { coerce: false })`
-- ✅ 新增 23 个测试用例，100% 通过率
-
-**核心特性**:
-- 智能判断：只转换字符串→数字（且必须是有效数字）
-- 类型安全：string 字段保持字符串，boolean 被正确拒绝
-- 枚举保护：数字枚举 `1|2|3` 不接受字符串 `"1"`
-- 边界处理：支持小数、负数、零、trim 等
-
-**使用示例**:
-```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'
-```
-
-**技术细节**:
-- 新增 `smartCoerceTypes()` 函数（约 60 行）
-- 修改文件：`index.js`
-- 测试文件：`test/unit/smart-coerce.test.js`（23 个测试）
-- 零性能损失，运行时开销可忽略不计
-
-**详细信息**: [查看 changelogs/v1.2.2.md](./changelogs/v1.2.2.md)
+> 📂 **Detailed changes**: see [`changelogs/`](./changelogs/) for full notes on major versions.
 
 ---
 
-### v1.1.8 - 智能参数识别 🚀
-
-**发布日期**: 2026-01-30  
-**重要性**: ⭐⭐⭐⭐⭐
-
-**主要改进**:
-- 🚀 新增智能参数识别功能，支持简化语法 `dsl.error.throw('key', 'locale')`
-- ✅ 从4个参数减少到2个参数（不需要参数对象时）
-- ✅ 智能识别第2个参数类型：字符串→语言参数，对象→参数对象
-- ✅ 所有方法都支持：create、throw、assert
-- ✅ 完全向后兼容，现有代码无需修改
-- ✅ 新增 17 个测试用例，100%通过率
-
-**技术细节**:
-- 新增 `normalizeParams()` 工具函数
-- 修改文件：`lib/errors/I18nError.js`、`index.js`
-- 参数识别逻辑：typeof 检查 + Array.isArray 排除
-- 零性能损失，运行时开销可忽略不计
-
-**使用示例**:
-```javascript
-// 之前：必须传递空对象
-dsl.error.throw('account.notFound', {}, 404, 'zh-CN');
-
-// 现在：直接传语言参数
-dsl.error.throw('account.notFound', 'zh-CN', 404);
-```
-
-### v1.1.7 - 错误消息路径显示优化 🐛
-
-**发布日期**: 2026-01-27  
-**重要性**: ⭐⭐⭐⭐
-
-### v1.1.6 - ErrorFormatter Bug修复 🐛
-
-**发布日期**: 2026-01-23  
-**重要性**: ⭐⭐⭐⭐
-
-**主要改进**:
-- 🐛 修复 enum 错误消息模板变量 `{{#valids}}` 未替换问题
-- 🐛 修复 additionalProperties 错误消息缺少属性名问题
-- ✅ 新增完整的错误消息插值测试（14个测试用例）
-- ✅ 确保所有 ajv 错误参数正确映射到模板变量
-
-### v1.1.5 - 错误配置对象格式支持 🚀
-
-**发布日期**: 2026-01-17  
-**重要性**: ⭐⭐⭐⭐
-
-**核心改进**:
-- ✨ 语言包支持对象格式 `{ code, message }`，统一错误代码管理
-- ✨ I18nError 新增 `originalKey` 字段，保留原始 key
-- ✨ 多语言共享相同的 `code`，便于前端统一处理
-- ✅ 完全向后兼容，字符串格式自动转换为对象
-- ✅ `error.is()` 同时支持 code 和 originalKey 判断
-
-**测试覆盖**: 942 个测试通过 (98.6%)
-
-### v1.1.4 - TypeScript类型修复与文档完善 🔧
-
-**发布日期**: 2026-01-13  
-**重要性**: ⭐⭐⭐
-
-**核心改进**:
-- ✅ 修复 index.d.ts 中2处重复函数签名（46个类型错误→0个错误）
-- ✅ 修复 `dsl.error.assert` 重复签名（L1336-1343）
-- ✅ 修复 `I18nError.assert` 重复签名（L1805-1821）
-- ✅ 完善多语言运行时支持文档（docs/runtime-locale-support.md）
-- ✅ README.md 添加运行时语言指定示例
-- ✅ 验证 string? 可选语法完整支持
-
-**详细信息**: [查看 changelogs/v1.1.4.md](./changelogs/v1.1.4.md)
+## Version History
+
+| Version | Date | Type | Key Theme |
+|---------|------|------|-----------|
+| [2.0.0] | 2026-05-09 | Major | Full release: BC-2/4/5/6/7 fixes, string:N compat, English comments, 58 enriched examples, 1095 tests [View](./changelogs/v2.0.0.md) |
+| [2.0.0-beta.2] | 2026-04-12 | Major | Full TypeScript rewrite: ESM+CJS dual format, AJV 8, tsup build, 1052 tests passing [View](./changelogs/v2.0.0-beta.2.md) |
+| [v1.2.5] | 2026-03-09 | Patch | Feature: `DslBuilder.toJsonSchema()` — exports clean JSON Schema, strips internal markers |
+| [v1.2.4] | 2026-03-09 | Patch | P1 Fix: `enum:a,b,c` comma-separated format parsing completely broken |
+| [v1.2.3] | 2026-03-03 | Patch | Feature: i18n sub-directory merging; collaborative locale maintenance with auto-merge + conflict detection [View](./changelogs/v1.2.3.md) |
+| [v1.2.2] | 2026-02-06 | Minor | Major feature: smart type coercion — auto-converts string numbers, full Web API support [View](./changelogs/v1.2.2.md) |
+| [v1.1.8] | 2026-01-30 | Patch | Feature: smart argument detection, simplified syntax `dsl.error.throw('key', 'locale')` [View](./changelogs/v1.1.8.md) |
+| [v1.1.7] | 2026-01-27 | Patch | Fix: error message path display — all error types now show field name only |
+| [v1.1.6] | 2026-01-23 | Patch | Fix: enum and additionalProperties error message template variables not substituted [View](./changelogs/v1.1.6.md) |
+| [v1.1.5] | 2026-01-17 | Patch | Feature: error config object format; locale messages now support `{ code, message }` object format [View](./changelogs/v1.1.5.md) |
+| [v1.1.4] | 2026-01-13 | Patch | TS fix: remove duplicate function signatures + multilingual docs improvements [View](./changelogs/v1.1.4.md) |
+| [v1.1.3] | 2026-01-09 | Patch | Fix: type error message template variables not substituted [View](./changelogs/v1.1.3.md) |
+| [v1.1.2] | 2026-01-06 | Patch | Feature: numeric comparison operators + bug fixes [View](./changelogs/v1.1.2.md) |
+| [v1.1.1] | 2026-01-06 | Patch | Feature: ConditionalBuilder independent message support [View](./changelogs/v1.1.1.md) |
+| [v1.1.0] | 2026-01-05 | Minor | Major: cross-type union validation + enhanced plugin system [View](./changelogs/v1.1.0.md) |
+| [v1.0.9] | 2026-01-04 | Patch | Major improvement: complete i18n support + full TypeScript types [View](./changelogs/v1.0.9.md) |
+| v1.0.8 | 2026-01-04 | Patch | Improvement: enhanced error message filtering |
+| v1.0.7 | 2026-01-04 | Patch | Fix: dsl.match/dsl.if nesting now supports dsl() wrapper |
+| v1.0.6 | 2026-01-04 | Patch | 🚨 Critical fix: TypeScript type pollution |
+| v1.0.5 | 2026-01-04 | Patch | Test coverage raised to 97% |
+| v1.0.4 | 2025-12-31 | Patch | Full TypeScript support, validateAsync, ValidationError |
+| v1.0.3 | 2025-12-31 | Patch | ⚠️ Breaking change: single-value syntax fix |
+| v1.0.2 | 2025-12-31 | Patch | 15 new validators, complete docs, 75 tests |
+| v1.0.1 | 2025-12-31 | Patch | Enum support, auto type detection, unified error messages |
+| [v1.0.0] | 2025-12-29 | Pre-release | Initial release [View](./changelogs/v1.0.0.md) |
 
 ---
 
-### v1.1.3 - 类型错误消息模板修复 🐛
+## [2.0.0] — 2026-05-09
 
-**发布日期**: 2026-01-09  
-**重要性**: ⭐⭐⭐
+### Breaking Changes (v1 → v2)
 
-**核心改进**:
-- ✅ 修复类型错误消息中 `{{#actual}}` 模板变量未替换问题
-- ✅ 错误消息正确显示实际数据类型
-- ✅ 向后兼容，无破坏性变更
+- **BC-2**: `DslAdapter.parseObject()` now returns `ObjectDslBuilder` (chainable: `.strict()`, `.requireAll()`, `.toSchema()`, `.toJsonSchema()`) instead of plain `JSONSchema`. Call `.toSchema()` to get the raw schema.
+- **BC-4**: `DslAdapter.typeMap` is now a Proxy getter; `DslAdapter.registerType()` method added for direct registration.
+- **BC-5**: `ConditionalBuilder.require(field)` method added for v1 field-requirement compatibility.
+- **BC-6**: `Validator.validateAsync()` added; async custom validators in sync `validate()` now return `{ valid: false }` with an error message instead of silently passing.
+- **BC-7**: `string:N` single-value DSL now expands to `{ minLength: N, maxLength: N }` (exactLength compat, consistent with v1 behavior).
 
-**详细信息**: [查看 changelogs/v1.1.3.md](./changelogs/v1.1.3.md)
+### New Features
 
----
+- **ObjectDslBuilder**: New class wrapping object schemas; supports `.strict()`, `.requireAll()`, `.toSchema()`, `.toJsonSchema()`, `.toString()`.
+- **validateAsync()**: Full async validation support with typed return (`Promise<T>`); throws `ValidationError` on failure.
+- **installStringExtensions()**: Opt-in String.prototype extension; auto-installed at module load for v1 compatibility.
 
-### v1.1.0 - 跨类型联合验证 🎉
+### Documentation & Examples
 
-**发布日期**: 2026-01-05  
-**重要性**: ⭐⭐⭐⭐⭐
+- 58 example files in `examples/docs/` fully enriched (90–130+ lines each) with complete API coverage.
+- All code comments translated to English (CJK locales and output strings preserved).
+- `docs/api-reference.md`: fixed 4 doc inconsistencies (string:N behavior, validateAsync signature, LocaleMessage params, exactOptionalPropertyTypes notes).
 
-**核心特性**:
-- ✅ 跨类型联合验证（email|phone 可以混合不同类型）
-- ✅ 运行时多语言支持（dsl.error.create 可指定 locale 参数）
-- ✅ 插件系统增强
+### Quality
 
-**详细信息**: [查看 changelogs/v1.1.0.md](./changelogs/v1.1.0.md)
+- 1095 tests passing (75 test files).
+- 0 TypeScript errors in source and examples.
+- ESM + CJS dual format build.
 
----
+### Fixes
 
-### v1.0.9 - 多语言支持完善 🌍
-
-**发布日期**: 2026-01-04  
-**重要性**: ⭐⭐⭐⭐
-
-**核心特性**:
-- ✅ 完整的多语言支持（5种语言）
-- ✅ TypeScript 类型定义完整
-- ✅ I18nError 多语言错误类
-
-**详细信息**: [查看 changelogs/v1.0.9.md](./changelogs/v1.0.9.md)
+- **Security**: replace the custom regex ReDoS heuristic in `CustomKeywords` with `safe-regex`, so catastrophic patterns such as `((a)+)+$` are rejected before execution.
+- **Validation**: stop caching `DslBuilder.toSchema()` results inside `Validator`, so chain mutations made after the first validation call are honored by both `validate()` and `validateAsync()`.
+- **Validation**: make `ConditionalBuilder` cache `Validator` instances by constructor-level option set, so repeated calls with different `allErrors` / `useDefaults` configurations no longer reuse a stale validator.
+- **Exporters**: fix MySQL integer sizing so `TypeConverter.toMySQLType()` checks both `minimum` and `maximum` before choosing `TINYINT` / `SMALLINT` / `INT`, avoiding undersized column types.
+- **Exporters**: escape Markdown table cell content in `MarkdownExporter`, so field names, constraint text, and multiline descriptions containing `|` or newlines no longer break rendered tables.
+- **Tests**: add focused regression coverage for unsafe regex rejection while preserving the existing invalid-regex error path.
 
 ---
 
-### v1.0.0 - 正式发布 🎉
-
-**发布日期**: 2025-12-29  
-**重要性**: ⭐⭐⭐⭐⭐
-
-**核心成就**:
-- ✅ 初始发布
-- ✅ 简洁的DSL语法
-- ✅ 完整的验证功能
+## [Unreleased]
 
-**详细信息**: [查看 changelogs/v1.0.0.md](./changelogs/v1.0.0.md)
+- docs: aligned 58-to-58 `docs/*.md` ↔ `examples/docs/*.ts` mapping, switched to stable example entry links
+- docs: completed runnable coverage for advanced APIs in `api-reference`, added `ErrorFormatter` reference, corrected `FEATURE-INDEX` method descriptions
+- chore: cleaned up legacy top-level `examples/*` entry paths, unified example entry points and `.tmp` workspace visibility
 
 ---
 
-**完整文档**: [docs/INDEX.md](./docs/INDEX.md)  
-**GitHub**: [https://github.com/vextjs/schema-dsl](https://github.com/vextjs/schema-dsl)  
-**npm**: [https://www.npmjs.com/package/schema-dsl](https://www.npmjs.com/package/schema-dsl)
+## Links
+
+- [GitHub Repository](https://github.com/vextjs/schema-dsl)
+- [Online Documentation](https://vextjs.github.io/schema-dsl)
+- [Detailed Changelogs](./changelogs/)
+- [Contributing Guide](./CONTRIBUTING.md)
+
+[Unreleased]: https://github.com/vextjs/schema-dsl/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/vextjs/schema-dsl/compare/v2.0.0-beta.2...v2.0.0
+[2.0.0-beta.2]: https://github.com/vextjs/schema-dsl/releases/tag/v2.0.0-beta.2
+[v1.2.5]: https://github.com/vextjs/schema-dsl/compare/v1.2.4...v1.2.5
+[v1.2.4]: https://github.com/vextjs/schema-dsl/compare/v1.2.3...v1.2.4
+[v1.2.3]: https://github.com/vextjs/schema-dsl/compare/v1.2.2...v1.2.3
+[v1.2.2]: https://github.com/vextjs/schema-dsl/compare/v1.1.8...v1.2.2
+[v1.1.8]: https://github.com/vextjs/schema-dsl/compare/v1.1.7...v1.1.8
+[v1.1.7]: https://github.com/vextjs/schema-dsl/compare/v1.1.6...v1.1.7
+[v1.1.6]: https://github.com/vextjs/schema-dsl/compare/v1.1.5...v1.1.6
+[v1.1.5]: https://github.com/vextjs/schema-dsl/compare/v1.1.4...v1.1.5
+[v1.1.4]: https://github.com/vextjs/schema-dsl/compare/v1.1.3...v1.1.4
+[v1.1.3]: https://github.com/vextjs/schema-dsl/compare/v1.1.2...v1.1.3
+[v1.1.2]: https://github.com/vextjs/schema-dsl/compare/v1.1.1...v1.1.2
+[v1.1.1]: https://github.com/vextjs/schema-dsl/compare/v1.1.0...v1.1.1
+[v1.1.0]: https://github.com/vextjs/schema-dsl/compare/v1.0.9...v1.1.0
+[v1.0.9]: https://github.com/vextjs/schema-dsl/compare/v1.0.8...v1.0.9
+[v1.0.0]: https://github.com/vextjs/schema-dsl/releases/tag/v1.0.0