schema-dsl 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -11,6 +11,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [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) |
@@ -18,6 +19,63 @@
 
 ---
 
+## [v1.0.4] - 2025-12-31
+
+### Added (新增功能)
+
+#### TypeScript 完整支持 ⭐
+
+- ✅ **完整的类型定义**
+  - 新增 `validateAsync` 函数类型定义
+  - 新增 `ValidationError` 类完整类型（包含所有方法）
+  - 优化 String 扩展的 TypeScript 说明
+
+- ✅ **TypeScript 使用指南**
+  - 创建完整的 TypeScript 使用文档 (`docs/typescript-guide.md`)
+  - 1000+ 行详细说明，涵盖从基础到高级所有场景
+  - 3个完整实战案例（用户注册、API验证、字段复用）
+  - 5个常见问题解答
+
+- ✅ **TypeScript 链式调用最佳实践**
+  ```typescript
+  // ✅ 推荐：使用 dsl() 包裹获得完整类型推导
+  const schema = dsl({
+    email: dsl('email!').label('邮箱').pattern(/custom/)
+  });
+  
+  // ❌ 不推荐：可能缺少类型提示
+  const schema = dsl({
+    email: 'email!'.label('邮箱')
+  });
+  ```
+
+### Improved (改进)
+
+- 📝 **README 更新**
+  - 添加 "1.5 TypeScript 用法" 快速开始章节
+  - 添加 TypeScript 使用指南链接
+  - 清晰说明 TypeScript 和 JavaScript 的不同用法
+
+- 🔧 **类型定义优化**
+  - 修复 `dsl.config` 的 `i18n` 参数类型错误
+  - 统一 `DslConfigOptions` 和 `dsl.config` 的类型定义
+  - 标记 String 扩展方法为 `@deprecated` for TypeScript
+
+### Documentation (文档)
+
+- 📚 新增文档
+  - `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 (重要说明)
+
+- ✅ **100% 向后兼容** - JavaScript 用户无需任何改变
+- ✅ **TypeScript 用户推荐使用 `dsl()` 包裹字符串** 以获得完整类型推导
+- ✅ **所有 API 都有完整的 TypeScript 类型定义**
+
+---
+
 ## [v1.0.3] - 2025-12-31
 
 ### ⚠️ 破坏性变更 (Breaking Changes)

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);
 ```
 
 **✅ 独家功能**：从验证规则直接生成数据库结构！
@@ -172,10 +177,13 @@ npm install schema-dsl
 
 ## 🚀 快速开始
 
-### 1. 基础验证
+### 1. 基础验证（JavaScript）
 
 ```javascript
 const { dsl, validate } = require('schema-dsl');
+
+const userSchema = dsl({
+  username: 'string:3-32!',
   email: 'email!',
   age: 'number:18-120',
   tags: 'array<string>'
@@ -210,7 +218,52 @@ console.log(result2.errors);   // 错误列表
 */
 ```
 
-### Express 集成 - 自动错误处理
+### 1.5 TypeScript 用法 ⭐
+
+**重要**: TypeScript 中使用链式调用需要用 `dsl()` 包裹字符串以获得完整的类型推导：
+
+```typescript
+import { dsl, validateAsync, ValidationError } from 'schema-dsl';
+
+// ✅ 推荐：使用 dsl() 包裹字符串获得完整类型提示
+const userSchema = dsl({
+  username: dsl('string:3-32!')
+    .pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')
+    .label('用户名'),
+  
+  email: dsl('email!')
+    .label('邮箱地址')
+    .messages({ required: '邮箱必填' }),
+  
+  age: dsl('number:18-100')
+    .label('年龄')
+});
+
+// 异步验证（推荐）
+try {
+  const validData = await validateAsync(userSchema, {
+    username: 'testuser',
+    email: 'test@example.com',
+    age: 25
+  });
+  console.log('验证通过:', validData);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    error.errors.forEach(err => {
+      console.log(`${err.path}: ${err.message}`);
+    });
+  }
+}
+```
+
+**为什么要用 `dsl()` 包裹？**
+- ✅ 完整的类型推导和 IDE 自动提示
+- ✅ 避免 TypeScript 严格模式警告
+- ✅ 更好的开发体验
+
+**详细说明**: 请查看 [TypeScript 使用指南](./docs/typescript-guide.md)
+
+### 2. Express 集成 - 自动错误处理
 
 ```javascript
 const { dsl, validateAsync, ValidationError } = require('schema-dsl');
@@ -477,17 +530,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)
+
 ---
 
 ## 🔧 核心功能
@@ -605,32 +723,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')
 });
 
 // 验证时指定语言
@@ -639,16 +761,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');
@@ -700,7 +850,7 @@ const schema = dsl({
 });
 ```
 
-### 6. 错误处理
+### 7. 错误处理
 
 ```javascript
 const { validate, ValidationError } = require('schema-dsl');
@@ -937,6 +1087,7 @@ const dynamicSchema = dsl(
 - [快速开始](./docs/quick-start.md) - 5分钟上手指南
 - [DSL 语法完整参考](./docs/dsl-syntax.md) - 所有语法详解
 - [API 文档](./docs/api-reference.md) - 完整 API 说明
+- [**TypeScript 使用指南**](./docs/typescript-guide.md) - TypeScript 最佳实践 ⭐
 
 ### 功能指南
 - [String 扩展方法](./docs/string-extensions.md) - 链式调用详解

package/STATUS.md

@@ -1,13 +1,14 @@
 # schema-dsl 项目状态
 
 > **最后更新**: 2025-12-31  
-> **当前版本**: v1.0.3  
+> **当前版本**: v1.0.4  
 > **项目状态**: ✅ 全部完成，测试100%通过  
 
 ---
 
 ## 📋 目录
 
+- [v1.0.4](#v104) - 2025-12-31 ✅ 已完成
 - [v1.0.3](#v103) - 2025-12-31 ⚠️ 破坏性变更
 - [v1.0.2](#v102) - 2025-12-31 ✅ 已完成
 - [v1.0.1](#v101) - 2025-12-31 ✅ 已完成
@@ -17,6 +18,43 @@
 
 ## 版本发布计划
 
+### v1.0.4
+
+**发布日期**: 2025-12-31  
+**状态**: ✅ 已完成  
+**类型**: ✨ 功能增强（TypeScript 完整支持）  
+**进度**: 100%完成 | 新增: TypeScript 类型定义、使用指南 | 文档: 1500+ 行
+
+| 需求标题 | 状态 | 优先级 | 详细 |
+|---------|------|--------|------|
+| 完善 index.d.ts | ✅ 完成 | P0 | validateAsync、ValidationError 类型 |
+| String 扩展 TS 说明 | ✅ 完成 | P0 | 添加详细使用说明和对比 |
+| TypeScript 使用指南 | ✅ 完成 | P0 | 1000+ 行完整文档 |
+| README 更新 | ✅ 完成 | P0 | 添加 TypeScript 章节 |
+| 类型错误修复 | ✅ 完成 | P0 | 修复 dsl.config i18n 类型 |
+| 发版文档更新 | ✅ 完成 | P0 | CHANGELOG、STATUS、package.json |
+
+**实现状态统计**:
+- ✅ 完成: 6个
+- 🔄 进行中: 0个
+- ⏳ 待完成: 0个
+
+**核心变更**:
+- ✅ **新增**: validateAsync 函数完整类型定义
+- ✅ **新增**: ValidationError 类完整类型（含所有方法）
+- ✅ **优化**: String 扩展添加 TypeScript 使用说明
+- ✅ **新增**: TypeScript 使用指南文档（1000+ 行）
+- ✅ **修复**: dsl.config 的 i18n 参数类型错误
+- ✅ **文档**: README 添加 TypeScript 快速开始章节
+
+**用户价值**:
+- 🎯 TypeScript 用户获得完整的类型安全和 IDE 提示
+- 🎯 详细的文档指导如何在 TypeScript 中正确使用
+- 🎯 JavaScript 用户体验不变，100% 向后兼容
+- 🎯 降低学习成本，提高开发效率
+
+---
+
 ### v1.0.3
 
 **发布日期**: 2025-12-31  

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