schema-dsl 1.2.5 → 2.0.1

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

@@ -1,143 +1,150 @@
-# SchemaUtils 使用指南
-
-> Schema 复用和转换工具  
-
----
-
-## 快速开始
-
-4 个方法复用 Schema：
-
-```javascript
-const { dsl, SchemaUtils } = require('schema-dsl');
-
-const userSchema = dsl({
-  id: 'objectId!',
-  name: 'string!',
-  email: 'email!',
-  password: 'string!',
-  age: 'integer:18-120'
-});
-
-// 排除字段
-SchemaUtils.omit(userSchema, ['password']);
-
-// 保留字段
-SchemaUtils.pick(userSchema, ['name', 'email']);
-
-// 变为可选
-SchemaUtils.partial(userSchema);
-
-// 扩展字段
-SchemaUtils.extend(userSchema, { avatar: 'url' });
-```
-
----
-
-## omit - 排除字段
-
-```javascript
-// 创建用户 - 排除系统字段
-const createSchema = SchemaUtils.omit(userSchema, ['id', 'createdAt']);
-
-// 公开信息 - 排除敏感字段
-const publicSchema = SchemaUtils.omit(userSchema, ['password']);
-```
-
----
-
-## pick - 保留字段
-
-```javascript
-// 只允许修改部分字段
-const updateSchema = SchemaUtils.pick(userSchema, ['name', 'age']);
-```
-
----
-
-## partial - 变为可选
-
-```javascript
-// 所有字段变为可选
-const partialSchema = SchemaUtils.partial(userSchema);
-```
-
----
-
-## extend - 扩展字段
-
-```javascript
-// 添加新字段
-const extendedSchema = SchemaUtils.extend(userSchema, {
-  avatar: 'url',
-  bio: 'string:0-500'
-});
-```
-
----
-
-## 链式调用
-
-```javascript
-// pick + partial
-SchemaUtils.pick(userSchema, ['name', 'age']).partial();
-
-// pick + extend
-SchemaUtils.pick(userSchema, ['name']).extend({ avatar: 'url' });
-```
-
----
-
-## Express 示例
-
-```javascript
-const { dsl, SchemaUtils, validateAsync } = require('schema-dsl');
-
-const userSchema = dsl({
-  id: 'objectId!',
-  name: 'string!',
-  email: 'email!',
-  password: 'string!',
-  age: 'integer:18-120'
-});
-
-// POST /users - 创建
-app.post('/users', async (req, res, next) => {
-  const schema = SchemaUtils.omit(userSchema, ['id']);
-  const data = await validateAsync(schema, req.body);
-  // 保存到数据库...
-});
-
-// GET /users/:id - 查询
-app.get('/users/:id', async (req, res) => {
-  const schema = SchemaUtils.omit(userSchema, ['password']);
-  const user = await db.findById(req.params.id);
-  const result = validate(schema, user);
-  res.json(result.data);
-});
-
-// PATCH /users/:id - 更新
-app.patch('/users/:id', async (req, res, next) => {
-  const schema = SchemaUtils.pick(userSchema, ['name', 'age']).partial();
-  const data = await validateAsync(schema, req.body);
-  // 更新数据库...
-});
-```
-
----
-
-## API
-
-### omit(schema, fields)
-排除字段
-
-### pick(schema, fields)
-保留字段
-
-### partial(schema, fields?)
-变为可选
-
-### extend(schema, extensions)
-扩展字段
-
-
+# SchemaUtils 使用指南
+
+> Schema 复用和转换工具  
+
+---
+
+## 快速开始
+
+4 个方法复用 Schema：
+
+```javascript
+const { dsl, SchemaUtils } = require('schema-dsl');
+
+const userSchema = dsl({
+  id: 'objectId!',
+  name: 'string!',
+  email: 'email!',
+  password: 'string!',
+  age: 'integer:18-120'
+});
+
+// 排除字段
+SchemaUtils.omit(userSchema, ['password']);
+
+// 保留字段
+SchemaUtils.pick(userSchema, ['name', 'email']);
+
+// 变为可选
+SchemaUtils.partial(userSchema);
+
+// 扩展字段
+SchemaUtils.extend(userSchema, { avatar: 'url' });
+```
+
+---
+
+## omit - 排除字段
+
+```javascript
+// 创建用户 - 排除系统字段
+const createSchema = SchemaUtils.omit(userSchema, ['id', 'createdAt']);
+
+// 公开信息 - 排除敏感字段
+const publicSchema = SchemaUtils.omit(userSchema, ['password']);
+```
+
+---
+
+## pick - 保留字段
+
+```javascript
+// 只允许修改部分字段
+const updateSchema = SchemaUtils.pick(userSchema, ['name', 'age']);
+```
+
+---
+
+## partial - 变为可选
+
+```javascript
+// 所有字段变为可选
+const partialSchema = SchemaUtils.partial(userSchema);
+```
+
+---
+
+## extend - 扩展字段
+
+```javascript
+// 添加新字段
+const extendedSchema = SchemaUtils.extend(userSchema, {
+  avatar: 'url',
+  bio: 'string:0-500'
+});
+```
+
+---
+
+## 链式调用
+
+```javascript
+// pick + partial
+SchemaUtils.pick(userSchema, ['name', 'age']).partial();
+
+// pick + extend
+SchemaUtils.pick(userSchema, ['name']).extend({ avatar: 'url' });
+```
+
+---
+
+## Express 示例
+
+```javascript
+const { dsl, SchemaUtils, validateAsync } = require('schema-dsl');
+
+const userSchema = dsl({
+  id: 'objectId!',
+  name: 'string!',
+  email: 'email!',
+  password: 'string!',
+  age: 'integer:18-120'
+});
+
+// POST /users - 创建
+app.post('/users', async (req, res, next) => {
+  const schema = SchemaUtils.omit(userSchema, ['id']);
+  const data = await validateAsync(schema, req.body);
+  // 保存到数据库...
+});
+
+// GET /users/:id - 查询
+app.get('/users/:id', async (req, res) => {
+  const schema = SchemaUtils.omit(userSchema, ['password']);
+  const user = await db.findById(req.params.id);
+  const result = validate(schema, user);
+  res.json(result.data);
+});
+
+// PATCH /users/:id - 更新
+app.patch('/users/:id', async (req, res, next) => {
+  const schema = SchemaUtils.pick(userSchema, ['name', 'age']).partial();
+  const data = await validateAsync(schema, req.body);
+  // 更新数据库...
+});
+```
+
+---
+
+## API
+
+### omit(schema, fields)
+排除字段
+
+### pick(schema, fields)
+保留字段
+
+### partial(schema, fields?)
+变为可选
+
+### 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 的成功/失败验证路径。
+
+