schema-dsl 1.2.4 → 2.0.0

package/docs/schema-utils-advanced-issues.md

@@ -0,0 +1,23 @@
+# SchemaUtils 深入问题分析
+
+## 常见问题
+
+### 内部字段泄漏
+
+链式 DSL 会产生 `_label`、`_customMessages`、`_required` 等内部字段。面向 OpenAPI 或外部系统时，应在 Builder 阶段使用 `toJsonSchema()` 输出纯净 JSON Schema。
+
+### required 同步
+
+使用 `pick()`、`omit()`、`partial()` 后应检查 `required` 是否符合预期，当前实现会同步处理顶层 required。
+
+### 深拷贝限制
+
+`SchemaUtils.clone()` 基于 JSON 序列化，不保留函数、`RegExp` 实例等非 JSON 值。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [schema-utils-advanced-issues.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/schema-utils-advanced-issues.ts)  
+**说明**: 覆盖内部字段泄漏、`required` 同步和 `clone()` 深拷贝边界三个最容易踩坑的点。
+

package/docs/schema-utils-best-practices.md

@@ -0,0 +1,20 @@
+# SchemaUtils 最佳实践
+
+## 推荐用法
+
+- 使用 `SchemaUtils.reusable()` 封装可复用字段工厂。
+- 使用 `SchemaUtils.extend()` 组合基础 Schema 与业务扩展字段。
+- 使用 `pick()` / `omit()` / `partial()` 生成派生 Schema，避免手写重复定义。
+
+## 注意事项
+
+- 派生 Schema 后仍需用 `validate()` 或 `Validator` 做回归验证。
+- 对外导出标准 JSON Schema 时，优先在 Builder 阶段使用 `toJsonSchema()`，或在导出前显式清理内部字段。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [schema-utils-best-practices.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/schema-utils-best-practices.ts)  
+**说明**: 以创建、公开返回、局部更新三个场景展示字段库复用与派生 schema 的推荐组织方式。
+

package/docs/schema-utils-chaining.md

@@ -140,4 +140,11 @@ app.patch('/users/:id', async (req, res, next) => {
 ### extend(schema, extensions)
 扩展字段
 
+---
+
+## 对应示例文件
+
+**示例入口**: [schema-utils-chaining.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/schema-utils-chaining.ts)  
+**说明**: 覆盖 `omit()`、`extend()`、`pick()`、`partial()` 的链式组合，以及派生 schema 的成功/失败验证路径。
+
 

package/docs/schema-utils.md

@@ -113,32 +113,33 @@ const registerSchema = dsl({
 
 ## Schema 合并
 
-### merge() - 合并多个Schema
+### createLibrary() - 创建片段库
 
 ```javascript
 const { SchemaUtils, dsl } = require('schema-dsl');
 
-// 基础Schema
-const baseUser = dsl({
-  name: 'string:1-50!',
-  email: 'email!'
+const fields = SchemaUtils.createLibrary({
+  email: () => 'email!'.label('邮箱地址'),
+  phone: () => dsl('string!').phone('cn').label('手机号'),
+  profile: () => ({
+    bio: 'string:500',
+    avatar: 'url'
+  })
 });
 
-// 扩展Schema
-const withAge = dsl({
-  age: 'number:18-120',
-  gender: 'male|female|other'
+const registerSchema = dsl({
+  email: fields.email(),
+  phone: fields.phone(),
+  password: dsl('string!').password('strong')
 });
 
-// 扩展
-const fullUser = SchemaUtils.extend(baseUser, {
-  age: 'number:18-120',
-  bio: 'string:500',
-  avatar: 'url'
+const profileSchema = dsl({
+  ...fields.profile(),
+  email: fields.email()
 });
 ```
 
-**说明**: 扩展字段，合并 properties 和 required 数组
+**说明**: `createLibrary()` 只是返回片段工厂集合，适合在大型项目中集中管理字段和组合片段。
 
 ---
 
@@ -206,6 +207,32 @@ const safeUser = SchemaUtils.omit(fullUser, ['password']);
 
 ---
 
+### partial() - 将字段改为可选
+
+```javascript
+const updateSchema = SchemaUtils.partial(dsl({
+  name: 'string!',
+  email: 'email!',
+  age: 'number:18-120'
+}));
+
+// 结果中 required 会被移除，适合 PATCH / 局部更新场景
+```
+
+也可以只对部分字段做可选化：
+
+```javascript
+const schema = dsl({
+  name: 'string!',
+  email: 'email!',
+  age: 'number:18-120'
+});
+
+const partialContact = SchemaUtils.partial(schema, ['name', 'email']);
+```
+
+---
+
 ## Schema 导出
 
 ### toMarkdown() - 导出为Markdown文档
@@ -218,10 +245,7 @@ const schema = dsl({
 });
 
 const markdown = SchemaUtils.toMarkdown(schema, {
-  title: '用户注册Schema',
-  showRequired: true,
-  showType: true,
-  showConstraints: true
+  title: '用户注册Schema'
 });
 
 console.log(markdown);
@@ -246,8 +270,7 @@ console.log(markdown);
 
 ```javascript
 const html = SchemaUtils.toHTML(schema, {
-  title: '用户注册Schema',
-  theme: 'bootstrap'  // 或 'default'
+  title: '用户注册Schema'
 });
 
 // 生成HTML表格，可以嵌入文档
@@ -259,10 +282,10 @@ const html = SchemaUtils.toHTML(schema, {
 
 ## 性能监控
 
-### validateBatch() - 批量验证
+### validateBatch() - 批量验证统计
 
 ```javascript
-const { Validator } = require('schema-dsl');
+const { SchemaUtils, Validator, dsl } = require('schema-dsl');
 
 const schema = dsl({
   email: 'email!',
@@ -277,44 +300,46 @@ const items = [
   { email: 'user2@example.com', age: 30 }
 ];
 
-const results = validator.validateBatch(schema, items);
+const batch = SchemaUtils.validateBatch(schema, items, validator.getAjv());
 
-console.log(results);
+console.log(batch);
 // {
 //   results: [
-//     { valid: true, ... },
-//     { valid: false, errors: [...] },
-//     { valid: true, ... }
+//     { index: 0, valid: true, errors: null, data: {...} },
+//     { index: 1, valid: false, errors: [...], data: null },
+//     { index: 2, valid: true, errors: null, data: {...} }
 //   ],
-//   stats: {
+//   summary: {
 //     total: 3,
 //     valid: 2,
 //     invalid: 1,
-//     duration: '5.2ms'
+//     duration: 5,
+//     averageTime: 1.67
 //   }
 // }
 ```
 
-**用途**: 批量验证数据，获取性能统计
+**说明**:
+- 如果你只需要“每条是否通过”的结果，可直接使用 `validator.validateBatch(schema, items)`
+- 如果你还需要汇总统计信息，再使用 `SchemaUtils.validateBatch(schema, items, validator.getAjv())`
 
 ---
 
-### 性能监控（自动）
+### withPerformance() - 给 Validator 添加性能包装
 
 ```javascript
-const validator = new Validator({ performance: true });
+const validator = SchemaUtils.withPerformance(new Validator());
 
 const result = validator.validate(schema, data);
 
 console.log(result.performance);
 // {
-//   duration: '2.1ms',
-//   compileDuration: '1.5ms',
-//   validateDuration: '0.6ms'
+//   duration: 2,
+//   timestamp: '2026-05-06T12:34:56.789Z'
 // }
 ```
 
-**用途**: 监控验证性能
+**用途**: 在不改业务调用方式的前提下，为验证结果附加耗时信息
 
 ---
 
@@ -344,6 +369,8 @@ cloned.properties.user.properties.name.maxLength = 100;
 ### validateNestingDepth() - 检查嵌套深度
 
 ```javascript
+const { dsl, DslBuilder } = require('schema-dsl');
+
 const schema = dsl({
   level1: {
     level2: {
@@ -354,15 +381,15 @@ const schema = dsl({
   }
 });
 
-const depth = schema.validateNestingDepth(10);
-// 返回: 4
+const result = DslBuilder.validateNestingDepth(schema, 10);
+// 返回: { valid: true, depth: 4, path: 'level1.level2.level3', message: '...' }
 
-if (depth > 5) {
+if (result.depth > 5) {
   console.warn('嵌套层级过深，建议扁平化');
 }
 ```
 
-**用途**: 防止过深嵌套
+**说明**: 这个能力属于 `DslBuilder` 静态方法，不是 `SchemaUtils` 的成员；这里一并列出是因为它常与 Schema 工具链一起使用。
 
 ---
 
@@ -485,6 +512,13 @@ const schema = dsl({
 
 ---
 
-**最后更新**: 2025-12-25
+## 对应示例文件
+
+**示例入口**: [schema-utils.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/schema-utils.ts)  
+**说明**: 覆盖 `reusable()`、`createLibrary()`、`extend()`、`validateBatch()`、`withPerformance()` 和 `clone()` 的最小工作流。
+
+---
+
+**最后更新**: 2026-05-08
 
 

package/docs/security-checklist.md

@@ -0,0 +1,20 @@
+# 安全检查清单
+
+## 发布前检查
+
+- 运行 `npm audit --audit-level=moderate`。
+- 确认文档示例不包含真实密钥、Token 或密码。
+- 自定义正则应避免灾难性回溯。
+- 自定义 validator 不应执行不可信输入生成的代码。
+
+## 当前建议
+
+依赖升级后应重新运行完整测试与构建验证。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [security-checklist.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/security-checklist.ts)  
+**说明**: 使用占位 token、受限字符集和显式 URL 校验，示范文档中“不要暴露真实凭据”“正则要有界”的落地写法。
+

package/docs/string-extensions.md

@@ -1,6 +1,6 @@
 # String 扩展文档
 
-> **更新时间**: 2025-12-25  
+> **更新时间**: 2026-05-22  
 
 ---
 
@@ -63,7 +63,7 @@ const schema = dsl({
 | `.label(text)` | 字段标签 | `'email!'.label('邮箱地址')` |
 | `.messages(obj)` | 自定义消息 | `'string!'.messages({...})` |
 | `.description(text)` | 描述 | `'url'.description('主页')` |
-| `.custom(fn)` | 自定义验证 | `'string!'.custom(async...)` |
+| `.custom(fn)` | 自定义同步验证 | `'string!'.custom(value => value !== "admin")` |
 | `.default(value)` | 默认值 | `'string'.default('guest')` |
 | `.username(range?)` | 用户名验证 | `'string!'.username('5-20')` |
 | `.phone(country)` | 手机号验证 | `'string!'.phone('cn')` |
@@ -179,9 +179,8 @@ const schema = dsl({
 const schema = dsl({
   // 最优雅：只在失败时返回错误消息
   username: 'string:3-32!'
-    .custom(async (value) => {
-      const exists = await checkUsernameExists(value);
-      if (exists) return '用户名已被占用';
+    .custom((value) => {
+      if (value === 'admin') return '用户名已被占用';
       // 成功时无需返回
     })
     .label('用户名'),
@@ -197,6 +196,8 @@ const schema = dsl({
 });
 ```
 
+⚠️ `.custom()` 当前仅支持同步函数；需要异步查库或远程调用时，请在 `validate()` / `validateAsync()` 通过后于业务层单独执行。
+
 **支持的返回值**:
 - 不返回/`undefined` → 验证通过 ✅
 - 返回字符串 → 验证失败（错误消息）
@@ -206,8 +207,8 @@ const schema = dsl({
 - 返回 `false` → 验证失败（默认消息）
 
 **注意**: 
-- 异步验证器（async）需要使用 `validator.validateAsync()`（计划中）或在外部处理。
-- 目前 `validator.validate()` 是同步的，如果 `.custom()` 返回 Promise，会抛出错误提示。
+- 当前版本**不支持**在 `.custom()` 中直接返回 `Promise`；即使调用 `validateAsync()`，异步 custom validator 仍会报 `同步验证不支持异步操作`。
+- 需要异步校验时，请改为：① 先用 `schema-dsl` 做同步结构校验；② 再在业务层执行异步检查。
 
 
 ---
@@ -471,10 +472,17 @@ const schema = dsl({
 - [DSL 语法](./dsl-syntax.md)
 - [API 参考](./api-reference.md)
 - [多语言支持](./multi-language.md)
-- [示例代码](../examples/string-extensions.js)
+- [示例代码](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/string-extensions.ts)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [string-extensions.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/string-extensions.ts)  
+**说明**: 覆盖 String.prototype 扩展的安装/卸载、链式 `.label()` / `.messages()` / `.pattern()` 调用，以及校验成功/失败路径。
 
 ---
 
-**最后更新**: 2025-12-25
+**最后更新**: 2026-05-08
 
 

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # 常见问题排查指南
 
-> **用途**: 快速解决 SchemaI-DSL 使用中的常见问题  
+> **用途**: 快速解决 schema-dsl 使用中的常见问题  
 > **更新**: 2025-12-26  
 
 ---
@@ -41,10 +41,10 @@ const validator = new Validator({ verbose: true });
 const result = validator.validate(schema, data);
 ```
 
-3. **使用 Schema 分析工具**
+3. **使用 Schema 摘要工具**
 ```javascript
-const { SchemaUtils } = require('schema-dsl');
-console.log(SchemaUtils.analyze(schema));
+const { SchemaHelper } = require('schema-dsl');
+console.log(SchemaHelper.summarizeSchema(schema));
 ```
 
 4. **检查字段名是否正确**
@@ -79,14 +79,20 @@ email: 'email!'.custom(async (value) => {
 // ❌ 错误：在 validate() 中使用异步验证器
 const result = validate(schema, data); // 同步模式
 
-// ✅ 解决1：使用 validateAsync()
-const result = await validateAsync(schema, data);
+// ❌ 误区：validateAsync() 也不会让 .custom(async fn) 生效
+await validateAsync(schema, data); // 仍会抛“同步验证不支持异步操作”
 
-// ✅ 解决2：使用同步验证器
+// ✅ 正确：使用同步验证器
 email: 'email!'.custom((value) => {
   // 同步代码
   if (checkSync(value)) return '邮箱已被占用';
 })
+
+// ✅ 或者：把异步检查放到 schema-dsl 之外
+const result = validate(schema, data);
+if (result.valid) {
+  await checkEmailUniqueness(data.email);
+}
 ```
 
 #### 原因2: custom() 返回值不正确
@@ -258,13 +264,15 @@ console.log(Object.keys(Locale.locales));
 // 应该包含: ['zh-CN', 'en-US', 'ja-JP', ...]
 ```
 
-#### 2. 检查 Validator 配置
+#### 2. 检查验证调用是否传入 locale
 ```javascript
-// ❌ 未指定语言
+// ❌ 构造函数不会设置本次验证语言
 const validator = new Validator();
 
-// ✅ 指定语言
-const validator = new Validator({ locale: 'zh-CN' });
+// ✅ 在 validate 时按次指定语言
+const result = validator.validate(schema, data, {
+  locale: 'zh-CN'
+});
 ```
 
 #### 3. 动态切换语言
@@ -378,7 +386,7 @@ db.createCollection('users', {
 
 **解决方案**:
 ```javascript
-// SchemaI-DSL 默认会自动安装 String 扩展
+// schema-dsl 默认会自动安装 String 扩展
 // 如果未生效，手动安装：
 const { installStringExtensions } = require('schema-dsl');
 installStringExtensions();
@@ -405,15 +413,15 @@ console.log(JSON.stringify(schema, null, 2));
 // 查看实际生成的 JSON Schema 结构
 ```
 
-### 技巧2: 使用 Schema 分析工具
+### 技巧2: 使用 Schema 摘要工具
 
 ```javascript
-const { SchemaUtils } = require('schema-dsl');
+const { SchemaHelper } = require('schema-dsl');
 
-// 分析 Schema 结构
-const analysis = SchemaUtils.analyze(schema);
-console.log(analysis);
-// 输出字段列表、约束信息、嵌套深度等
+// 查看 Schema 结构摘要
+const summary = SchemaHelper.summarizeSchema(schema);
+console.log(summary);
+// 输出字段列表、required 数量、复杂度等
 ```
 
 ### 技巧3: 启用详细日志
@@ -458,13 +466,20 @@ describe('User Schema', () => {
 
 如果以上方法无法解决你的问题：
 
-1. **查看文档**: [完整文档索引](INDEX.md)
-2. **查看示例**: [examples/](../examples/) 目录
-3. **GitHub Issues**: [提交问题](https://github.com/schema-dsl/schema-dsl/issues)
+1. **查看文档**: [完整文档索引](doc-index.md)
+2. **查看示例**: [troubleshooting.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/troubleshooting.ts)
+3. **GitHub Issues**: [提交问题](https://github.com/vextjs/schema-dsl/issues)
 4. **常见问题**: [FAQ.md](faq.md)
 
 ---
 
+## 对应示例文件
+
+**示例入口**: [troubleshooting.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/troubleshooting.ts)  
+**说明**: 演示如何用 `validate()` 和 `compile()` 复现错误、查看路径/关键字/消息，并快速定位失败原因。
+
+---
+
 ## 贡献
 
 发现了新的常见问题？欢迎提交 PR 补充本文档！