schema-dsl 1.1.3 → 1.1.4

package/README.md

@@ -17,6 +17,29 @@
 
 ---
 
+## ⚡ TL;DR（30秒快速理解）
+
+**schema-dsl 是什么？**  
+最简洁的数据验证库，一行DSL代替10行链式调用，性能超越Zod/Joi/Yup。
+
+**核心优势：**
+- 🎯 **极简语法**: `'string:3-32!'` 代替 8行 Joi 代码（减少 65% 代码量）
+- 🚀 **性能第一**: 2,879,606 ops/s，比 Zod 快 1.58倍，比 Joi 快 9.61倍
+- 🌍 **完整多语言**: 内置5种语言，支持运行时动态切换（v1.1.0+）
+- 🎨 **独家功能**: 从验证规则直接生成 MongoDB/MySQL/PostgreSQL Schema
+
+**3行代码上手：**
+```javascript
+const { dsl, validate } = require('schema-dsl');
+const schema = dsl({ email: 'email!', age: 'number:18-' });
+const result = validate(schema, { email: 'test@example.com', age: 25 });
+console.log(result.valid);  // true
+```
+
+**5分钟教程**: [快速开始](#-快速开始) | **完整文档**: [docs/INDEX.md](./docs/INDEX.md) | **在线体验**: [RunKit](https://runkit.com/npm/schema-dsl)
+
+---
+
 ## 🗺️ 文档导航
 
 **新手入门**:
@@ -45,6 +68,128 @@
 
 ---
 
+## 🆕 最新特性（v1.1.0+）
+
+### 🔗 跨类型联合验证
+
+**一行代码支持多种类型，告别繁琐的类型判断**
+
+```javascript
+const schema = dsl({
+  contact: 'types:email|phone!',      // 邮箱或手机号
+  price: 'types:number:0-|string:1-20',  // 数字价格或"面议"
+  status: 'types:active|inactive|null'   // 枚举或空值
+});
+
+validate(schema, { contact: 'test@example.com' });  // ✅ 通过
+validate(schema, { contact: '13800138000' });       // ✅ 通过
+validate(schema, { contact: 12345 });               // ❌ 失败
+```
+
+**实际场景**:
+- ✅ 用户注册：支持邮箱或手机号登录
+- ✅ 商品价格：数字或"面议"字符串
+- ✅ 可选字段：允许null值
+
+📖 [完整文档](./docs/union-types.md)
+
+---
+
+### 🌍 运行时多语言支持
+
+**无需修改全局设置，每次调用指定语言**
+
+```javascript
+// 根据请求头动态返回不同语言的错误
+app.post('/api/account', (req, res) => {
+  const locale = req.headers['accept-language'] || 'en-US';
+  
+  try {
+    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
+    // 中文请求返回: "账户不存在"
+    // 英文请求返回: "Account not found"
+  } catch (error) {
+    res.status(error.statusCode).json(error.toJSON());
+  }
+});
+```
+
+**适用场景**:
+- ✅ 多语言 API（根据请求头动态返回）
+- ✅ 微服务架构（错误传递保持原语言）
+- ✅ 国际化应用（同一请求多种语言）
+
+📖 [运行时多语言文档](./docs/runtime-locale-support.md)
+
+---
+
+### ⚡ 其他新特性
+
+- ✅ **统一错误抛出**: `I18nError` 类，支持多语言错误消息
+- ✅ **插件系统增强**: 自定义类型注册更简单
+- ✅ **TypeScript 类型完善**: 0个类型错误（v1.1.4）
+
+[查看完整更新日志](./CHANGELOG.md)
+
+---
+
+## 📦 功能清单（AI友好格式）
+
+> 方便AI快速理解所有功能
+
+### 核心功能
+
+```json
+{
+  "validation": {
+    "basic": ["string", "number", "boolean", "date", "email", "url", "phone", "idCard"],
+    "advanced": ["regex", "custom", "conditional", "nested", "array"],
+    "unionTypes": "v1.1.0+ 跨类型联合验证 (types:string|number)"
+  },
+  "i18n": {
+    "supported": ["zh-CN", "en-US", "ja-JP", "es-ES", "fr-FR"],
+    "features": ["配置加载", "运行时切换", "自定义消息", "参数插值"],
+    "runtime": "v1.1.0+ 运行时指定语言 (dsl.error.create(code, params, statusCode, locale))"
+  },
+  "database": {
+    "export": ["MongoDB", "MySQL", "PostgreSQL"],
+    "unique": "从验证规则直接生成数据库Schema"
+  },
+  "framework": {
+    "integration": ["Express", "Koa", "Fastify"],
+    "async": "validateAsync() 失败自动抛出 ValidationError"
+  },
+  "api": {
+    "main": ["dsl()", "validate()", "validateAsync()"],
+    "utils": ["SchemaUtils.pick()", "SchemaUtils.omit()", "SchemaUtils.partial()"],
+    "conditional": ["dsl.if()", "dsl.match()"],
+    "errors": ["ValidationError", "I18nError"]
+  },
+  "performance": {
+    "opsPerSecond": 2879606,
+    "vs": {
+      "Zod": "1.58x faster",
+      "Joi": "9.61x faster",
+      "Yup": "27.07x faster"
+    },
+    "optimization": ["WeakMap缓存", "智能编译", "批量验证优化"]
+  }
+}
+```
+
+### API速查
+
+| API | 用途 | 返回值 | 文档 |
+|-----|------|--------|------|
+| `dsl(schema)` | 创建Schema | Schema对象 | [DSL语法](./docs/dsl-syntax.md) |
+| `validate(schema, data)` | 同步验证 | `{valid, errors, data}` | [验证指南](./docs/validation-guide.md) |
+| `validateAsync(schema, data)` | 异步验证 | Promise（失败抛错） | [异步验证](./docs/validate-async.md) |
+| `dsl.if(condition)` | 条件验证 | ConditionalBuilder | [条件API](./docs/conditional-api.md) |
+| `SchemaUtils.pick()` | 选择字段 | 新Schema | [SchemaUtils](./docs/schema-utils.md) |
+| `I18nError.throw()` | 抛出多语言错误 | never | [I18nError示例](./examples/i18n-error.examples.js) |
+
+---
+
 ## ✨ 为什么选择 schema-dsl？
 
 ### 🎯 极简 DSL 语法
@@ -137,9 +282,48 @@ validate(schema, { username: 'ab' }, { locale: 'ja-JP' });
 // => "usernameは3文字以上である必要があります"
 ```
 
+**🆕 运行时多语言支持（v1.1.0+）**
+
+无需修改全局设置，可在每次调用时指定语言：
+
+```javascript
+const { dsl, I18nError } = require('schema-dsl');
+
+// 方式1: 业务错误 - 运行时指定语言
+const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
+console.log(error1.message);  // "账户不存在"
+
+const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
+console.log(error2.message);  // "Account not found"
+
+// 方式2: 断言风格 - 根据请求头动态指定
+app.post('/api/withdraw', (req, res) => {
+  const locale = req.headers['accept-language'] || 'en-US';
+  const account = getAccount(req.user.id);
+  
+  // 根据请求头返回对应语言的错误
+  I18nError.assert(account, 'account.notFound', {}, 404, locale);
+  I18nError.assert(
+    account.balance >= req.body.amount,
+    'account.insufficientBalance',
+    { balance: account.balance, required: req.body.amount },
+    400,
+    locale
+  );
+  
+  // 验证通过，继续处理...
+});
+```
+
+**适用场景**：
+- ✅ 多语言 API（根据请求头返回不同语言）
+- ✅ 微服务架构（错误在服务间传递时保持语言）
+- ✅ 同一请求中需要多种语言的错误消息
+
 **内置语言**: 中文、英文、日语、法语、西班牙语
 
-📖 [完整多语言文档](./docs/i18n.md)
+📖 [完整多语言文档](./docs/i18n.md)  
+📖 [运行时多语言支持](./docs/runtime-locale-support.md)
 
 ### 🎨 数据库 Schema 导出
 
@@ -1901,6 +2085,40 @@ dsl.error.throw('user.noPermission');
 dsl.error.assert(user.role === 'admin', 'user.noPermission');
 ```
 
+**🆕 运行时指定语言（v1.1.0+）**
+
+无需修改全局语言设置，每次调用时指定：
+
+```javascript
+// 根据请求头动态返回不同语言
+app.post('/api/account', (req, res, next) => {
+  const locale = req.headers['accept-language'] || 'en-US';
+  const account = getAccount(req.user.id);
+  
+  try {
+    // 第5个参数指定语言
+    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
+    dsl.error.assert(
+      account.balance >= 100,
+      'account.insufficientBalance',
+      { balance: account.balance, required: 100 },
+      400,
+      locale
+    );
+    // 验证通过...
+  } catch (error) {
+    next(error);
+  }
+});
+
+// 同一请求中使用不同语言
+const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
+console.log(error1.message);  // "账户不存在"
+
+const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
+console.log(error2.message);  // "Account not found"
+```
+
 **Express/Koa 集成**:
 ```javascript
 // 错误处理中间件
@@ -1930,7 +2148,8 @@ app.post('/withdraw', (req, res) => {
 - 用户: `user.notFound`, `user.noPermission`
 - 订单: `order.notPaid`, `order.paymentMissing`
 
-📖 完整文档请查看 [examples/i18n-error.examples.js](./examples/i18n-error.examples.js)
+📖 完整文档请查看 [examples/i18n-error.examples.js](./examples/i18n-error.examples.js)  
+📖 运行时多语言支持请查看 [docs/runtime-locale-support.md](./docs/runtime-locale-support.md)
 
 ---
 

package/STATUS.md

@@ -1,13 +1,14 @@
 # schema-dsl 项目状态
 
-> **最后更新**: 2026-01-09  
-> **当前版本**: v1.1.3  
+> **最后更新**: 2026-01-13  
+> **当前版本**: v1.1.4  
 > **项目状态**: ✅ 全部完成，测试100%通过（921个测试）  
 
 ---
 
 ## 📋 目录
 
+- [v1.1.4](#v114) - 2026-01-13 ✅ 已完成
 - [v1.1.3](#v113) - 2026-01-09 ✅ 已完成
 - [v1.1.1](#v111) - 2026-01-06 ✅ 已完成
 - [v1.1.0](#v110) - 2026-01-05 ✅ 已完成
@@ -26,6 +27,37 @@
 
 ## 版本发布计划
 
+### v1.1.4
+
+**发布日期**: 2026-01-13  
+**状态**: ✅ 已完成  
+**类型**: 🔧 TypeScript类型修复 + 📚 文档完善  
+**进度**: 100%完成 | 测试: 921个通过
+
+| 需求标题 | 状态 | 优先级 | 详细 |
+|---------|------|--------|------|
+| 修复 dsl.error.assert 重复签名 | ✅ 完成 | P0 | index.d.ts L1336-1343 |
+| 修复 I18nError.assert 重复签名 | ✅ 完成 | P0 | index.d.ts L1805-1821 |
+| 完善运行时多语言文档 | ✅ 完成 | P1 | docs/runtime-locale-support.md |
+| 更新 README.md | ✅ 完成 | P1 | 添加运行时语言支持示例 |
+| 生成深度分析报告 | ✅ 完成 | P2 | reports/schema-dsl/analysis/ |
+| 更新 CHANGELOG | ✅ 完成 | P0 | v1.1.4 变更记录 |
+| 更新 STATUS | ✅ 完成 | P0 | 版本号和状态 |
+
+**实现状态统计**:
+- ✅ 完成: 7个
+- 🔄 进行中: 0个
+- ⏳ 待完成: 0个
+
+**核心变更**:
+- ✅ **修复**: index.d.ts 中2处重复函数签名（46个类型错误→0个错误）
+- ✅ **文档**: 完善运行时多语言支持文档
+- ✅ **文档**: README.md 添加运行时语言指定示例
+- ✅ **验证**: string? 可选语法完整支持
+- ✅ **验证**: 多语言加载机制验证
+
+---
+
 ### v1.1.3
 
 **发布日期**: 2026-01-09  

package/changelogs/v1.0.0.md

@@ -0,0 +1,328 @@
+# v1.0.0 变更日志
+
+> **发布日期**: 2025-12-29  
+> **版本号**: v1.0.0  
+> **类型**: 🎉 正式发布
+
+---
+
+## 📋 变更概览
+
+这是 schema-dsl 的首个正式发布版本，标志着项目达到生产就绪状态。
+
+| 里程碑 | 状态 |
+|--------|------|
+| 核心功能完善 | ✅ |
+| 测试覆盖充分 | ✅ |
+| 文档完整 | ✅ |
+| npm 发布 | ✅ |
+| 生产就绪 | ✅ |
+
+---
+
+## 🎉 核心特性
+
+### 1. 极简 DSL 语法
+
+**一行代码定义验证规则，代码量减少 65%**
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// ✅ 简洁的 DSL 语法
+const schema = dsl({
+  username: 'string:3-32!',
+  email: 'email!',
+  age: 'number:18-120',
+  tags: 'array<string>'
+});
+
+// ❌ 对比 Joi（需要 8 行）
+const Joi = require('joi');
+const joiSchema = Joi.object({
+  username: Joi.string().min(3).max(32).required(),
+  email: Joi.string().email().required(),
+  age: Joi.number().min(18).max(120),
+  tags: Joi.array().items(Joi.string())
+});
+```
+
+---
+
+### 2. 完整的验证功能
+
+#### 基础类型
+
+- ✅ `string` - 字符串验证
+- ✅ `number` - 数字验证
+- ✅ `integer` - 整数验证
+- ✅ `boolean` - 布尔值验证
+- ✅ `date` / `datetime` - 日期时间验证
+- ✅ `email` - 邮箱验证
+- ✅ `url` - URL验证
+- ✅ `phone` - 手机号验证
+- ✅ `idCard` - 身份证验证
+
+#### 高级功能
+
+- ✅ **嵌套对象验证**
+- ✅ **数组验证**
+- ✅ **正则表达式验证**
+- ✅ **自定义验证器**
+- ✅ **条件验证**
+- ✅ **枚举验证**
+
+---
+
+### 3. 高性能设计
+
+**性能测试结果**：
+
+| 验证库 | 性能 (ops/s) | 相对速度 |
+|--------|-------------|---------|
+| **schema-dsl** | **2,879,606** | **基准 (1.00x)** |
+| Zod | 1,818,592 | 0.63x (慢 58%) |
+| Joi | 299,761 | 0.10x (慢 861%) |
+| Yup | 106,378 | 0.04x (慢 2607%) |
+
+**优化技术**：
+- ✅ WeakMap 缓存机制
+- ✅ 智能编译优化
+- ✅ 批量验证优化
+- ✅ 惰性求值
+
+---
+
+### 4. TypeScript 完整支持
+
+```typescript
+import { dsl, validate, ValidationError } from 'schema-dsl';
+
+// 完整的类型推导
+const schema = dsl({
+  username: 'string:3-32!',
+  email: 'email!'
+});
+
+// 类型安全的验证
+const result = validate(schema, data);
+
+if (result.valid) {
+  console.log(result.data);  // 类型推导
+} else {
+  console.log(result.errors); // ValidationError[]
+}
+```
+
+---
+
+### 5. 数据库 Schema 导出
+
+**独家功能：从验证规则直接生成数据库结构**
+
+```javascript
+const { dsl, exporters } = require('schema-dsl');
+
+const schema = dsl({
+  username: 'string:3-32!',
+  email: 'email!',
+  age: 'number:18-120'
+});
+
+// MongoDB Schema
+const mongoExporter = new exporters.MongoDBExporter();
+const mongoSchema = mongoExporter.export(schema);
+
+// MySQL DDL
+const mysqlExporter = new exporters.MySQLExporter();
+const mysqlDDL = mysqlExporter.export('users', schema);
+
+// PostgreSQL DDL
+const pgExporter = new exporters.PostgreSQLExporter();
+const pgDDL = pgExporter.export('users', schema);
+```
+
+---
+
+### 6. 框架集成
+
+**Express**
+```javascript
+const { validateAsync, ValidationError } = require('schema-dsl');
+
+app.post('/api/users', async (req, res, next) => {
+  try {
+    const validData = await validateAsync(userSchema, req.body);
+    // 验证通过...
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+**Koa**
+```javascript
+app.use(async (ctx, next) => {
+  try {
+    ctx.validData = await validateAsync(schema, ctx.request.body);
+    await next();
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      ctx.status = 400;
+      ctx.body = { errors: error.errors };
+    }
+  }
+});
+```
+
+---
+
+### 7. 条件验证
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// 快速断言
+dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .assert(userData);
+
+// 复杂条件
+dsl.if(d => d.role === 'admin')
+  .and(d => d.permissions.includes('delete'))
+  .message('权限不足')
+  .assert(user);
+```
+
+---
+
+### 8. Schema 复用工具
+
+```javascript
+const { SchemaUtils } = require('schema-dsl');
+
+// 选择字段
+const createSchema = SchemaUtils.pick(fullSchema, ['username', 'email']);
+
+// 排除字段
+const publicSchema = SchemaUtils.omit(fullSchema, ['password']);
+
+// 变为可选
+const updateSchema = SchemaUtils.partial(createSchema);
+
+// 扩展字段
+const registerSchema = createSchema.extend({
+  captcha: 'string:4-6!',
+  agree: 'boolean!'
+});
+```
+
+---
+
+## 📚 完整文档
+
+### 用户指南
+
+- ✅ [快速开始](../README.md#快速开始)
+- ✅ [DSL 语法](../docs/dsl-syntax.md)
+- ✅ [验证指南](../docs/validation-guide.md)
+- ✅ [类型参考](../docs/type-reference.md)
+
+### API 文档
+
+- ✅ [dsl() API](../docs/api-reference.md)
+- ✅ [validate() API](../docs/validate.md)
+- ✅ [validateAsync() API](../docs/validate-async.md)
+- ✅ [SchemaUtils API](../docs/schema-utils.md)
+
+### 高级功能
+
+- ✅ [条件验证](../docs/conditional-api.md)
+- ✅ [自定义扩展](../docs/custom-extensions-guide.md)
+- ✅ [数据库导出](../docs/mongodb-exporter.md)
+- ✅ [性能优化](../docs/cache-manager.md)
+
+### 框架集成
+
+- ✅ [Express 集成](../examples/express-integration.js)
+- ✅ [Koa 集成](../examples/middleware-usage.js)
+- ✅ [Fastify 集成](../examples/middleware-usage.js)
+
+---
+
+## 📊 测试覆盖
+
+- ✅ **测试套件**: 800+ 个测试用例
+- ✅ **测试覆盖率**: 95%+
+- ✅ **兼容性测试**: Node.js 14/16/18/20
+
+---
+
+## 🎯 生产就绪
+
+### 质量保证
+
+- ✅ 所有测试通过
+- ✅ 无已知严重 Bug
+- ✅ 文档完整
+- ✅ API 稳定
+
+### 性能验证
+
+- ✅ 基准测试完成
+- ✅ 性能优于主流验证库
+- ✅ 内存占用合理
+
+### 安全性
+
+- ✅ 无已知安全漏洞
+- ✅ 输入验证严格
+- ✅ 错误处理完善
+
+---
+
+## 📦 npm 发布
+
+```bash
+npm install schema-dsl
+```
+
+**包信息**：
+- 包名: `schema-dsl`
+- 版本: `1.0.0`
+- 大小: ~50KB (未压缩)
+- 许可证: MIT
+
+---
+
+## 🎉 里程碑
+
+v1.0.0 标志着 schema-dsl 的以下成就：
+
+1. ✅ **功能完整**: 覆盖所有常见验证场景
+2. ✅ **性能优秀**: 超越主流验证库
+3. ✅ **文档完善**: 40+ 篇详细文档
+4. ✅ **测试充分**: 800+ 测试用例
+5. ✅ **生产就绪**: 可用于生产环境
+
+---
+
+## 🙏 致谢
+
+感谢所有测试用户和贡献者的反馈，让 schema-dsl 达到了生产就绪的质量标准。
+
+---
+
+## 🔗 相关链接
+
+- [GitHub Repository](https://github.com/vextjs/schema-dsl)
+- [npm Package](https://www.npmjs.com/package/schema-dsl)
+- [完整文档](../docs/INDEX.md)
+- [在线体验](https://runkit.com/npm/schema-dsl)
+
+---
+
+**发布者**: schema-dsl Team  
+**发布时间**: 2025-12-29  
+**下一版本**: v1.0.1
+