schema-dsl 1.2.4 → 2.0.0

package/docs/INDEX.md

@@ -1,252 +0,0 @@
-# schema-dsl 文档索引
-
-> **更新时间**: 2025-12-29  
-> **用途**: 所有文档的快速导航  
-> **文档数量**: 27个文档（总计 12,450+ 行）
-
----
-
-## 📑 目录
-
-### 快速导航
-- [🚀 快速开始](#-快速开始) - 入门必读
-- [📖 核心文档](#-核心文档) - 主要功能文档
-- [🎯 功能索引](#-功能索引) - 按功能查找
-- [🗄️ 导出器](#️-导出器) - 数据库Schema导出
-- [🛠️ 工具类](#️-工具类utilities) - 辅助工具
-- [📖 使用指南](#-使用指南guides) - 完整教程
-- [🔧 故障排查](#-故障排查troubleshooting) - 问题解决
-- [📝 示例代码](#-示例代码examples) - 完整示例
-- [❓ 常见问题](#-常见问题faq) - FAQ
-
----
-
-## 🚀 快速开始
-
-| 文档 | 阅读时间 | 说明 |
-|------|----------|------|
-| [README.md](../README.md) | 3分钟 | 项目介绍、安装和快速开始 ⭐ |
-| [quick-start.md](quick-start.md) | 5分钟 | 5分钟快速上手教程 ⭐ |
-| [design-philosophy.md](design-philosophy.md) | 15分钟 | **设计理念与性能权衡** ⭐⭐⭐ |
-| [FEATURE-INDEX.md](FEATURE-INDEX.md) | 10分钟 | 完整功能索引 ⭐ |
-| [best-practices.md](best-practices.md) | 15分钟 | 最佳实践指南 ⭐⭐⭐ |
-| [faq.md](faq.md) | 5分钟 | 常见问题解答 |
-
----
-
-## 📖 核心文档
-
-### DSL 语法（核心功能）
-
-| 文档 | 行数 | 说明 |
-|------|------|------|
-| [dsl-syntax.md](dsl-syntax.md) | 2815行 | **DSL语法完整指南**（最重要）⭐⭐⭐ |
-| [string-extensions.md](string-extensions.md) | 465行 | **String扩展文档** ⭐⭐ |
-| [plugin-system.md](plugin-system.md) | 580行 | **插件系统指南** ⭐⭐ |
-| [api-reference.md](api-reference.md) | 534行 | API完整参考 ⭐⭐ |
-| [validate.md](validate.md) | 452行 | validate方法详解 ⭐ |
-| [**validate-async.md**](validate-async.md) | ~700行 | **异步验证方法详解** ⭐⭐⭐ |
-| [**schema-utils-chaining.md**](schema-utils-chaining.md) | ~680行 | **Schema链式复用方法** ⭐⭐⭐ |
-| [**schema-utils-best-practices.md**](schema-utils-best-practices.md) | ~500行 | **SchemaUtils最佳实践与常见陷阱** ⭐⭐⭐ |
-| [**schema-utils-advanced-issues.md**](schema-utils-advanced-issues.md) | ~600行 | **SchemaUtils深入问题分析** ⭐⭐ |
-
----
-
-## 🎯 功能索引
-
-### 核心API
-
-| 功能 | 文档 | 代码位置 |
-|------|------|---------|
-| dsl() 函数 | [api-reference.md](api-reference.md#dsl-函数) | `lib/adapters/DslAdapter.js` |
-| DslBuilder 类 | [api-reference.md](api-reference.md#dslbuilder-类) | `lib/core/DslBuilder.js` |
-| String 扩展 | [string-extensions.md](string-extensions.md) | `lib/core/StringExtensions.js` |
-| Validator 类 | [validate.md](validate.md) | `lib/core/Validator.js` |
-| validate() 函数 | [api-reference.md](api-reference.md) | `index.js` |
-| validateAsync() 函数 | [validate-async.md](validate-async.md) | `index.js` |
-| ValidationError 类 | [validate-async.md](validate-async.md#validationerror) | `lib/errors/ValidationError.js` |
-| SchemaUtils 链式调用 | [schema-utils-chaining.md](schema-utils-chaining.md) | `lib/utils/SchemaUtils.js` |
-
-
----
-
-## 🗄️ 导出器
-
-> 将 JSON Schema 转换为数据库 DDL 和验证规则
-
-> ⚠️ **重要提示**: 请先阅读 [**导出限制说明**](export-limitations.md)，了解哪些特性无法导出到数据库 Schema。
-
-### 导出限制说明 ⚠️
-
-| 文档 | 说明 |
-|------|------|
-| [**export-limitations.md**](export-limitations.md) | **导出限制完整说明**（必读）⭐⭐⭐ |
-
-**主要内容**:
-- ❌ 不支持导出的特性（条件验证、自定义验证器等）
-- ⚠️ 部分支持的特性（正则、范围、枚举等）
-- ✅ 完全支持的特性（基础类型、必填约束等）
-- 数据库特定限制对比（MongoDB/MySQL/PostgreSQL）
-- 最佳实践建议（分层验证、文档化约束等）
-
-### MongoDB 导出器
-
-| 文档 | 行数 | 说明 |
-|------|------|------|
-| [mongodb-exporter.md](mongodb-exporter.md) | ~200行 | MongoDB 导出器完整指南 |
-
-**主要功能**:
-- `export()` - 导出 $jsonSchema 验证规则
-- `generateCreateCommand()` - 生成创建集合命令（含验证）
-- `generateCommand()` - 生成完整 runCommand 命令
-- `MongoDBExporter.export()` - 静态快速导出方法
-
-### MySQL 导出器
-
-| 文档 | 行数 | 说明 |
-|------|------|------|
-| [mysql-exporter.md](mysql-exporter.md) | ~220行 | MySQL 导出器完整指南 |
-
-**主要功能**:
-- `export()` - 导出 CREATE TABLE DDL
-- `generateIndex()` - 生成 CREATE INDEX DDL
-- 支持 ENGINE、CHARSET、COLLATE 配置
-
-### PostgreSQL 导出器
-
-| 文档 | 行数 | 说明 |
-|------|------|------|
-| [postgresql-exporter.md](postgresql-exporter.md) | ~280行 | PostgreSQL 导出器完整指南 |
-
-**主要功能**:
-- `export()` - 导出 CREATE TABLE DDL（含 CHECK 约束）
-- `generateIndex()` - 生成索引 DDL（支持 btree/gin/gist/hash）
-- 支持 Schema 命名空间和 COMMENT
-
----
-
-## 🛠️ 工具类（Utilities）
-
-| 文档 | 行数 | 说明 |
-|------|------|------|
-| [type-converter.md](type-converter.md) | ~250行 | TypeConverter - 类型转换工具 |
-| [schema-helper.md](schema-helper.md) | ~220行 | SchemaHelper - Schema 辅助工具 |
-| [cache-manager.md](cache-manager.md) | ~250行 | CacheManager - LRU缓存管理 |
-
-### TypeConverter 主要功能
-- `toMongoDBType()` - 转换为 MongoDB 类型
-- `toMySQLType()` - 转换为 MySQL 类型  
-- `toPostgreSQLType()` - 转换为 PostgreSQL 类型
-- `extractConstraints()` - 提取约束信息
-- `mergeSchemas()` - 合并多个 Schema
-
-### SchemaHelper 主要功能
-- `isValidSchema()` - 验证 Schema 合法性
-- `cloneSchema()` - 深度克隆 Schema
-- `flattenSchema()` - 扁平化嵌套 Schema
-- `getFieldPaths()` - 获取所有字段路径
-- `summarizeSchema()` - 生成 Schema 摘要
-
-### CacheManager 主要功能
-- LRU 缓存策略（最近最少使用淘汰）
-- TTL 过期支持
-- 缓存统计（命中率、大小等）
-- 线程安全设计
-
----
-
-## 📖 使用指南（Guides）
-
-| 文档 | 行数 | 说明 |
-|------|------|------|
-| [validation-guide.md](validation-guide.md) | ~400行 | 数据验证完整指南 |
-| [export-guide.md](export-guide.md) | ~350行 | 数据库导出完整指南 |
-| [error-handling.md](error-handling.md) | ~640行 | 错误处理最佳实践 |
-
-### 验证指南内容
-- 基础验证流程
-- 字段类型验证（字符串/数字/布尔/数组/对象）
-- 常用业务验证模式
-- 批量验证与性能优化
-- 错误处理最佳实践
-
-### 导出指南内容
-- MongoDB/MySQL/PostgreSQL 导出对比
-- 配置与自定义选项
-- 自动化迁移脚本
-- 版本管理与最佳实践
-- **⚠️ [导出限制说明](export-limitations.md) - 哪些特性无法导出** ⭐⭐⭐
-
-
-- 数据库导出概述
-- MongoDB/MySQL/PostgreSQL 导出教程
-- 多数据库同步方案
-- 类型映射参考表
-- 最佳实践与常见问题
-
----
-
-## 📝 示例代码（Examples）
-
-| 文件 | 说明 |
-|------|------|
-| [simple-example.js](../examples/simple-example.js) | 简单示例 |
-| [dsl-style.js](../examples/dsl-style.js) | DSL 风格完整示例 |
-| [string-extensions.js](../examples/string-extensions.js) | String 扩展示例 |
-| [password-reset/](../examples/password-reset/) | 密码重置表单示例 |
-
----
-
-## ❓ 常见问题（FAQ）
-
-| 文档 | 说明 |
-|------|------|
-| [faq.md](faq.md) | 常见问题与解答 |
-
-**热门问题**:
-- DSL 语法与 Joi 语法的区别？
-- 如何自定义验证规则？
-- 如何优化验证性能？
-- 不同数据库的类型映射？
-- 如何处理验证错误？
-
----
-
-## 🔧 开发指南
-
-| 文档 | 说明 |
-|------|------|
-| [CONTRIBUTING.md](../CONTRIBUTING.md) | 贡献指南 |
-
----
-
-## 📊 版本信息
-
-| 文档 | 说明 |
-|------|------|
-| [STATUS.md](../STATUS.md) | 项目状态（243个测试全部通过）|
-| [CHANGELOG.md](../CHANGELOG.md) | 更新日志 |
-
----
-
-## 📁 文档统计
-
-| 分类 | 文档数 | 总行数 |
-|------|--------|--------|
-| 核心文档 | 4 | ~4,266 |
-| 导出器文档 | 3 | ~700 |
-| 工具类文档 | 3 | ~720 |
-| 使用指南 | 3 | ~1,390 |
-| 其他文档 | 9 | ~500 |
-| **合计** | **22** | **~7,576** |
-
----
-
-**图例说明**:
-- ⭐ 重点推荐文档
-- ⭐⭐ 核心文档
-- ⭐⭐⭐ 必读文档
-
-**最后更新**: 2025-12-29
-
-

package/docs/issues-resolved-summary.md

@@ -1,196 +0,0 @@
-# 问题解答总结
-
-## 问题1：npm run test 没看到执行
-
-### 问题描述
-执行 `npm run test` 后，没有看到任何输出。
-
-### 原因分析
-这是 **Windows PowerShell 编码问题**，不是测试本身的问题。
-
-### 验证结果
-测试文件 `test-output.txt` 显示：
-```
-983 passing (5s)
-```
-
-**✅ 所有 983 个测试全部通过！**
-
-测试完全正常执行，只是因为：
-- Windows PowerShell 的编码问题导致中文显示为乱码
-- PowerShell 的输出重定向机制导致终端显示为空
-- 但测试本身没有任何问题
-
-### 解决方案
-
-**方式1：保存到文件查看**
-```powershell
-npm test > test-output.txt 2>&1
-type test-output.txt
-```
-
-**方式2：使用 Git Bash 或 WSL**
-```bash
-npm test
-```
-
-**方式3：只看测试结果摘要**
-```powershell
-npm test 2>&1 | Select-String "passing|failing"
-```
-
----
-
-## 问题2：直接用对象会有什么影响？
-
-### 您的理解
-
-> "我理解是如果要高性能，直接项目启动的时候就配置好 schema 对吗？如果直接在接口中配置的话每次都会重复转换"
-
-### 答案
-
-**✅ 您的理解完全正确！** 👍
-
-### 详细说明
-
-#### ❌ 性能较差：每次请求都转换
-
-```javascript
-app.post('/api/user', (req, res) => {
-  const result = validate(
-    { email: 'email!', age: 'number!' },  // ❌ 每次请求都转换
-    req.body
-  );
-});
-```
-
-**问题**：
-- 每次请求都执行 DSL → JSON Schema 转换
-- 1000 次请求 = 1000 次转换
-- 性能损失约 3-5%
-- 高并发时影响明显
-
-#### ✅ 性能最优：项目启动时配置
-
-```javascript
-// schemas/user.js - 项目启动时加载
-const userSchemas = {
-  register: dsl({
-    email: 'email!',
-    age: 'number!'
-  })
-};
-
-module.exports = userSchemas;
-
-// routes/user.js - 路由中使用
-const userSchemas = require('../schemas/user');
-
-app.post('/api/user', (req, res) => {
-  const result = validate(userSchemas.register, req.body);  // ✅ 直接使用
-});
-```
-
-**优势**：
-- 启动时转换 1 次
-- 1000 次请求 = 0 次转换
-- 性能最优
-- 适合生产环境
-
-### 性能对比
-
-| 方式 | 1000次请求耗时 | 转换次数 | 适用场景 |
-|------|---------------|---------|---------|
-| 每次都转换 | ~3.4秒 | 1000次 | 原型开发、测试 |
-| 启动时配置 | ~3.3秒 | 1次 | 生产环境、高并发 |
-| **性能差异** | **约3-5%** | - | - |
-
-### 使用建议
-
-| 场景 | 推荐方式 | 原因 |
-|------|---------|------|
-| **生产环境 API** | ✅ 项目启动时配置 schema | 避免每次请求都转换 |
-| **高并发服务** | ✅ 项目启动时配置 schema | 3-5% 的性能损失会被放大 |
-| **微服务** | ✅ 项目启动时配置 schema | 保证响应时间稳定 |
-| **单次脚本** | ✅ 直接用 DSL 对象 | 只执行一次，性能影响可忽略 |
-| **原型开发** | ✅ 直接用 DSL 对象 | 快速迭代，无需在意性能 |
-| **测试代码** | ✅ 直接用 DSL 对象 | 简洁清晰，易于维护 |
-
-### 最佳实践示例
-
-#### 1. 定义 Schema（schemas/user.js）
-
-```javascript
-const { dsl } = require('schema-dsl');
-
-// ✅ 项目启动时转换一次
-module.exports = {
-  register: dsl({
-    username: 'string:3-32!',
-    email: 'email!',
-    password: 'password:strong!'
-  }),
-  
-  login: dsl({
-    username: 'string!',
-    password: 'string!'
-  })
-};
-```
-
-#### 2. 在路由中使用（routes/user.js）
-
-```javascript
-const userSchemas = require('../schemas/user');
-const { validate } = require('schema-dsl');
-
-// ✅ 直接使用，不再转换
-app.post('/api/register', (req, res) => {
-  const result = validate(userSchemas.register, req.body);
-  // ...
-});
-
-app.post('/api/login', (req, res) => {
-  const result = validate(userSchemas.login, req.body);
-  // ...
-});
-```
-
-#### 3. 主应用入口（app.js）
-
-```javascript
-// ✅ 应用启动时加载所有 schema
-const schemas = require('./schemas');
-console.log('✅ Schemas loaded:', Object.keys(schemas));
-
-// 启动服务
-app.listen(3000, () => {
-  console.log('✅ Server started');
-  console.log('✅ All schemas are pre-compiled and ready to use');
-});
-```
-
----
-
-## 相关文档
-
-1. **validate-dsl-object-support.md** - 完整功能说明
-2. **best-practices-project-structure.md** - 项目结构最佳实践（含完整示例）
-3. **user-questions-answered.md** - 之前问题的详细解答
-
----
-
-## 总结
-
-### 问题1
-- ✅ 测试完全正常，983 个全部通过
-- ✅ 只是 PowerShell 编码问题导致显示异常
-- ✅ 可以通过保存到文件查看或使用其他终端
-
-### 问题2
-- ✅ 您的理解完全正确
-- ✅ 生产环境应该在项目启动时配置好所有 schema
-- ✅ 避免每次请求都重复转换，性能最优
-- ✅ 已提供完整的项目结构和代码示例
-
-**所有问题已完全解决！** 🎉

package/docs/performance-benchmark-report.md

@@ -1,179 +0,0 @@
-# schema-dsl 性能测试报告
-
-## 📋 测试概述
-
-**测试日期**: 2024-01-XX  
-**测试版本**: v1.0.4  
-**测试环境**: Node.js (运行环境)  
-**对比库**: Joi, Yup, Zod, Ajv  
-
-## 🎯 测试目标
-
-验证 schema-dsl 在真实场景下的性能表现，并与主流验证库进行公平对比。
-
-## 🔬 测试方法
-
-### 公平性保证
-
-1. **预编译Schema**: 所有库的 schema 均在测试前预编译，避免编译时间影响测试结果
-2. **JIT预热**: 每个测试前执行 10% 的预热迭代，确保 V8 引擎充分优化
-3. **多轮测试**: 每个测试执行 10 轮，移除最高/最低值，取平均值
-4. **高精度计时**: 使用 `process.hrtime.bigint()` 实现纳秒级精度
-5. **无异常处理干扰**: 移除性能关键路径中的 try-catch，避免 JIT 反优化
-6. **统一测试数据**: 所有库使用完全相同的测试数据结构
-
-### 测试配置
-
-```javascript
-// 简单验证场景
-iterations: 10000
-rounds: 10
-warmup: 1000 (10%)
-
-// 复杂验证场景  
-iterations: 5000
-rounds: 10
-warmup: 500 (10%)
-```
-
-### 测试场景
-
-#### 场景1: 简单对象验证
-```javascript
-{
-  username: 'john_doe',
-  email: 'john@example.com',
-  age: 25
-}
-```
-
-#### 场景2: 复杂嵌套验证
-```javascript
-{
-  name: 'John Doe',
-  email: 'john@example.com',
-  profile: {
-    age: 30,
-    bio: 'Software developer',
-    tags: ['javascript', 'nodejs']
-  }
-}
-```
-
-## 📊 测试结果
-
-### 10轮完整测试汇总
-
-#### 简单验证性能
-| 验证库 | 平均吞吐量 | 最低吞吐量 | 最高吞吐量 | 标准差 | 稳定性 |
-|--------|-----------|-----------|-----------|--------|-------|
-| **schema-dsl** | **4,130,506/s** | 3,694,035/s | 4,563,536/s | 266,785 | ⭐⭐⭐⭐ |
-| Joi | 466,616/s | 448,739/s | 477,551/s | 7,941 | ⭐⭐⭐⭐⭐ |
-| Yup | 318,888/s | 309,023/s | 324,891/s | 4,268 | ⭐⭐⭐⭐⭐ |
-| Zod | 9,743,926/s | 8,247,990/s | 10,450,049/s | 646,068 | ⭐⭐⭐⭐ |
-| Ajv | 21,456,535/s | 17,460,641/s | 25,036,512/s | 2,602,772 | ⭐⭐⭐ |
-
-#### 复杂验证性能
-| 验证库 | 平均吞吐量 | 最低吞吐量 | 最高吞吐量 | 标准差 | 稳定性 |
-|--------|-----------|-----------|-----------|--------|-------|
-| **schema-dsl** | **3,159,137/s** | 2,910,530/s | 3,345,526/s | 145,171 | ⭐⭐⭐⭐⭐ |
-| Joi | 242,500/s | 233,608/s | 251,069/s | 4,410 | ⭐⭐⭐⭐⭐ |
-| Yup | 70,313/s | 65,425/s | 72,158/s | 2,016 | ⭐⭐⭐⭐⭐ |
-| Zod | 2,487,493/s | 2,313,726/s | 2,762,660/s | 130,431 | ⭐⭐⭐⭐⭐ |
-| Ajv | 9,021,336/s | 8,012,179/s | 10,069,141/s | 632,381 | ⭐⭐⭐⭐ |
-
-### 性能对比分析
-
-#### schema-dsl vs 其他库
-
-**简单验证场景**:
-- **vs Joi**: 快 **8.85倍** (413万/s vs 47万/s)
-- **vs Yup**: 快 **12.95倍** (413万/s vs 32万/s)
-- **vs Zod**: 慢 0.42倍 (413万/s vs 974万/s)
-- **vs Ajv**: 慢 0.19倍 (413万/s vs 2146万/s)
-
-**复杂验证场景**:
-- **vs Joi**: 快 **13.03倍** (316万/s vs 24万/s)
-- **vs Yup**: 快 **44.93倍** (316万/s vs 7万/s)
-- **vs Zod**: 快 **1.27倍** (316万/s vs 249万/s) ⭐
-- **vs Ajv**: 慢 0.35倍 (316万/s vs 902万/s)
-
-## 🎯 核心发现
-
-### 1. 简洁性与性能的平衡
-
-schema-dsl 在保持最简洁 DSL 语法的同时：
-- 比 Joi 快 **9-13倍**
-- 比 Yup 快 **13-45倍**  
-- **复杂场景超越 Zod 1.3倍**
-
-### 2. 复杂场景优势明显
-
-随着验证规则复杂度增加，schema-dsl 的优势更加明显：
-- 简单场景: 优于 Joi/Yup，但不及 Zod/Ajv
-- **复杂场景: 超越 Zod，仅次于 Ajv**
-
-### 3. 性能稳定性
-
-标准差分析显示：
-- **schema-dsl**: 中等稳定性（简单: 266k, 复杂: 145k）
-- **Joi/Yup/Zod**: 非常稳定（标准差 < 20k）
-- **Ajv**: 波动较大（标准差 > 600k）
-
-## 💡 选型建议
-
-### 选择 schema-dsl 的理由
-
-✅ **追求简洁性**: `'string:3-32!'` vs `Joi.string().min(3).max(32).required()`  
-✅ **复杂验证场景**: 嵌套对象、数组验证性能超越 Zod  
-✅ **平衡性能与可读性**: 比 Joi/Yup 快得多，语法比 Ajv 简单得多  
-✅ **多语言支持**: 内置 5 种语言错误消息自动翻译  
-
-### 其他库的优势
-
-- **Ajv**: 极致性能要求（但需要学习 JSON Schema）
-- **Zod**: TypeScript 类型推导（但复杂场景性能不如 schema-dsl）
-- **Joi**: 生态成熟、稳定可靠（但性能和简洁性较差）
-- **Yup**: 与 Formik 集成好（但性能最慢）
-
-## 🔧 测试改进历史
-
-### 之前的测试问题
-
-1. ❌ Yup 测试中使用 try-catch 导致 JIT 反优化
-2. ❌ 缺少 JIT 预热阶段，冷启动影响结果
-3. ❌ 单次运行，受垃圾回收等因素影响
-4. ❌ 使用 Date.now() 计时，精度不足（±1ms）
-
-### 改进后的测试
-
-1. ✅ 移除所有性能关键路径的 try-catch
-2. ✅ 添加 10% 预热迭代确保 JIT 优化
-3. ✅ 10 轮测试取平均值，移除异常值
-4. ✅ 使用 process.hrtime.bigint() 纳秒级计时
-
-### 性能数据修正
-
-| 版本 | 简单验证 | 复杂验证 | 变化 |
-|------|---------|---------|------|
-| 旧测试 | 50万/s | 63万/s | 基准 |
-| 新测试 | **413万/s** | **316万/s** | ⬆️ 8.3倍 / 5.0倍 |
-
-**注**: 旧测试方法的不公平性导致低估了 schema-dsl 的真实性能。
-
-## 📝 结论
-
-schema-dsl 成功实现了 **"简洁性"** 与 **"性能"** 的平衡：
-
-1. **DSL 语法最简洁**: `'string:3-32!'` 一行搞定
-2. **复杂场景性能优异**: 超越 Zod，仅次于 Ajv
-3. **生产级性能**: 100万+ QPS 足以应对绝大多数应用
-4. **多语言支持**: 自动错误消息翻译
-
-对于追求 **代码可读性** 和 **合理性能** 的开发者来说，schema-dsl 是理想选择！
-
----
-
-**测试代码**: [test/performance/library-comparison.test.js](../test/performance/library-comparison.test.js)  
-**运行脚本**: [test/performance/run-benchmark.js](../test/performance/run-benchmark.js)  
-**复现方法**: `node test/performance/run-benchmark.js`