schema-dsl 1.0.7 → 1.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +195 -12
- package/README.md +39 -17
- package/STATUS.md +74 -3
- package/docs/add-custom-locale.md +395 -0
- package/docs/dynamic-locale.md +74 -28
- package/docs/frontend-i18n-guide.md +18 -15
- package/docs/i18n-user-guide.md +7 -9
- package/docs/i18n.md +65 -2
- package/index.d.ts +63 -5
- package/index.js +12 -3
- package/lib/core/ErrorFormatter.js +102 -33
- package/lib/core/Validator.js +6 -14
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -9,18 +9,201 @@
|
|
|
9
9
|
|
|
10
10
|
## 版本概览
|
|
11
11
|
|
|
12
|
-
| 版本
|
|
13
|
-
|
|
14
|
-
| [v1.0.
|
|
15
|
-
| [v1.0.
|
|
16
|
-
| [v1.0.7](#v107)
|
|
17
|
-
| [v1.0.6](#v106)
|
|
18
|
-
| [v1.0.
|
|
19
|
-
| [v1.0.
|
|
20
|
-
| [v1.0.
|
|
21
|
-
| [v1.0.
|
|
22
|
-
| [v1.0.
|
|
23
|
-
| [v1.0.
|
|
12
|
+
| 版本 | 日期 | 变更摘要 | 详细 |
|
|
13
|
+
|------------------|------|---------|------|
|
|
14
|
+
| [v1.0.9](#v109) | 2026-01-04 | 🎉 重大改进：多语言支持完善 + TypeScript 类型完整 | [查看详情](#v109) |
|
|
15
|
+
| [v1.0.8](#v108) | 2026-01-04 | 优化：错误消息过滤增强 | [查看详情](#v108) |
|
|
16
|
+
| [v1.0.7](#v107) | 2026-01-04 | 修复：dsl.match/dsl.if 嵌套支持 dsl() 包裹 | [查看详情](#v107) |
|
|
17
|
+
| [v1.0.6](#v106) | 2026-01-04 | 🚨 紧急修复：TypeScript 类型污染 | [查看详情](#v106) |
|
|
18
|
+
| [v1.0.7](#v107) | 2026-01-04 | 修复：dsl.match/dsl.if 嵌套支持 dsl() 包裹 | [查看详情](#v107) |
|
|
19
|
+
| [v1.0.6](#v106) | 2026-01-04 | 🚨 紧急修复：TypeScript 类型污染 | [查看详情](#v106) |
|
|
20
|
+
| [v1.0.5](#v105) | 2026-01-04 | 测试覆盖率提升至 97% | [查看详情](#v105) |
|
|
21
|
+
| [v1.0.4](#v104) | 2025-12-31 | TypeScript 完整支持、validateAsync、ValidationError | [查看详情](#v104) |
|
|
22
|
+
| [v1.0.3](#v103) | 2025-12-31 | ⚠️ 破坏性变更：单值语法修复 | [查看详情](#v103) |
|
|
23
|
+
| [v1.0.2](#v102) | 2025-12-31 | 15个新增验证器、完整文档、75个测试 | [查看详情](#v102) |
|
|
24
|
+
| [v1.0.1](#v101) | 2025-12-31 | 枚举功能、自动类型识别、统一错误消息 | [查看详情](#v101) |
|
|
25
|
+
| [v1.0.0](#v100) | 2025-12-29 | 初始发布版本 | [查看详情](#v100) |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## [v1.0.9] - 2026-01-04
|
|
30
|
+
|
|
31
|
+
### 🎉 重大改进
|
|
32
|
+
|
|
33
|
+
#### 1. 多语言文档完善 ⭐⭐⭐
|
|
34
|
+
|
|
35
|
+
**优化内容**：
|
|
36
|
+
|
|
37
|
+
1. ✅ **统一文档描述为"首次加载，运行时切换"**
|
|
38
|
+
- 修复 `i18n-user-guide.md` 配置示例错误
|
|
39
|
+
- 更新 `add-custom-locale.md`、`dynamic-locale.md`、`frontend-i18n-guide.md`
|
|
40
|
+
- 添加完整的配置和使用示例
|
|
41
|
+
- 添加错误示例对比（运行时单个加载 vs 首次加载）
|
|
42
|
+
|
|
43
|
+
2. ✅ **添加文档导航**
|
|
44
|
+
- 在 `i18n.md` 添加多语言文档导航
|
|
45
|
+
- 帮助用户快速找到所需文档
|
|
46
|
+
|
|
47
|
+
3. ✅ **性能数据更新**
|
|
48
|
+
- 更新性能对比数据：**2,879,606 ops/s**（提升3.19倍）
|
|
49
|
+
- 比 Zod 快 1.58倍
|
|
50
|
+
- 比 Joi 快 9.61倍
|
|
51
|
+
- 比 Yup 快 27.07倍
|
|
52
|
+
|
|
53
|
+
#### 2. 多语言支持完善（v1.0.9 早期）⭐⭐⭐
|
|
54
|
+
|
|
55
|
+
**问题描述**：
|
|
56
|
+
- TypeScript 类型定义缺少 `options` 参数
|
|
57
|
+
- 多语言切换需要修改全局状态，并发场景不安全
|
|
58
|
+
- 自定义错误消息查找逻辑有问题
|
|
59
|
+
|
|
60
|
+
**修复内容**：
|
|
61
|
+
|
|
62
|
+
1. ✅ **TypeScript 类型定义完善**
|
|
63
|
+
```typescript
|
|
64
|
+
// 新增 ValidateOptions 接口
|
|
65
|
+
interface ValidateOptions {
|
|
66
|
+
format?: boolean; // 是否格式化错误
|
|
67
|
+
locale?: string; // 动态指定语言（如 'zh-CN', 'en-US'）
|
|
68
|
+
messages?: ErrorMessages; // 自定义错误消息
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// 更新函数签名
|
|
72
|
+
function validate(
|
|
73
|
+
schema: JSONSchema | DslBuilder,
|
|
74
|
+
data: any,
|
|
75
|
+
options?: ValidateOptions // ← 新增
|
|
76
|
+
): ValidationResult;
|
|
77
|
+
|
|
78
|
+
// 更新 Validator.validate 方法签名
|
|
79
|
+
validate(
|
|
80
|
+
schema: JSONSchema | DslBuilder | Function,
|
|
81
|
+
data: any,
|
|
82
|
+
options?: ValidateOptions // ← 新增
|
|
83
|
+
): ValidationResult;
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
2. ✅ **参数化语言切换（无需全局状态）**
|
|
87
|
+
```javascript
|
|
88
|
+
// 旧方式（需要修改全局状态）
|
|
89
|
+
Locale.setLocale('zh-CN');
|
|
90
|
+
const result = validate(schema, data);
|
|
91
|
+
|
|
92
|
+
// 新方式（参数化，支持并发）
|
|
93
|
+
const result = validate(schema, data, { locale: 'zh-CN' });
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
3. ✅ **修复自定义错误消息查找逻辑**
|
|
97
|
+
- **Bug 1**: 优先使用通用模板而非 schema 自定义消息
|
|
98
|
+
- **Bug 2**: 无法正确处理三种自定义消息格式：
|
|
99
|
+
- 键引用：`_customMessages.pattern = "pattern.objectId"`
|
|
100
|
+
- 模板字符串：`_customMessages.min = "{{#label}}必须大于{{#limit}}"`
|
|
101
|
+
- 最终消息：`_customMessages.pattern = "手机号格式不正确"`
|
|
102
|
+
|
|
103
|
+
**修复效果**：
|
|
104
|
+
|
|
105
|
+
```javascript
|
|
106
|
+
// 1. 并发调用不同语言
|
|
107
|
+
const [resultZh, resultEn] = await Promise.all([
|
|
108
|
+
validate(schema, data, { locale: 'zh-CN' }),
|
|
109
|
+
validate(schema, data, { locale: 'en-US' })
|
|
110
|
+
]);
|
|
111
|
+
// ✅ 两次调用互不影响
|
|
112
|
+
|
|
113
|
+
// 2. 自定义消息（键引用）
|
|
114
|
+
const schema = dsl('objectId!');
|
|
115
|
+
const result = validate(schema, 'invalid', { locale: 'zh-CN' });
|
|
116
|
+
// message: "无效的 ObjectId" ✅
|
|
117
|
+
|
|
118
|
+
// 3. 自定义消息（模板字符串）
|
|
119
|
+
const schema = dsl({
|
|
120
|
+
age: 'number:18-!'.label('年龄')
|
|
121
|
+
.messages({ 'min': '{{#label}}必须大于{{#limit}}' })
|
|
122
|
+
});
|
|
123
|
+
const result = validate(schema, { age: 10 });
|
|
124
|
+
// message: "年龄必须大于18" ✅
|
|
125
|
+
|
|
126
|
+
// 4. 自定义消息（最终消息）
|
|
127
|
+
const schema = dsl({
|
|
128
|
+
phone: 'string!'.pattern(/^1[3-9]\d{9}$/)
|
|
129
|
+
.messages({ 'pattern': '手机号格式不正确' })
|
|
130
|
+
});
|
|
131
|
+
const result = validate(schema, { phone: 'invalid' });
|
|
132
|
+
// message: "手机号格式不正确" ✅
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
**技术细节**：
|
|
136
|
+
- 修改 `index.js` 中的 `validate()` 函数，传递 `options` 参数
|
|
137
|
+
- 修改 `Validator.js` 中的 `validate()` 方法，直接传递 `locale` 到 ErrorFormatter
|
|
138
|
+
- 修改 `ErrorFormatter.js`：
|
|
139
|
+
- `format()` 方法支持对象参数 `{ locale, messages }`
|
|
140
|
+
- `formatDetailed()` 方法新增 `customMessages` 参数
|
|
141
|
+
- 优化自定义消息查找逻辑：优先检查 schema 中的 `_customMessages`
|
|
142
|
+
|
|
143
|
+
**测试结果**：
|
|
144
|
+
- ✅ 725 个测试全部通过（从 51 个失败修复到 0 个失败）
|
|
145
|
+
- ✅ 完全向后兼容，不破坏现有 API
|
|
146
|
+
|
|
147
|
+
### Changed (变更)
|
|
148
|
+
|
|
149
|
+
- 📝 **API**: `validate()` 和 `Validator.validate()` 新增 `options` 参数（向后兼容）
|
|
150
|
+
- 🔧 **内部**: `ErrorFormatter.formatDetailed()` 新增 `customMessages` 参数
|
|
151
|
+
|
|
152
|
+
### Fixed (修复)
|
|
153
|
+
|
|
154
|
+
- 🐛 修复 TypeScript 类型定义缺少 `options` 参数
|
|
155
|
+
- 🐛 修复自定义错误消息查找逻辑（优先级问题）
|
|
156
|
+
- 🐛 修复自定义消息无法区分键引用/模板字符串/最终消息
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## [v1.0.8] - 2026-01-04
|
|
161
|
+
|
|
162
|
+
### Improved (优化)
|
|
163
|
+
|
|
164
|
+
#### 错误消息过滤增强 ⭐
|
|
165
|
+
|
|
166
|
+
**问题描述**：
|
|
167
|
+
用户报告错误消息存在冗余问题：
|
|
168
|
+
- 在嵌套 If/Match 结构中，会显示重复的 "must match then schema" 包装错误
|
|
169
|
+
- 当已有具体字段错误时（如"Credit price is required"），还会额外显示2-3个通用包装错误
|
|
170
|
+
|
|
171
|
+
**修复内容**：
|
|
172
|
+
- ✅ 过滤 `if` 关键字的包装错误
|
|
173
|
+
- ✅ 过滤 `anyOf` 关键字的包装错误
|
|
174
|
+
- ✅ 过滤 `oneOf` 关键字的包装错误
|
|
175
|
+
- ✅ 当存在具体字段错误时，自动移除所有包装错误
|
|
176
|
+
|
|
177
|
+
**修复效果**：
|
|
178
|
+
|
|
179
|
+
修复前：
|
|
180
|
+
```javascript
|
|
181
|
+
const result = validate(schema, data);
|
|
182
|
+
// errors: [
|
|
183
|
+
// { message: "Credit price is required" },
|
|
184
|
+
// { message: "must match then schema" }, // 冗余
|
|
185
|
+
// { message: "must match then schema" } // 冗余
|
|
186
|
+
// ]
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
修复后：
|
|
190
|
+
```javascript
|
|
191
|
+
const result = validate(schema, data);
|
|
192
|
+
// errors: [
|
|
193
|
+
// { message: "Credit price is required" } // 只显示具体错误
|
|
194
|
+
// ]
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
**技术细节**：
|
|
198
|
+
- 修改文件：[lib/core/ErrorFormatter.js](lib/core/ErrorFormatter.js#L84-L101)
|
|
199
|
+
- 过滤逻辑：检测到具体错误（type, required, pattern等）时，自动过滤包装错误（if, anyOf, oneOf）
|
|
200
|
+
- 适用场景：所有使用 `dsl.if()`、`dsl.match()` 以及 JSON Schema 的 anyOf/oneOf 的验证
|
|
201
|
+
|
|
202
|
+
**测试覆盖**：
|
|
203
|
+
- 测试文件：[test/unit/error-message-filter.test.js](test/unit/error-message-filter.test.js)
|
|
204
|
+
- 新增测试：5个错误过滤场景
|
|
205
|
+
- 测试总数：725 (+5)
|
|
206
|
+
- 所有测试通过 ✅
|
|
24
207
|
|
|
25
208
|
---
|
|
26
209
|
|
package/README.md
CHANGED
|
@@ -59,37 +59,59 @@ const schema = dsl({
|
|
|
59
59
|
</tr>
|
|
60
60
|
</table>
|
|
61
61
|
|
|
62
|
-
### 🚀
|
|
62
|
+
### 🚀 性能卓越
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
**测试结果：schema-dsl 是目前性能最优的验证库（基于最新基准测试）**
|
|
65
65
|
|
|
66
|
-
| 验证库 |
|
|
67
|
-
|
|
68
|
-
| **schema-dsl** | **
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
| Ajv | 2146万/s | 902万/s | 最快（但复杂） |
|
|
66
|
+
| 验证库 | 性能 (ops/s) | 相对速度 | 评价 |
|
|
67
|
+
|--------|-------------|---------|------|
|
|
68
|
+
| **schema-dsl** | **2,879,606** | **基准 (1.00x)** | **🥇 第一名** |
|
|
69
|
+
| Zod | 1,818,592 | 0.63x | 🥈 慢 58% |
|
|
70
|
+
| Joi | 299,761 | 0.10x | 🥉 慢 861% |
|
|
71
|
+
| Yup | 106,378 | 0.04x | 慢 2607% |
|
|
73
72
|
|
|
74
|
-
|
|
73
|
+
**性能优势**:
|
|
74
|
+
- ✅ 比 Zod 快 **1.58倍**
|
|
75
|
+
- ✅ 比 Joi 快 **9.61倍**
|
|
76
|
+
- ✅ 比 Yup 快 **27.07倍**
|
|
75
77
|
|
|
76
|
-
> 📊
|
|
78
|
+
> 📊 **测试环境**: Node.js v20.x, Windows
|
|
79
|
+
> 📊 **测试场景**: 用户注册表单验证（username, email, age, tags）
|
|
80
|
+
> 📊 **测试工具**: [Benchmark.js](https://benchmarkjs.com/)
|
|
81
|
+
> 📊 **运行测试**: `node test/benchmarks/library-comparison.js`
|
|
77
82
|
|
|
78
83
|
### 🌍 完整多语言支持
|
|
79
84
|
|
|
80
|
-
|
|
85
|
+
**一行配置，自动加载所有语言包**
|
|
81
86
|
|
|
82
87
|
```javascript
|
|
88
|
+
const { dsl, validate } = require('schema-dsl');
|
|
89
|
+
const path = require('path');
|
|
90
|
+
|
|
91
|
+
// ========== 应用启动时配置（只执行一次）==========
|
|
92
|
+
dsl.config({
|
|
93
|
+
i18n: path.join(__dirname, 'locales') // 自动加载目录下所有语言文件
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
// ========== 运行时直接切换语言（无需重新加载）==========
|
|
97
|
+
const schema = dsl({ username: 'string:3-32!' });
|
|
98
|
+
|
|
83
99
|
// 中文错误消息
|
|
84
|
-
validate(schema,
|
|
85
|
-
// => "
|
|
100
|
+
validate(schema, { username: 'ab' }, { locale: 'zh-CN' });
|
|
101
|
+
// => "username长度不能少于3个字符"
|
|
86
102
|
|
|
87
103
|
// 英文错误消息
|
|
88
|
-
validate(schema,
|
|
89
|
-
// => "
|
|
104
|
+
validate(schema, { username: 'ab' }, { locale: 'en-US' });
|
|
105
|
+
// => "username length must be at least 3"
|
|
106
|
+
|
|
107
|
+
// 日语错误消息
|
|
108
|
+
validate(schema, { username: 'ab' }, { locale: 'ja-JP' });
|
|
109
|
+
// => "usernameは3文字以上である必要があります"
|
|
90
110
|
```
|
|
91
111
|
|
|
92
|
-
|
|
112
|
+
**内置语言**: 中文、英文、日语、法语、西班牙语
|
|
113
|
+
|
|
114
|
+
📖 [完整多语言文档](./docs/i18n.md)
|
|
93
115
|
|
|
94
116
|
### 🎨 数据库 Schema 导出
|
|
95
117
|
|
package/STATUS.md
CHANGED
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
# schema-dsl 项目状态
|
|
2
2
|
|
|
3
|
-
> **最后更新**:
|
|
4
|
-
> **当前版本**: v1.0.
|
|
5
|
-
> **项目状态**: ✅ 全部完成，测试100
|
|
3
|
+
> **最后更新**: 2026-01-04
|
|
4
|
+
> **当前版本**: v1.0.9
|
|
5
|
+
> **项目状态**: ✅ 全部完成，测试100%通过（725个测试）
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## 📋 目录
|
|
10
10
|
|
|
11
|
+
- [v1.0.9](#v109) - 2026-01-04 ✅ 已完成
|
|
12
|
+
- [v1.0.8](#v108) - 2026-01-04 ✅ 已完成
|
|
13
|
+
- [v1.0.7](#v107) - 2026-01-04 ✅ 已完成
|
|
14
|
+
- [v1.0.6](#v106) - 2026-01-04 ✅ 已完成
|
|
15
|
+
- [v1.0.5](#v105) - 2026-01-04 ✅ 已完成
|
|
11
16
|
- [v1.0.4](#v104) - 2025-12-31 ✅ 已完成
|
|
12
17
|
- [v1.0.3](#v103) - 2025-12-31 ⚠️ 破坏性变更
|
|
13
18
|
- [v1.0.2](#v102) - 2025-12-31 ✅ 已完成
|
|
@@ -18,6 +23,72 @@
|
|
|
18
23
|
|
|
19
24
|
## 版本发布计划
|
|
20
25
|
|
|
26
|
+
### v1.0.9
|
|
27
|
+
|
|
28
|
+
**发布日期**: 2026-01-04
|
|
29
|
+
**状态**: ✅ 已完成
|
|
30
|
+
**类型**: 📝 文档完善 + 性能验证
|
|
31
|
+
**进度**: 100%完成 | 优化: 多语言文档 | 性能: 2,879,606 ops/s
|
|
32
|
+
|
|
33
|
+
| 需求标题 | 状态 | 优先级 | 详细 |
|
|
34
|
+
|---------|------|--------|------|
|
|
35
|
+
| 多语言文档统一 | ✅ 完成 | P0 | "首次加载，运行时切换" |
|
|
36
|
+
| 添加文档导航 | ✅ 完成 | P1 | i18n.md 导航指引 |
|
|
37
|
+
| 性能数据更新 | ✅ 完成 | P0 | 更新到 2,879,606 ops/s |
|
|
38
|
+
| README 更新 | ✅ 完成 | P0 | 性能+多语言章节 |
|
|
39
|
+
| CHANGELOG 更新 | ✅ 完成 | P0 | 添加 v1.0.9 记录 |
|
|
40
|
+
| 配置示例修复 | ✅ 完成 | P0 | i18n-user-guide.md |
|
|
41
|
+
|
|
42
|
+
**实现状态统计**:
|
|
43
|
+
- ✅ 完成: 6个
|
|
44
|
+
- 🔄 进行中: 0个
|
|
45
|
+
- ⏳ 待完成: 0个
|
|
46
|
+
|
|
47
|
+
**核心变更**:
|
|
48
|
+
- ✅ **优化**: 统一多语言文档描述（5个文档）
|
|
49
|
+
- ✅ **新增**: 文档导航（i18n.md）
|
|
50
|
+
- ✅ **更新**: 性能对比数据（提升3.19倍）
|
|
51
|
+
- ✅ **修复**: i18n-user-guide.md 配置错误
|
|
52
|
+
- ✅ **更新**: README.md 和 CHANGELOG.md
|
|
53
|
+
|
|
54
|
+
**用户价值**:
|
|
55
|
+
- 🎯 文档更清晰，用户快速找到所需信息
|
|
56
|
+
- 🎯 性能数据更新，证明库的卓越性能
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
### v1.0.8
|
|
61
|
+
|
|
62
|
+
**发布日期**: 2026-01-04
|
|
63
|
+
**状态**: ✅ 已完成
|
|
64
|
+
**类型**: 🔧 错误消息过滤增强
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
### v1.0.7
|
|
69
|
+
|
|
70
|
+
**发布日期**: 2026-01-04
|
|
71
|
+
**状态**: ✅ 已完成
|
|
72
|
+
**类型**: 🐛 嵌套支持修复
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
### v1.0.6
|
|
77
|
+
|
|
78
|
+
**发布日期**: 2026-01-04
|
|
79
|
+
**状态**: ✅ 已完成
|
|
80
|
+
**类型**: 🚨 TypeScript 类型污染修复
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
### v1.0.5
|
|
85
|
+
|
|
86
|
+
**发布日期**: 2026-01-04
|
|
87
|
+
**状态**: ✅ 已完成
|
|
88
|
+
**类型**: ✅ 测试覆盖率提升
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
21
92
|
### v1.0.4
|
|
22
93
|
|
|
23
94
|
**发布日期**: 2025-12-31
|