schema-dsl 1.2.4 → 2.0.0

package/docs/faq.md

@@ -1,6 +1,6 @@
 # 常见问题解答 (FAQ)
 
-> **更新时间**: 2025-12-25  
+> **更新时间**: 2026-05-08  
 
 
 ---
@@ -20,12 +20,12 @@
 
 ## 基础问题
 
-### Q: SchemaI-DSL 和 Joi、Yup 有什么区别？
+### Q: schema-dsl 和 Joi、Yup 有什么区别？
 
-**A**: SchemaI-DSL 采用 DSL 语法，更简洁：
+**A**: schema-dsl 采用 DSL 语法，更简洁：
 
 ```javascript
-// SchemaI-DSL - 简洁
+// schema-dsl - 简洁
 const schema = dsl({
   username: 'string:3-32!',
   email: 'email!'
@@ -46,13 +46,15 @@ const schema = Joi.object({
 
 ---
 
-### Q: 如何安装 SchemaI-DSL？
+### Q: 如何安装 schema-dsl？
 
 ```bash
 npm install schema-dsl
 ```
 
-**Node.js 版本要求**：>= 12.0.0
+**Node.js 版本要求**：`>=18.0.0`
+
+当前 TypeScript 重构版以 `Node.js >=18.0.0` 为唯一运行时基线，不再承诺旧 Node 版本兼容。
 
 ---
 
@@ -64,10 +66,25 @@ npm install schema-dsl
 // CommonJS
 const { dsl, validate } = require('schema-dsl');
 
-// ES Modules
+// ES Modules（named import）
 import { dsl, validate } from 'schema-dsl';
+
+// ES Modules（default import）
+import dslDefault from 'schema-dsl';
 ```
 
+### Q: i18n 目录加载支持哪些语言包文件格式？
+
+**A**: 在 **Node.js >= 18.0.0** 下，`dsl.config({ i18n: '/path/to/locales' })` 默认支持：
+
+- `.js`（CommonJS 语言包）
+- `.cjs`
+- `.json`
+- `.jsonc`
+- `.json5`
+
+**推荐**：如果你的项目是 `type: module` / ESM，优先使用 `.cjs`、`.json`、`.jsonc`、`.json5`，兼容性最稳定。
+
 ---
 
 ## DSL 语法问题
@@ -175,12 +192,9 @@ const result = validator.validate(schema, data);
 
 ```javascript
 {
-  valid: true/false,    // 是否通过
-  errors: [],           // 错误数组（如果有）
-  data: {},             // 验证后的数据（可能包含默认值）
-  performance: {        // 性能信息
-    duration: 1.5       // 验证耗时（毫秒）
-  }
+  valid: true/false,      // 是否通过
+  data: {},               // 当前实现会返回本次验证数据，失败时也便于定位输入
+  errors: []              // 成功时为空数组，失败时包含详细错误
 }
 ```
 
@@ -188,12 +202,14 @@ const result = validator.validate(schema, data);
 
 ### Q: 如何获取所有错误而不是只有第一个？
 
-**A**: 默认就是返回所有错误。如果只需要第一个：
+**A**: 默认就会返回全部错误。如果你只想保留首条错误，可以显式关闭 `allErrors`：
 
 ```javascript
 const validator = new Validator({ allErrors: false });
 ```
 
+`allErrors` 需要在创建 `Validator` 实例时配置，`validator.validate(schema, data, options)` 不能按次覆盖这个开关。
+
 ---
 
 ### Q: 如何使用默认值？
@@ -215,38 +231,27 @@ console.log(result.data);
 
 ## 性能问题
 
-### Q: Schema-DSL 的性能怎么样？
+### Q: schema-dsl 的性能怎么样？
 
-**A**: 性能优秀，排名第3：
+**A**: 性能不错，**S3 嵌套场景快于 Zod（28%），无效数据公平对比快 89x**：
 
-| 库名 | 每秒操作数 | 排名 |
-|------|-----------|------|
-| Ajv | 2,000,000 ops/s | 🥇 第1 |
-| Zod | 526,316 ops/s | 🥈 第2 |
-| **Schema-DSL** | **277,778 ops/s** | 🥉 **第3** |
-| Joi | 97,087 ops/s | 第4 |
-| Yup | 60,241 ops/s | 第5 |
+| 场景 | Schema-DSL | Zod | 对比 |
+|------|-----------|-----|------|
+| S1 简单有效 | **1.301M ops/s** | 1.305M ops/s | ≈ 持平（差 <1%）|
+| S2 无效（均无 i18n）| **1.205M ops/s** | 13.49K ops/s | ✅ 快 **89x** |
+| S3 嵌套有效 | **1.085M ops/s** | 847K ops/s | ✅ 快 **28%** |
+| 底层 Ajv (raw) | ~4.7M ops/s | — | 底层引擎 |
 
 **结论**:
-- ✅ 比 Joi 快 **2.86倍**
-- ✅ 比 Yup 快 **4.61倍**
-- ✅ 对大多数应用足够（27万+ ops/s）
+- ✅ S3 嵌套场景快于 Zod（**28%**），S1 简单有效场景持平；无效数据公平对比快 **89x**
+- ✅ 比 Joi 快约 **13x**（无效数据公平对比）
+- ✅ 内置缓存确保热路径零解析开销
 
 ---
 
-### Q: 为什么比 Zod 慢？
-
-**A**: 因为 Schema-DSL 使用**运行时解析 DSL**，而 Zod 是**编译时构建**。
+### Q: 有效/无效数据场景性能差异为什么大？
 
-**权衡**:
-```
-损失: 比 Zod 慢 1.9倍
-换来:
-  ✅ 代码量减少 65%
-  ✅ 完全动态的验证规则
-  ✅ 多租户/配置驱动支持
-  ✅ 前后端共享规则
-```
+**A**: 公平对比（S2，均不做 i18n 格式化）schema-dsl 显著快于 Zod（**89x**）。Zod 在无效数据场景极慢的根源是其错误收集使用异常驱动（`try/catch` 控制流），每个无效字段抛出一次 Error，4 个错误字段 = 4 次 Error 实例创建 + 4 次堆栈捕获。schema-dsl 基于 AJV 的无异常收集路径，无格式化时达 1.2M ops/s。
 
 ---
 
@@ -299,7 +304,7 @@ app.post('/api/users', (req, res) => {
 
 ### Q: 缓存如何工作？
 
-**A**: SchemaI-DSL 内置 LRU 缓存：
+**A**: schema-dsl 当前通过 `CacheManager` 委托 `cache-hub` 的 `MemoryCache` 实现编译缓存：
 
 ```javascript
 const validator = new Validator({
@@ -310,13 +315,15 @@ const validator = new Validator({
 });
 
 // 缓存统计
-const stats = validator.cache.getStats();
+const stats = validator.getCacheStats();
 console.log(stats);
 // {
-//   size: 150,      // 当前缓存数
-//   hits: 8500,     // 缓存命中次数
-//   misses: 150,    // 缓存未命中次数
-//   evictions: 0    // 驱逐次数
+//   hits: 8500,
+//   misses: 150,
+//   hitRate: '98.27',
+//   size: 150,
+//   maxSize: 5000,
+//   enabled: true
 // }
 ```
 
@@ -324,11 +331,16 @@ console.log(stats);
 
 ### Q: 如何批量验证？
 
-**A**: 使用 `validateBatch()`：
+**A**: 使用 `SchemaUtils.validateBatch()`：
 
 ```javascript
-const results = validator.validateBatch(schema, [data1, data2, data3]);
-// 返回结果数组
+const { SchemaUtils, Validator } = require('schema-dsl');
+
+const validator = new Validator();
+const batch = SchemaUtils.validateBatch(schema, [data1, data2, data3], validator.getAjv());
+
+console.log(batch.summary.valid);
+console.log(batch.results[0].valid);
 ```
 
 ---
@@ -368,7 +380,7 @@ const results = validator.validateBatch(schema, [data1, data2, data3]);
 6. **前后端共享验证** - 一套规则，两端使用
 
 ⚠️ **不适合的场景**:
-1. 极致性能要求（>50万 ops/s）→ 推荐 **Zod** 或 **Ajv**
+1. 绝对吞吐量优先、且不需要 DSL 动态能力 → 推荐 **Ajv**
 2. TypeScript 强类型推断 → 推荐 **Zod**
 3. 静态验证规则 → 推荐 **Zod**
 
@@ -415,16 +427,12 @@ JSON.stringify({ username: 'string:3-32!' });
 
 **A**: Schema-DSL 的设计优先级：
 
-```
+```text
 灵活性 > 易用性 > 性能
 ```
 
 **权衡结果**:
-- 损失：比 Zod 慢 1.9倍
-- 换来：完全的动态性 + 代码量减少 65%
-- 结论：对大多数应用（<10万 ops/s）足够
-
-**如果需要极致性能**: 推荐使用 Zod（526k ops/s）或 Ajv（2M ops/s）
+- 增益：S3 嵌套场景快于 Zod 28%，S1 持平；无效数据公平对比快 89x
 
 ---
 
@@ -467,12 +475,12 @@ validator.validate(schema, data, { locale: 'zh-CN' });
 
 ### Q: 错误路径格式是什么？
 
-**A**: JSON Pointer 格式：
+**A**: 当前返回的是 slash path：
 
 ```javascript
-'/username'           // 顶层字段
-'/user/name'          // 嵌套字段
-'/items/0/name'       // 数组元素
+'username'           // 顶层字段
+'user/name'          // 嵌套字段
+'items/0/name'       // 数组元素
 ```
 
 ---
@@ -523,18 +531,21 @@ MySQL 会生成 `COMMENT`，PostgreSQL 会生成 `COMMENT ON COLUMN`。
 
 ## TypeScript 支持
 
-### Q: SchemaI-DSL 支持 TypeScript 吗？
+### Q: schema-dsl 支持 TypeScript 吗？
 
-**A**: 支持，类型定义在 `index.d.ts`：
+**A**: 支持。当前更稳定的 TypeScript 写法是直接使用 `dsl('...')` Builder API，而不是依赖 String 原型扩展：
 
 ```typescript
-import { dsl, validate, DslBuilder, Validator } from 'schema-dsl';
+import { dsl, validate, Validator } from 'schema-dsl';
 
 const schema = dsl({
   username: 'string:3-32!',
-  email: 'email!'
+  email: dsl('email!').label('邮箱地址').error({
+    required: '请输入邮箱地址'
+  })
 });
 
+const validator = new Validator({ allErrors: true });
 const result = validate(schema, data);
 if (result.valid) {
   console.log(result.data);
@@ -543,14 +554,15 @@ if (result.valid) {
 
 ---
 
-### Q: 如何获得 String 扩展的类型提示？
+### Q: TypeScript 下如何写出更稳妥的链式提示？
 
-**A**: 类型定义包含全局 String 扩展：
+**A**: 推荐始终从 `dsl('...')` 开始链式调用；这样能和当前类型声明保持一致：
 
 ```typescript
-// TypeScript 会识别这些方法
 const schema = dsl({
-  email: 'email!'.label('邮箱').messages({ ... })
+  email: dsl('email!')
+    .label('邮箱')
+    .error({ format: '请输入有效邮箱地址' })
 });
 ```
 
@@ -560,7 +572,7 @@ const schema = dsl({
 
 如果您有其他问题：
 
-1. 查看 [完整文档](INDEX.md)
+1. 查看 [完整文档](doc-index.md)
 2. 查看 [DSL 语法指南](dsl-syntax.md)
 3. 查看 [API 参考](api-reference.md)
 4. 提交 [GitHub Issue](https://github.com/schema-dsl/schema-dsl/issues)
@@ -575,3 +587,10 @@ const schema = dsl({
 - [导出指南](export-guide.md)
 - [错误处理](error-handling.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [faq.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/faq.ts)  
+**说明**: 把 FAQ 里最常被复制的 4 类场景放在一个可运行示例中: 单次验证、多语言错误、批量验证、缓存统计。
+

package/docs/frontend-i18n-guide.md

@@ -60,7 +60,7 @@ app.post('/api/validate/:type', (req, res) => {
   }
   
   // 从请求头获取语言偏好
-  const locale = req.headers['accept-language'] || 'en-US';
+  const locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'en-US';
   
   // 验证（直接切换语言，无需重新加载）
   const result = validate(schema, req.body, { locale });
@@ -71,7 +71,7 @@ app.post('/api/validate/:type', (req, res) => {
 // 用户注册（带验证）
 app.post('/api/register', (req, res) => {
   // 从请求头获取语言偏好
-  const locale = req.headers['accept-language'] || 'en-US';
+  const locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'en-US';
   
   // 验证数据
   const result = validate(schemas.user, req.body, { locale });
@@ -222,13 +222,20 @@ app.post('/api/validate', (req, res) => {
 
 ### Q2: 每次请求创建 Validator 实例会影响性能吗？
 
-**A**: 不会。Validator 实例创建非常轻量，且验证器内部有编译缓存。
+**A**: 实例创建本身很轻量，但**仍然建议复用同一个 `Validator` 实例**。原因不是构造函数慢，而是编译缓存挂在实例上；如果每个请求都 `new Validator()`，同一份 Schema 会反复出现首次编译 miss。
 
 ```javascript
-// 性能测试结果
-// 创建实例: ~0.001ms
-// 验证数据: ~0.1-1ms
-// 总计: 可忽略不计
+const validator = new Validator();
+
+app.post('/api/validate', (req, res) => {
+  const locale = resolveLocale(req);
+  const result = validator.validate(schema, req.body, { locale });
+  res.json(result);
+});
+
+// 说明：
+// - 共享实例：同一 schema 的后续请求可以复用编译缓存
+// - 语言仍通过 validate(..., { locale }) 按次传入，不要写进构造函数
 ```
 
 ### Q3: 如何支持更多语言？
@@ -250,8 +257,8 @@ Locale.addLocale('de-DE', {
 **A**: 后端返回错误消息已经是本地化的，前端无需处理。如果需要前端验证：
 
 ```javascript
-// 前端可以使用相同的 SchemaI-DSL（浏览器版）
-import { dsl, validate } from 'schema-dsl/browser';
+// 前端可以复用同一套 schema-dsl 校验规则
+import { dsl, validate } from 'schema-dsl';
 
 const schema = dsl({ /* ... */ });
 const result = validate(schema, formData, { 
@@ -265,12 +272,12 @@ const result = validate(schema, formData, {
 // 中间件：优先级 Header > Cookie > Session > 默认
 app.use((req, res, next) => {
   const locale = 
-    req.headers['accept-language'] ||
+    req.headers['accept-language']?.split(',')[0]?.trim() ||
     req.cookies?.locale ||
     req.session?.locale ||
     'en-US';
   
-  req.validator = new Validator({ locale });
+  req.locale = locale;
   next();
 });
 ```
@@ -281,7 +288,7 @@ app.use((req, res, next) => {
 
 ### ✅ 推荐做法
 
-1. **使用实例级配置**：每个请求创建独立 Validator
+1. **复用共享 Validator 实例**：按次通过 `validate(..., { locale })` 传入语言
 2. **通过请求头传递语言**：符合 HTTP 标准
 3. **使用中间件统一处理**：提高代码复用性
 
@@ -291,3 +298,10 @@ app.use((req, res, next) => {
 - [API 参考](api-reference.md)
 - [最佳实践](best-practices.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [frontend-i18n-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/frontend-i18n-guide.ts)  
+**说明**: 覆盖前端常见的语言优先级解析、表单提交验证，以及把错误数组整理成字段级错误映射。
+

package/docs/i18n-user-guide.md

@@ -1,6 +1,6 @@
 # 多语言支持用户指南
 
-> **更新日期**: 2025-12-29
+> **更新日期**: 2026-04-30
 
 ---
 
@@ -17,6 +17,11 @@
 
 ## 快速开始
 
+> **Node.js 要求**：`>=18.0.0`
+>
+> **目录加载（Node >=18）默认支持的语言文件格式**：`.js`（CommonJS）、`.cjs`、`.json`、`.jsonc`、`.json5`。  
+> **推荐**：如果你的应用是 `type: module` / ESM 项目，优先使用 `.cjs`、`.json`、`.jsonc`、`.json5`。
+
 ### 5 分钟上手
 
 ```javascript
@@ -50,7 +55,12 @@ const result = validate(schema, data, { locale: 'zh-CN' });
 
 ## 配置方式
 
-### 方式 1：直接传入对象（推荐小型项目）
+### 方式 1：传入对象配置（推荐小型项目）
+
+`schema-dsl` 同时支持两种对象写法：
+
+- 兼容包装层：`{ i18n: { locales: { ... } } }`
+- 简写形式：`{ i18n: { 'zh-CN': { ... }, 'en-US': { ... } } }`
 
 ```javascript
 dsl.config({
@@ -71,6 +81,23 @@ dsl.config({
 });
 ```
 
+**简写形式**:
+
+```javascript
+dsl.config({
+  i18n: {
+    'zh-CN': {
+      'username': '用户名',
+      'email': '邮箱地址'
+    },
+    'en-US': {
+      'username': 'Username',
+      'email': 'Email Address'
+    }
+  }
+});
+```
+
 **优点**:
 - ✅ 简单直接
 - ✅ 适合小型项目
@@ -85,13 +112,13 @@ dsl.config({
 ### 方式 2：从目录加载（推荐大型项目）
 
 **目录结构**:
-```
+```text
 project/
   ├── i18n/
   │   └── labels/
-  │       ├── zh-CN.js
-  │       ├── en-US.js
-  │       └── ja-JP.js
+  │       ├── zh-CN.cjs
+  │       ├── en-US.jsonc
+  │       └── ja-JP.json5
   ├── app.js
   └── routes/
 ```
@@ -107,7 +134,7 @@ dsl.config({
 });
 ```
 
-**语言包文件**（`i18n/labels/zh-CN.js`）:
+**语言包文件**（`i18n/labels/zh-CN.cjs`）:
 ```javascript
 module.exports = {
   // 字段标签
@@ -148,7 +175,7 @@ dsl.config({
 
 | 项目规模 | maxSize | 说明 |
 |---------|---------|------|
-| 小型（< 100 Schema） | 1000（默认） | 够用 |
+| 小型（< 100 Schema） | 1000 | 够用 |
 | 中型（100-1000） | 5000（默认） | 推荐 |
 | 大型（1000-5000） | 10000 | 推荐 |
 | 超大型（> 5000） | 20000 | 推荐 |
@@ -186,7 +213,7 @@ const addressSchema = dsl({
 
 **语言包**:
 ```javascript
-{
+const labels = {
   'address.city': '城市',
   'address.street': '街道',
   'address.zipCode': '邮编'
@@ -206,10 +233,10 @@ const { validate } = require('schema-dsl');
 const app = express();
 app.use(express.json());
 
-// 中间件：提取语言参数
+// 中间件：提取语言参数（简化版：query > Accept-Language > 默认）
 app.use((req, res, next) => {
-  req.locale = req.headers['accept-language'] || 
-               req.query.lang || 
+  req.locale = req.query.lang ||
+               req.headers['accept-language']?.split(',')[0]?.trim() || 
                'zh-CN';
   next();
 });
@@ -343,22 +370,22 @@ const handleSubmit = async () => {
 ### 1. 语言包组织
 
 **推荐结构**:
-```
+```text
 i18n/
   ├── labels/         # 字段标签
-  │   ├── zh-CN.js
-  │   ├── en-US.js
-  │   └── ja-JP.js
+  │   ├── zh-CN.cjs
+  │   ├── en-US.jsonc
+  │   └── ja-JP.json5
   └── messages/       # 自定义消息（可选）
-      ├── zh-CN.js
-      └── en-US.js
+      ├── zh-CN.cjs
+      └── en-US.json
 ```
 
 ### 2. 命名规范
 
 **字段标签**:
 ```javascript
-{
+const fieldLabels = {
   'username': '用户名',           // 简单字段
   'address.city': '城市',         // 嵌套字段
   'order.items[0].name': '商品名称' // 数组字段
@@ -367,7 +394,7 @@ i18n/
 
 **自定义消息**:
 ```javascript
-{
+const customMessages = {
   'custom.emailTaken': '邮箱已被注册',
   'custom.passwordWeak': '密码强度不够',
   'custom.orderExpired': '订单已过期'
@@ -381,8 +408,8 @@ i18n/
 const locale = 
   req.query.lang ||              // 1. URL 参数（最高优先级）
   req.cookies.lang ||            // 2. Cookie
-  req.headers['accept-language'] || // 3. Accept-Language 头
-  'zh-CN';                       // 4. 默认语言
+  req.headers['accept-language']?.split(',')[0]?.trim() || // 3. Accept-Language 头（取首个语言标签）
+  'en-US';                       // 4. 默认语言
 ```
 
 ### 4. 语言持久化
@@ -405,7 +432,7 @@ const savedLang = localStorage.getItem('userLanguage') || 'zh-CN';
 **A**: 创建新的语言包文件并重启应用
 
 ```javascript
-// i18n/labels/ko-KR.js（韩语）
+// i18n/labels/ko-KR.cjs（韩语）
 module.exports = {
   'username': '사용자 이름',
   'email': '이메일 주소'
@@ -416,10 +443,10 @@ module.exports = {
 
 **A**: 系统会自动回退
 
-```
+```text
 查找顺序：
-1. 用户语言包（i18n/labels/zh-CN.js）
-2. 系统语言包（lib/locales/zh-CN.js）
+1. 用户语言包（例如 `i18n/labels/zh-CN.cjs` / `zh-CN.jsonc`）
+2. 内置语言包（包内预置的 `zh-CN` / `en-US` / `ja-JP` / `es-ES` / `fr-FR`）
 3. 使用 key 本身
 ```
 
@@ -427,7 +454,7 @@ module.exports = {
 
 **A**: 大型项目提升 3-10 倍
 
-```
+```text
 场景：3000 个 Schema
 原配置（1000）：33% 命中率
 优化后（5000）：100% 命中率
@@ -440,35 +467,21 @@ module.exports = {
 
 ```javascript
 // 动态添加语言
+const frFR = require('./i18n/fr-FR.cjs');
+
 dsl.config({
   i18n: {
     locales: {
-      'fr-FR': require('./i18n/fr-FR.js')
+      'fr-FR': frFR
     }
   }
 });
 ```
 
-### Q5: 如何与其他 i18n 库协同？
-
-**A**: 保持语言同步
-
-```javascript
-import i18next from 'i18next';
-import { Locale } from 'schema-dsl';
-
-// 同时切换两个库的语言
-function changeLanguage(lang) {
-  i18next.changeLanguage(lang);
-  Locale.setLocale(lang);
-}
-```
-
 ---
 
-## 相关文档
+## 对应示例文件
 
-- [API 参考](./api-reference.md)
-- [完整示例](../examples/i18n-full-demo.js)
-- [动态缓存优化](./cache-manager.md)
+**示例入口**: [i18n-user-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/i18n-user-guide.ts)  
+**说明**: 覆盖 `dsl.config({ i18n: { locales: ... } })` 的对象配置方式、已加载语言列表，以及不同 locale 的运行时切换。