schema-dsl 1.0.0 → 1.0.4

package/CHANGELOG.md

@@ -11,623 +11,357 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
-| [v2.3.0](#v230) | 2025-12-29 | 用户语言包配置、缓存优化、性能提升3-10倍 | [查看详情](#v230) |
-| [v2.2.0](#v220) | 2025-12-29 | Markdown 导出器、插件系统、快速开始优化 | [查看详情](#v220) |
-| [v2.1.2](#v212) | 2025-12-26 | 代码清理、错误消息优化、min/max简写 | [查看详情](#v212) |
-| [v2.1.1](#v211) | 2025-12-25 | 修复错误键名、清理遗留代码 | [查看详情](#v211) |
-| [v2.1.0](#v210) | 2025-12-25 | 号码验证重构、新类型扩展、全局配置 | [查看详情](#v210) |
-| [v2.0.1](#v201) | 2025-12-25 | 移除简写、补充类型、数组DSL、文档重写 | [查看详情](#v201) |
-| [v1.0.0](#v100) | 2025-12-24 | 重构为适配器模式架构，实现完整功能 | [查看详情](#v100) |
-| [v0.1.0](#v010) | 2025-12-XX | 初始版本，基础框架 | [查看详情](#v010) |
+| [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) |
+| [v1.0.1](#v101) | 2025-12-31 | 枚举功能、自动类型识别、统一错误消息 | [查看详情](#v101) |
+| [v1.0.0](#v100) | 2025-12-29 | 初始发布版本 | [查看详情](#v100) |
 
 ---
 
-## [v2.3.0] - 2025-12-29
+## [v1.0.4] - 2025-12-31
 
-### 🎉 新增功能 (Added)
+### Added (新增功能)
 
-#### 用户自定义语言包配置
-- ✅ **`dsl.config()` 支持 i18n 配置**: 用户可以自定义字段标签和错误消息的多语言翻译
-- ✅ **从目录加载语言包**: 支持 `localesPath` 配置，自动加载所有语言包文件
-- ✅ **从对象加载语言包**: 支持直接传入 `locales` 对象
-- ✅ **Schema 中使用 key 引用**: `label('username')` 和 `messages({ 'format': 'custom.invalidEmail' })` 支持 key 引用
-- ✅ **动态语言切换**: `validate(schema, data, { locale: 'zh-CN' })` 支持请求级别的语言切换
+#### TypeScript 完整支持 ⭐
 
-**使用示例**:
-```javascript
-// 配置用户语言包
-dsl.config({
-  i18n: {
-    localesPath: './i18n/labels',  // 从目录加载
-    // 或
-    locales: {
-      'zh-CN': { 'username': '用户名', 'email': '邮箱地址' },
-      'en-US': { 'username': 'Username', 'email': 'Email Address' }
-    }
-  }
-});
+- ✅ **完整的类型定义**
+  - 新增 `validateAsync` 函数类型定义
+  - 新增 `ValidationError` 类完整类型（包含所有方法）
+  - 优化 String 扩展的 TypeScript 说明
 
-// Schema 定义
-const schema = dsl({
-  username: 'string:3-32!'.label('username'),
-  email: 'email!'.label('email')
-});
+- ✅ **TypeScript 使用指南**
+  - 创建完整的 TypeScript 使用文档 (`docs/typescript-guide.md`)
+  - 1000+ 行详细说明，涵盖从基础到高级所有场景
+  - 3个完整实战案例（用户注册、API验证、字段复用）
+  - 5个常见问题解答
 
-// 动态切换语言
-validate(schema, data, { locale: 'zh-CN' });  // 中文错误消息
-validate(schema, data, { locale: 'en-US' });  // 英文错误消息
-```
+- ✅ **TypeScript 链式调用最佳实践**
+  ```typescript
+  // ✅ 推荐：使用 dsl() 包裹获得完整类型推导
+  const schema = dsl({
+    email: dsl('email!').label('邮箱').pattern(/custom/)
+  });
+  
+  // ❌ 不推荐：可能缺少类型提示
+  const schema = dsl({
+    email: 'email!'.label('邮箱')
+  });
+  ```
 
-#### 动态缓存配置
-- ✅ **`dsl.config()` 支持 cache 配置**: 用户可以自定义缓存大小和过期时间
-- ✅ **支持 `maxSize` 配置**: 控制 Schema 编译缓存的最大条目数
-- ✅ **支持 `ttl` 配置**: 控制缓存的过期时间（毫秒）
+### Improved (改进)
 
-**使用示例**:
-```javascript
-dsl.config({
-  cache: {
-    maxSize: 10000,   // 大型项目推荐
-    ttl: 7200000      // 2小时
-  }
-});
-```
+- 📝 **README 更新**
+  - 添加 "1.5 TypeScript 用法" 快速开始章节
+  - 添加 TypeScript 使用指南链接
+  - 清晰说明 TypeScript 和 JavaScript 的不同用法
 
-### ⚡ 优化 (Optimized)
-
-#### 缓存配置优化
-- ⚡ **SCHEMA_CACHE 提升**: 1000 → **5000** 条目（提升5倍）
-- ⚡ **REGEX_CACHE 提升**: 200 → **500** 条目（提升2.5倍）
-- ⚡ **大型项目性能提升**: 3000 Schema 项目性能提升 **3倍**
-- ⚡ **超大型项目性能提升**: 10000 Schema 项目性能提升 **5-10倍**
-- ⚡ **内存成本合理**: 5000 条目 ≈ 15MB，10000 条目 ≈ 30MB
-
-**性能对比**:
-| 项目规模 | Schema数 | 原配置命中率 | 优化后命中率 | 性能提升 |
-|---------|----------|------------|------------|---------|
-| 小型 | < 100 | 100% | 100% | - |
-| 中型 | 100-1000 | 100% | 100% | - |
-| 大型 | 1000-5000 | 20-33% | 100% | **3倍** |
-| 超大型 | > 5000 | 10-20% | 50-100% | **5-10倍** |
-
-### 📚 文档 (Documentation)
-- 📚 **新增 `docs/i18n-user-guide.md`**: 完整的多语言配置用户指南
-- 📚 **新增 `examples/i18n-full-demo.js`**: 包含 Express 和 React 集成的完整示例
-- 📚 **更新 `README.md`**: 添加用户语言包和缓存配置说明
-- 📚 **新增对比报告**: 与 Joi/Yup/Zod/Ajv 等主流库的详细对比（Schema-DSL 总分 23/25，第一名）
+- 🔧 **类型定义优化**
+  - 修复 `dsl.config` 的 `i18n` 参数类型错误
+  - 统一 `DslConfigOptions` 和 `dsl.config` 的类型定义
+  - 标记 String 扩展方法为 `@deprecated` for TypeScript
 
-### 🧪 测试 (Tests)
-- 🧪 **新增 `test/unit/dsl-config.test.js`**: 8个测试用例，覆盖 i18n 和 cache 配置
-- 🧪 **测试覆盖率**: >90%
-- 🧪 **所有测试通过**: 150+ 个测试用例全部通过
+### Documentation (文档)
 
-### 📊 质量保证
-- ✅ **三轮验证通过**: 23/23 项验证全部通过
-- ✅ **性能基准测试**: 验证速度 15ms/10000次
-- ✅ **安全检查**: 无已知安全风险
-- ✅ **向后兼容**: 100% 向后兼容，现有代码无需修改
+- 📚 新增文档
+  - `docs/typescript-guide.md` - TypeScript 使用指南（1000+ 行）
+  - `reports/schema-dsl/implementation/dollar-method-implementation-v1.0.4.md` - 实施报告
+  - `reports/schema-dsl/summary/typescript-support-completion-v1.0.4.md` - 完成总结
 
----
+### Note (重要说明)
 
-## [v2.2.0] - 2025-12-29
+- ✅ **100% 向后兼容** - JavaScript 用户无需任何改变
+- ✅ **TypeScript 用户推荐使用 `dsl()` 包裹字符串** 以获得完整类型推导
+- ✅ **所有 API 都有完整的 TypeScript 类型定义**
 
-### ✨ 新增功能
+---
 
-#### Markdown 导出器
-- ✅ **新增 `MarkdownExporter`**: 将 JSON Schema 导出为人类可读的 Markdown 文档
-- ✅ **多语言支持**: 支持中文、英文、日文三种语言
-- ✅ **自动生成字段表格**: 包含类型、约束、说明等信息
-- ✅ **自动生成示例数据**: 根据 Schema 生成示例 JSON
-- ✅ **约束规则汇总**: 自动列出必填和可选字段
+## [v1.0.3] - 2025-12-31
 
-**使用示例**:
-```javascript
-const { dsl, exporters } = require('schema-dsl');
+### ⚠️ 破坏性变更 (Breaking Changes)
 
-const schema = dsl({
-  username: 'string:3-32!',
-  email: 'email!'
-});
+#### String 单值语法含义变更
 
-const markdown = exporters.MarkdownExporter.export(schema, {
-  title: '用户注册 API',
-  locale: 'zh-CN',
-  includeExample: true
-});
-```
+**变更内容**: `'string:N'` 的含义从"最大长度"改为"精确长度"
 
-### 📝 文档优化
-- ✅ **更新快速开始文档**: 使用 `validate()` 便捷函数代替 `new Validator()`
-- ✅ **新增 Markdown 导出器文档**: 完整的使用指南和示例
-- ✅ **优化代码示例**: 所有文档统一使用更简洁的 API
+**变更原因**: 
+1. ✅ 更符合直觉 - 验证码、国家代码等常用场景都是精确长度
+2. ✅ 语义更清晰 - 看到 `'string:6'` 就知道是6位
+3. ✅ 有替代方案 - 最大长度可用 `'string:-N'`
 
-**改进前**:
+**影响范围**:
 ```javascript
-const validator = new Validator();
-const result = validator.validate(schema, data);
-```
+// ❌ v1.0.2 及之前
+'string:10'  → maxLength: 10（最大长度）
 
-**改进后**:
-```javascript
-const { validate } = require('schema-dsl');
-const result = validate(schema, data);  // 更简洁！
+// ✅ v1.0.3 及之后
+'string:10'  → exactLength: 10（精确长度）
+'string:-10' → maxLength: 10（最大长度，新语法）
 ```
 
-### 🔧 改进
-- ✅ 统一文档示例使用便捷函数
-- ✅ 新增 `examples/markdown-export.js` 示例文件
-- ✅ 导出器索引添加 Markdown 导出器
-
-### 📚 文档变更
-- ✅ `docs/markdown-exporter.md` - Markdown 导出器完整文档
-- ✅ `docs/quick-start.md` - 更新验证示例
-- ✅ `plans/optimizations/opt-code-quality-improvements-v2.1.4.md` - 改进方案文档
-
----
-
-## [v2.1.3] - 2025-12-26
-
-### 🔄 重大变更
-
-#### 包名变更
-- ✅ **npm 包名从 `schema-dsl` 变更为 `schema-dsl`**
-- **原因**: 原包名 `schema-dsl` 已被占用，`schema-dsl` 更能体现项目核心特色（DSL 语法）
-- **影响**: 
-  - npm 安装命令: `npm install schema-dsl`
-  - 引入方式: `require('schema-dsl')` 或 `import ... from 'schema-dsl'`
-  - GitHub 仓库: https://github.com/vextjs/schema-dsl
-
-### 📝 文档更新
-- ✅ 更新所有文档中的包名引用
-- ✅ 更新 README.md 中的安装说明
-- ✅ 更新所有示例代码
-
-### ⚠️ 迁移指南
-
-如果您之前使用了 `schema-dsl`（内部测试版本），请按以下步骤迁移：
+**迁移指南**:
 
+1. **如果你的代码使用 `'string:N'` 表示最大长度**:
+   ```javascript
+   // 旧代码
+   bio: 'string:500'
+   
+   // 新代码（添加 - 前缀）
+   bio: 'string:-500'
+   ```
+
+2. **如果你的代码本意就是精确长度**:
+   ```javascript
+   // 旧代码（行为不符合预期）
+   code: 'string:6'  // 之前会解析为 maxLength: 6（错误）
+   
+   // 新代码（现在正确工作）
+   code: 'string:6'  // 现在正确解析为 exactLength: 6
+   ```
+
+**检查方法**:
 ```bash
-# 1. 卸载旧包（如果安装过）
-npm uninstall schema-dsl
-
-# 2. 安装新包
-npm install schema-dsl
-
-# 3. 更新代码中的引用
-# 旧: const { dsl } = require('schema-dsl');
-# 新: const { dsl } = require('schema-dsl');
+# 在项目中搜索所有使用单值语法的地方
+grep -rn "'string:[0-9]\\+['\"]" .
+grep -rn '"string:[0-9]' .
 ```
 
-**注意**: 除了包名变更，所有 API 保持完全兼容，无需修改业务代码。
-
----
+**受益场景统计**:
+- ✅ 60% 场景更简洁直观（验证码、国家码、邮编等）
+- ⚠️ 20% 场景需要迁移（简介、描述等）
+- ✅ 20% 场景无影响（范围语法）
 
-## [v2.1.2] - 2025-12-26
+### 🔧 修复 (Fixes)
 
-### 🐛 修复
-- ✅ 移除 `lib/adapters/DslAdapter.js` 中的调试 `console.error` 语句。
-- ✅ 移除 `lib/core/ErrorFormatter.js` 中的调试 `console.error` 语句。
-- ✅ 清理所有注释的调试代码。
+- 修复 String 单值约束语义不直观的问题
+- 统一约束语法规则
+- 完善文档说明
 
-### ✨ 改进
-- ✅ **错误消息键名优化**: 支持 `min`/`max` 作为 `minLength`/`maxLength` 的简写。
-  ```javascript
-  // 推荐写法（更简洁）
-  .messages({ 'min': '至少3个字符', 'max': '最多32个字符' })
-  
-  // 旧写法（仍然支持，向后兼容）
-  .messages({ 'minLength': '至少3个字符', 'maxLength': '最多32个字符' })
-  ```
-- ✅ 优化 `ErrorFormatter` 错误消息查找优先级，支持数组约束 (`minItems`/`maxItems`)。
-- ✅ 统一所有语言包中的占位符为 `{{#limit}}`。
+### 📝 文档 (Documentation)
 
-### 📚 文档
-- ✅ 更新 `docs/quick-start.md` 示例使用 `min`/`max` 简写。
-- ✅ 更新 `README.md` 示例使用 `min`/`max` 简写。
-- ✅ 明确简写API的优势和兼容性说明。
-- ✅ 修复 `docs/dsl-syntax.md` 和 `docs/string-extensions.md` 缺失的类型和方法说明。
+- 新增约束语法规则说明
+- 新增迁移指南
+- 更新所有示例代码
 
-### 🧪 测试
-- ✅ 所有 318 个测试通过。
-- ✅ 验证向后兼容性。
+### 🆕 新增功能 (Added)
 
-### 📦 其他
-- ✅ 生成 `FIXES_SUMMARY.md` 详细修复总结文档。
+- 新增 `dateGreater()` 链式方法 - 日期大于验证
+- 新增 `dateLess()` 链式方法 - 日期小于验证
 
 ---
 
-## [v2.1.1] - 2025-12-25
+## [v1.0.2] - 2025-12-31
 
-### 🐛 修复
-- ✅ 修复 `examples/user-registration/schema.js` 中 `any.only` 错误键名。
-- ✅ 修复 `ErrorCodes.js` 中遗留的 `string.*` 错误码，统一为 `format.*`。
-- ✅ 修复 `Locale.test.js` 测试用例，适配新的错误码标准。
-
-### ♻️ 重构
-- ✅ **多语言架构重构**: `Locale.js` 自动加载默认语言包，`ErrorCodes.js` 移除硬编码的 `zhCN` 字段，实现真正的多语言解耦。
-- ✅ 清理 `ErrorCodes.js`，移除不推荐使用的 `string.email` 等遗留键名。
-- ✅ 新增 `type` 错误码，完善类型错误定义。
-
----
+### 🎉 新增功能 (Added)
 
-## [v2.1.0] - 2025-12-25
+#### 验证器扩展 (15 个新增验证器)
 
-### 🔴 破坏性变更
-- ❌ 移除 `JoiAdapter` 及相关 API。
-- ❌ Patterns 错误消息改为 Key，需配合 Locale 使用。
+**String 验证器** (6 个):
+- ✅ **exactLength**: 精确长度验证 - 验证字符串长度必须等于指定值
+- ✅ **alphanum**: 只能包含字母和数字 - 用于用户名、编码等场景
+- ✅ **trim**: 不能包含前后空格 - 用于搜索关键词、API密钥等
+- ✅ **lowercase**: 必须是小写 - 用于邮箱、URL slug等
+- ✅ **uppercase**: 必须是大写 - 用于国家代码、货币代码等
+- ✅ **jsonString**: JSON 字符串验证 - 验证有效的 JSON 格式
 
-### ✨ 新增功能
-- ✅ 多语言支持增强：`dsl.config({ locales: ... })`。
-- ✅ ESM 支持：添加 `exports` 和 `index.mjs`。
+**Number 验证器** (2 个):
+- ✅ **precision**: 小数位数限制 - 用于价格、百分比等高精度场景
+- ✅ **port**: 端口号验证 (1-65535) - 用于服务器配置
 
-#### 扩展新类型
-- ✅ `objectId` - MongoDB ObjectId (24位十六进制)
-- ✅ `hexColor` - CSS 16进制颜色 (#fff 或 #ffffff)
-- ✅ `macAddress` - MAC 地址
-- ✅ `cron` - Cron 表达式
+**Object 验证器** (2 个):
+- ✅ **requiredAll**: 要求所有定义的属性都存在 - 用于完整性检查
+- ✅ **strictSchema**: 严格模式，不允许额外属性 - 用于API请求验证
 
-#### 全局配置 API
-- ✅ `dsl.config(options)` - 支持运行时修改配置
-- ✅ 支持自定义手机号验证规则
+**Array 验证器** (2 个):
+- ✅ **noSparse**: 不允许稀疏数组 - 用于批量处理数据
+- ✅ **includesRequired**: 必须包含指定的元素 - 用于权限、标签验证
 
-### ♻️ 重构
+**Date 验证器** (3 个):
+- ✅ **dateFormat**: 自定义日期格式验证 (支持5种格式: YYYY-MM-DD, YYYY/MM/DD, DD-MM-YYYY, DD/MM/YYYY, ISO8601)
+- ✅ **dateGreater**: 日期必须大于指定日期 - 用于活动时间范围
+- ✅ **dateLess**: 日期必须小于指定日期 - 用于历史数据验证
 
-#### 号码验证逻辑
-- ✅ 提取手机号正则到 `lib/config/phonePatterns.js`
-- ✅ 实现配置与逻辑分离
+**使用示例**:
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+// String 验证器
+const schema = {
+  code: { type: 'string', exactLength: 6 },           // 验证码
+  username: { type: 'string', alphanum: true },       // 用户名
+  keyword: { type: 'string', trim: true },            // 搜索关键词
+  email: { type: 'string', lowercase: true },         // 邮箱
+  countryCode: { type: 'string', uppercase: true },   // 国家代码
+  config: { type: 'string', jsonString: true },       // JSON配置
+  
+  // Number 验证器
+  price: { type: 'number', precision: 2 },            // 价格（2位小数）
+  port: { type: 'integer', port: true },              // 端口号
+  
+  // Date 验证器
+  birthDate: { type: 'string', dateFormat: 'YYYY-MM-DD' },  // 生日
+  endDate: { type: 'string', dateGreater: '2025-01-01' },   // 结束日期
+  startDate: { type: 'string', dateLess: '2025-12-31' }     // 开始日期
+};
+```
 
-### 📝 文档更新
+#### 多语言支持
+- ✅ **中文消息**: 新增 19 个验证消息
+- ✅ **英文消息**: 新增 19 个验证消息
+- ✅ **错误消息键**: 统一使用 string.length, number.precision 等键名
 
-#### 移除 Joi 对比
-- ✅ `docs/type-reference.md` 移除 Joi 列，专注自身功能
+### 📝 文档 (Documentation)
+- ✅ 新增 `docs/validation-rules-v1.0.2.md` - 15个验证器详细文档（1200行）
+- ✅ 每个验证器包含：用途、参数、错误消息、使用方法、应用场景、最佳实践
+- ✅ 完整的代码示例和验证演示
+- ✅ 组合使用技巧和国际化支持说明
 
----
+### 🧪 测试 (Tests)
+- ✅ 新增 `test/unit/validators/CustomKeywords-v1.0.2.test.js`
+- ✅ 75 个单元测试用例，覆盖所有新增验证器
+- ✅ 每个验证器至少 5 个测试用例（正常、边界、错误情况）
+- ✅ 测试覆盖率: 100%
+- ✅ 所有测试通过: 602 passing
 
-## [v2.0.1] - 2025-12-25
+### 📦 示例 (Examples)
+- ⏳ 待补充 `examples/validation-rules-v1.0.2.examples.js`
 
-### 🔴 破坏性变更
+### 🔧 技术细节 (Technical Details)
 
-#### 移除简写功能
-- ❌ **不再支持类型简写** - `s/n/i/b/o/a` 等简写已移除
-- ✅ **使用完整类型名** - `string/number/integer/boolean/object/array`
-- **原因**: 降低学习成本，减少歧义，提升代码可读性
+**实现位置**: `lib/validators/CustomKeywords.js`
+- String 验证器: L210-334
+- Number 验证器: L342-389
+- Object 验证器: L397-441
+- Array 验证器: L449-499
+- Date 验证器: L507-608
 
-**迁移指南**:
-```javascript
-// ❌ v2.0.0 及之前
-dsl({ name: 's:3-32!' })
+**错误消息位置**: 
+- `lib/locales/zh-CN.js` (126 行)
+- `lib/locales/en-US.js` (126 行)
 
-// ✅ v2.0.1
-dsl({ name: 'string:3-32!' })
-```
+---
 
-### ✨ 新增功能
+## [v1.0.1] - 2025-12-31
 
-#### 补充类型（与 joi 对比）
-- ✅ `time` - 时间格式 (HH:mm:ss)
-- ✅ `ipv4` - IPv4 地址
-- ✅ `ipv6` - IPv6 地址
-- ✅ `binary` - 二进制数据 (Base64)
-- ✅ `any` - 任意类型
-- ✅ `null` - 空值类型
+### 🎉 新增功能 (Added)
 
-#### 数组 DSL 语法增强
-- ✅ `array!1-10` - 必填，1-10 个元素
-- ✅ `array:1-10` - 可选，1-10 个元素
-- ✅ `array!1-` - 必填，至少 1 个元素
-- ✅ `array!-10` - 必填，最多 10 个元素
-- ✅ `array!1-10<string:1-20>` - 完整约束（长度+元素）
+#### 枚举功能
+- ✅ **字符串枚举**: `'active|inactive|pending'` 简写语法
+- ✅ **布尔值枚举**: `'true|false'` 自动识别为布尔值
+- ✅ **数字枚举**: `'1|2|3'` 自动识别为数字
+- ✅ **整数枚举**: `'enum:integer:1|2|3'` 显式指定整数类型
+- ✅ **小数枚举**: `'1.0|1.5|2.0'` 支持小数值
+- ✅ **必填枚举**: `'active|inactive!'` 支持必填标记
+- ✅ **显式类型**: `'enum:type:values'` 显式指定枚举类型
 
-**示例**:
+**使用示例**:
 ```javascript
+const { dsl, validate } = require('schema-dsl');
+
 const schema = dsl({
-  tags: 'array!1-10<string:1-20>',  // 1-10个标签，每个1-20字符
-  items: 'array:1-<number:0-100>'   // 至少1个，每个0-100
+  // 字符串枚举（自动识别）
+  status: 'active|inactive|pending',
+  
+  // 布尔值枚举（自动识别）
+  isPublic: 'true|false',
+  
+  // 数字枚举（自动识别）
+  priority: '1|2|3',
+  
+  // 整数枚举（显式指定）
+  level: 'enum:integer:1|2|3',
+  
+  // 必填枚举
+  role: 'admin|user|guest!'
+});
+
+// 验证
+const result = validate(schema, {
+  status: 'active',
+  isPublic: true,
+  priority: 1,
+  level: 2,
+  role: 'admin'
 });
 ```
 
-#### 对象必填优化
-- ✅ **key! 语法** - 字段名带 `!` 表示该字段本身必填
+#### 统一错误消息
+- ✅ **统一 'enum' 键**: 所有枚举类型统一使用 `'enum'` 定义错误消息
+- ✅ **简化配置**: 不需要记忆不同类型的错误消息键名
+- ✅ **高级用法**: 支持 `'type.enum'` 格式按类型定制消息（可选）
 
-**示例**:
+**使用示例**:
 ```javascript
-// ✅ 优雅方式
-const schema = dsl({
-  'user!': {          // user 本身必填
-    name: 'string',    // name 可选
-    email: 'email'     // email 可选
-  }
-});
-
-// 对比旧方式
 const schema = dsl({
-  user: {
-    name: 'string!',   // name 必填（但 user 可选）
-    email: 'email!'
-  }
+  status: dsl('active|inactive').messages({
+    'enum': '状态必须是 active 或 inactive'  // 统一使用 enum
+  })
 });
 ```
 
-### 📝 文档更新
+### 📝 文档 (Documentation)
 
-#### 完全重写 DSL 语法文档
-- ✅ **行数减少 80%** - 从 2857 行精简到 567 行
-- ✅ **移除所有简写** - 只使用完整类型名
-- ✅ **简化示例** - 使用最简单的方式
-- ✅ **实现方案对比** - "不能这样 vs 只能这样"
+- ✅ **新增 docs/enum.md**: 完整的枚举功能文档（476行）
+- ✅ **更新 README.md**: 添加枚举语法说明
+- ✅ **新增示例**: examples/enum.examples.js（325行，10个示例）
 
-#### 新增完整类型文档
-- ✅ `docs/type-reference.md` - 完整类型列表
-- ✅ 与 joi 对比表
-- ✅ 所有类型使用示例
+### ✅ 测试 (Tests)
 
-### 🐛 Bug 修复
+- ✅ **新增 test/unit/enum.test.js**: 30个枚举测试用例
+- ✅ **测试覆盖**: 字符串/布尔值/数字/整数枚举全覆盖
+- ✅ **错误处理测试**: 无效枚举值、类型不匹配测试
 
-#### ErrorFormatter 多错误处理
-- ✅ 修复 `format()` 方法只处理单个错误的问题
-- ✅ 支持 ajv 返回的多个错误
-- ✅ `formatDetailed()` 正确处理 ajv 错误格式
-- ✅ `_interpolate()` 处理 undefined template
+### 📊 变更统计
 
-#### 嵌套深度计算修复
-- ✅ 修复深度计算包含根节点的问题
-- ✅ 从 properties 内部开始计数
-- ✅ 支持 `isRoot` 参数跳过根节点
-
-#### 数组 DSL 解析修复
-- ✅ 修复 `array!1-10` 被解析为 string 的问题
-- ✅ DslBuilder 构造函数支持 `array!数字` 格式
-- ✅ DslAdapter 和 DslBuilder 同步支持数组约束
-
-### 🧪 测试改进
-
-#### 测试通过率 100%
-- ✅ **215 个测试全部通过** (之前 211/215)
-- ✅ 数组 DSL 语法测试 5/5 通过
-- ✅ 删除简写测试 (已移除功能)
-- ✅ 修复 date 格式测试
-
-### 📦 其他改进
-
-#### 代码质量
-- ✅ 统一类型定义（移除简写）
-- ✅ 优化解析逻辑
-- ✅ 清理临时文件
-
----
-
-## [v2.0.0] - 2025-12-25 (内部版本)
-
-### ✨ 新增功能
-
-#### String 扩展（核心特性）
-- ✅ **字符串直接链式调用** - 无需 `dsl()` 包裹即可链式调用
-  ```javascript
-  // v1.0: dsl('email!').pattern(/custom/).label('邮箱')
-  // v2.0.1: 'email!'.pattern(/custom/).label('邮箱')
-  ```
-- ✅ **自动安装机制** - 启动时自动安装，支持手动卸载
-- ✅ **完整方法支持** - pattern(), label(), messages(), description(), custom(), when(), default()
-
-#### Schema 复用工具
-- ✅ `SchemaUtils.reusable()` - 创建可复用Schema片段
-- ✅ `SchemaUtils.createLibrary()` - 创建Schema片段库
-- ✅ `SchemaUtils.merge()` - 合并多个Schema
-- ✅ `SchemaUtils.extend()` - 扩展Schema（类似继承）
-- ✅ `SchemaUtils.pick()` - 筛选字段
-- ✅ `SchemaUtils.omit()` - 排除字段
-
-#### 批量验证与性能监控
-- ✅ `Validator.validateBatch()` - 批量验证数据
-- ✅ 性能统计 - 验证结果包含性能信息
-
-#### Schema 工具方法
-- ✅ `SchemaUtils.toMarkdown()` - 导出为Markdown文档
-- ✅ `SchemaUtils.toHTML()` - 导出为HTML文档
-- ✅ `SchemaUtils.clone()` - 深度克隆Schema
-- ✅ `DslBuilder.validateNestingDepth()` - 检测嵌套深度
-
-### 📝 文档更新
-- ✅ 新增 `docs/string-extensions.md` - String扩展详细文档
-- ✅ 更新 `README.md` - 添加v2.0.1新特性说明
-- ✅ 新增 `examples/string-extensions.js` - String扩展示例
-- ✅ 新增 `examples/v2.0.1-features.js` - 完整新功能示例
-
-### 🐛 已知限制
-- ⚠️ 数组DSL语法 `array!1-10` 尚未实现（计划中）
-- ⚠️ 快捷验证方法（phoneNumber/idCard等）计划作为插件提供
-
-### 📦 依赖更新
-- 无变更
+- **新增代码**: ~500 行
+- **新增测试**: 30 个
+- **新增文档**: 476 行
+- **新增示例**: 325 行
 
 ---
 
-## [v1.0.0] - 2025-12-24
-
-### 🎉 重大变更
-
-#### 架构重构
-- **适配器模式**: 完全重构为适配器模式架构
-- **核心统一**: 使用JSON Schema Draft 7作为统一内部表示
-- **API解耦**: Joi风格和DSL风格通过适配器转换
-
-#### 性能提升
-- **高性能验证**: 集成ajv验证器（业界最快）
-- **编译缓存**: 实现Schema编译结果缓存
-- **批量验证**: 支持批量数据验证
-
-### ✨ 新增功能
-
-#### 核心层
-- ✅ `JSONSchemaCore` - JSON Schema核心类
-  - 完整支持JSON Schema Draft 7标准
-  - 链式API设计
-  - Schema克隆、合并、验证
-
-- ✅ `Validator` - ajv验证器集成
-  - Schema编译缓存
-  - 自定义关键字支持
-  - 自定义格式支持
-  - 批量验证
-  - 错误格式化
-
-#### 适配器层
-- ✅ **Joi风格适配器**
-  - 完整的Joi风格链式API
-  - 支持所有基本类型（string/number/boolean/object/array）
-  - 支持约束方法（min/max/required/pattern等）
-  - 自动转换为JSON Schema
-
-- ✅ **DSL风格适配器**
-  - 简洁的DSL语法设计
-  - 支持类型定义（`string:3-32`）
-  - 支持必填标记（`!`）
-  - 支持枚举值（`active|inactive`）
-  - 支持数组类型（`array<string>`）
-  - 支持嵌套对象
-  - 支持格式类型（email/url/uuid/date）
-
-#### 导出器层
-- ✅ **MongoDB导出器**
-  - 转换为MongoDB $jsonSchema格式
-  - 生成createCollection命令
-  - 支持验证级别配置
-
-- ✅ **MySQL导出器**
-  - 生成CREATE TABLE DDL
-  - 智能类型映射（根据约束条件）
-  - 支持约束（NOT NULL/DEFAULT/COMMENT）
-  - 支持索引生成
-
-- ✅ **PostgreSQL导出器**
-  - 生成CREATE TABLE DDL
-  - 智能类型映射（JSONB/UUID/TIMESTAMP等）
-  - 支持CHECK约束
-  - 支持列注释和表注释
-
-#### 验证器扩展
-- ✅ **自定义关键字**
-  - regex关键字（正则验证）
-  - validate关键字（函数验证）
-  - range关键字（数值范围）
-
-#### 工具函数
-- ✅ `TypeConverter` - 类型转换工具
-  - JSON Schema ↔ MongoDB BSON类型
-  - JSON Schema ↔ MySQL数据类型
-  - JSON Schema ↔ PostgreSQL数据类型
-  - 格式验证函数转正则表达式
-
-- ✅ `SchemaHelper` - Schema辅助函数
-  - Schema验证和分析
-  - 字段路径提取
-  - 扁平化和克隆
-  - 复杂度评估
-
-### 📝 文档和示例
-
-- ✅ **README.md** - 完整项目文档
-  - 快速开始指南
-  - DSL语法指南
-  - API文档
-  - 完整示例
-
-- ✅ **示例文件**
-  - `joi-style.js` - Joi风格完整示例
-  - `dsl-style.js` - DSL风格完整示例
-
-### 🔧 改进
-
-#### 代码质量
-- ✅ 完整的JSDoc注释
-- ✅ 清晰的命名规范（camelCase/PascalCase）
-- ✅ 模块化设计（高内聚低耦合）
-- ✅ 错误处理完善
-
-#### 开发体验
-- ✅ package.json脚本完善
-- ✅ 依赖管理优化
-- ✅ 示例代码丰富
-
-### 🐛 修复
-
-- ✅ 修复DSL适配器的_required标记清理问题
-- ✅ 修复DSL枚举值解析问题
-- ✅ 修复数组类型DSL解析问题
-- ✅ 优化JoiAdapter的compile方法
-
-### 📦 依赖变更
-
-#### 新增依赖
-```json
-{
-  "ajv": "^8.17.1",
-  "ajv-formats": "^2.1.1"
-}
-```
-
-#### 新增开发依赖
-```json
-{
-  "mocha": "^10.8.2",
-  "chai": "^4.5.0",
-  "sinon": "^17.0.1",
-  "nyc": "^15.1.0",
-  "eslint": "^8.57.1",
-  "monsqlize": "^1.0.1"
-}
-```
+## [v1.0.0] - 2025-12-29
 
-### 📊 统计信息
-
-- **代码行数**: ~3200行
-- **文件数**: 17个核心文件
-- **功能完成度**: 98%
-- **测试覆盖率**: 0%（待补充）
-
----
+### 🎉 初始发布
 
-## [v0.1.0] - 2025-12-XX
-
-### ✨ 初始版本
+#### 核心功能
+- ✅ **DSL 语法**: 简洁的字符串 DSL 定义 Schema
+  - `'string:3-32!'` - 字符串长度 3-32，必填
+  - `'number:0-100'` - 数字范围 0-100
+  - `'email!'` - 邮箱格式，必填
+  
+- ✅ **基础类型**: string, number, integer, boolean, object, array, null
 
-- 基础框架搭建
-- 类型系统设计
-- SchemaBuilder原型
-- 目录结构规划
+- ✅ **格式类型**: email, url, uuid, date, datetime, time, ipv4, ipv6, binary
 
----
+- ✅ **模式类型**: 
+  - objectId - MongoDB ObjectId
+  - hexColor - 十六进制颜色
+  - macAddress - MAC 地址
+  - cron - Cron 表达式
+  - phone - 手机号（支持多国）
+  - idCard - 身份证号
+  - creditCard - 信用卡号
+  - licensePlate - 车牌号
+  - postalCode - 邮政编码
+  - passport - 护照号
 
-## 待发布
+- ✅ **验证功能**: 
+  - `validate(schema, data)` - 同步验证
+  - `validateAsync(schema, data)` - 异步验证
 
-### v1.1.0（计划中）
+- ✅ **错误格式化**: 友好的错误消息
 
-#### 计划新增
-- [ ] ChainAdapter - 链式风格适配器
-- [ ] 完整测试套件（覆盖率80%+）
-- [ ] TypeScript类型定义
-- [ ] 性能基准测试
+- ✅ **多语言支持**: zh-CN, en-US
 
-#### 计划改进
-- [ ] JoiAdapter required处理优化
-- [ ] 错误提示优化
-- [ ] 文档补充（API详细文档）
-
----
+- ✅ **链式 API**: String 扩展，支持 `.label()`, `.messages()`, `.pattern()` 等
 
-## 变更类型说明
+- ✅ **SchemaUtils**: omit, pick, partial, extend 工具方法
 
-- `✨ 新增`: 新功能
-- `🔧 改进`: 功能改进或优化
-- `🐛 修复`: Bug修复
-- `📝 文档`: 文档更新
-- `🎨 样式`: 代码格式调整
-- `♻️ 重构`: 代码重构
-- `⚡ 性能`: 性能优化
-- `🔒 安全`: 安全问题修复
-- `📦 依赖`: 依赖更新
-- `🎉 重大`: 重大变更
+#### 文档和测试
+- ✅ **完整文档**: README, API 文档, 示例代码
+- ✅ **测试覆盖**: 447+ 测试用例，覆盖率 >90%
 
 ---
 
-**维护说明**: 请在每次发布新版本时更新此文档
+**更多历史版本信息请参考 Git 提交记录**