schema-dsl 1.1.3 → 1.1.5

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,188 @@
 
 ---
 
+## 🆕 最新特性（v1.1.5）
+
+### 🎯 错误配置对象格式支持（v1.1.5）
+
+**统一错误代码，多语言共享，前端友好**
+
+```javascript
+// 语言包配置（支持对象格式）
+const locales = {
+  'zh-CN': {
+    'account.notFound': {
+      code: 40001,              // 统一的数字错误代码
+      message: '账户不存在'
+    },
+    'account.insufficientBalance': {
+      code: 40002,
+      message: '余额不足，当前{{#balance}}，需要{{#required}}'
+    }
+  },
+  'en-US': {
+    'account.notFound': {
+      code: 40001,              // 相同的数字 code
+      message: 'Account not found'
+    },
+    'account.insufficientBalance': {
+      code: 40002,
+      message: 'Insufficient balance: {{#balance}}, required: {{#required}}'
+    }
+  }
+};
+
+// 使用
+try {
+  dsl.error.throw('account.notFound');
+} catch (error) {
+  console.log(error.code);         // 40001 (统一数字代码)
+  console.log(error.originalKey);  // 'account.notFound' (原始key)
+  console.log(error.message);      // 中文: "账户不存在" / 英文: "Account not found"
+  
+  // 增强的 error.is() - 两种方式都支持
+  if (error.is('account.notFound')) { }  // ✅ 使用 originalKey
+  if (error.is(40001)) { }               // ✅ 使用数字 code
+}
+
+// 前端统一处理
+switch (error.code) {
+  case 40001: showNotFoundPage(); break;     // 不受语言影响
+  case 40002: showTopUpDialog(); break;
+}
+```
+
+**核心优势**:
+- 🎯 **统一错误代码**: 不同语言使用相同的数字 `code`，便于前端统一处理
+- 🔄 **完全向后兼容**: 字符串格式自动转换，现有代码无需修改
+- 📊 **更好的错误追踪**: `originalKey` 和 `code` 分离，便于日志分析
+- 🌍 **多语言友好**: 前端可以用统一的数字 code 处理，不受语言影响
+
+📖 [完整文档](./docs/error-handling.md#v115-新功能对象格式错误配置) · [变更日志](./changelogs/v1.1.5.md)
+
+---
+
+### 🔗 跨类型联合验证（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)
+
+---
+
+### ⚡ 其他新特性
+
+- ✅ **错误配置对象格式**: 支持 `{ code, message }` 统一错误代码（v1.1.5）
+- ✅ **统一错误抛出**: `I18nError` 类，支持多语言错误消息（v1.1.1）
+- ✅ **插件系统增强**: 自定义类型注册更简单（v1.1.0）
+- ✅ **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 +342,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 +2145,125 @@ dsl.error.throw('user.noPermission');
 dsl.error.assert(user.role === 'admin', 'user.noPermission');
 ```
 
+**🆕 对象格式错误配置（v1.1.5）**
+
+支持统一的数字错误代码，便于前端处理：
+
+```javascript
+// 语言包配置（lib/locales/zh-CN.js）
+module.exports = {
+  // 字符串格式（向后兼容）
+  'user.notFound': '用户不存在',
+  
+  // 对象格式（v1.1.5 新增）- 使用数字错误码
+  'account.notFound': {
+    code: 40001,              // 数字错误代码
+    message: '账户不存在'
+  },
+  'account.insufficientBalance': {
+    code: 40002,
+    message: '余额不足，当前{{#balance}}，需要{{#required}}'
+  },
+  'order.notPaid': {
+    code: 50001,
+    message: '订单未支付'
+  }
+};
+
+// lib/locales/en-US.js
+module.exports = {
+  'account.notFound': {
+    code: 40001,              // 相同的数字 code
+    message: 'Account not found'
+  },
+  'account.insufficientBalance': {
+    code: 40002,
+    message: 'Insufficient balance: {{#balance}}, required: {{#required}}'
+  },
+  'order.notPaid': {
+    code: 50001,
+    message: 'Order not paid'
+  }
+};
+
+// 使用
+try {
+  dsl.error.throw('account.notFound');
+} catch (error) {
+  error.code          // 40001 (数字代码)
+  error.originalKey   // 'account.notFound' (原始key)
+  error.message       // '账户不存在'
+  
+  // 两种判断方式
+  error.is('account.notFound')  // ✅ 使用 originalKey
+  error.is(40001)               // ✅ 使用数字 code
+}
+
+// 前端统一处理（不受语言影响）
+try {
+  await api.getAccount(id);
+} catch (error) {
+  switch (error.code) {
+    case 40001:
+      router.push('/account-not-found');
+      break;
+    case 40002:
+      showTopUpDialog(error.params.balance, error.params.required);
+      break;
+    case 50001:
+      showPaymentDialog();
+      break;
+  }
+}
+```
+
+**优势**：
+- ✅ 多语言共享相同的数字 `code`，前端统一处理
+- ✅ 完全向后兼容，字符串格式自动转换
+- ✅ `originalKey` 便于调试和日志追踪
+- ✅ 数字 code 更简洁，易于管理和文档化
+
+**错误码规范建议**：
+- `4xxxx` - 客户端错误（账户、权限、参数等）
+- `5xxxx` - 业务逻辑错误（订单、支付、库存等）
+- `6xxxx` - 系统错误（数据库、服务不可用等）
+
+📖 详细说明: [错误处理文档](./docs/error-handling.md#v115-新功能对象格式错误配置)
+
+**🆕 运行时指定语言（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 +2293,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,15 @@
 # schema-dsl 项目状态
 
-> **最后更新**: 2026-01-09  
-> **当前版本**: v1.1.3  
-> **项目状态**: ✅ 全部完成，测试100%通过（921个测试）  
+> **最后更新**: 2026-01-17  
+> **当前版本**: v1.1.5  
+> **项目状态**: ✅ 全部完成，测试100%通过（955个测试）  
 
 ---
 
 ## 📋 目录
 
+- [v1.1.5](#v115) - 2026-01-17 ✅ 已完成
+- [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 +28,70 @@
 
 ## 版本发布计划
 
+### v1.1.5
+
+**发布日期**: 2026-01-17  
+**状态**: ✅ 已完成  
+**类型**: 🚀 功能增强 - 错误配置对象格式支持  
+**进度**: 100%完成 | 测试: 955个通过 (100%)
+
+| 需求标题 | 状态 | 优先级 | 详细 |
+|---------|------|--------|------|
+| 实现 Locale.getMessage 对象格式支持 | ✅ 完成 | P0 | lib/core/Locale.js |
+| 修改 I18nError 构造函数支持对象格式 | ✅ 完成 | P0 | lib/errors/I18nError.js |
+| 新增 originalKey 字段 | ✅ 完成 | P0 | I18nError 类 |
+| 更新 TypeScript 类型定义 | ✅ 完成 | P0 | index.d.ts |
+| 更新语言包示例（对象格式） | ✅ 完成 | P1 | lib/locales/*.js |
+| 新增测试用例（6个） | ✅ 完成 | P0 | test/unit/i18n-error.test.js |
+| 更新现有测试适配对象格式 | ✅ 完成 | P0 | test/unit/*.test.js |
+| 更新 CHANGELOG | ✅ 完成 | P0 | v1.1.5 变更记录 |
+| 更新 STATUS | ✅ 完成 | P0 | 版本号和状态 |
+
+**实现状态统计**:
+- ✅ 完成: 9个
+- 🔄 进行中: 0个
+- ⏳ 待完成: 0个
+
+**核心变更**:
+- ✨ 语言包支持对象格式 `{ code, message }`
+- ✨ I18nError 新增 `originalKey` 字段
+- ✨ 多语言共享相同的 `code`
+- ✅ 完全向后兼容，字符串格式自动转换
+- ✅ `error.is()` 同时支持 code 和 originalKey 判断
+
+**向后兼容性**: ✅ 100% 向后兼容
+
+### 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