schema-dsl 1.2.4 → 2.0.0

package/docs/validate-async.md

@@ -31,13 +31,18 @@ try {
 ---
 
 ## 基础用法
+
+```javascript
+try {
+  await validateAsync(userSchema, {
     name: '',
     email: 'invalid'
   });
 } catch (error) {
   console.log(error instanceof ValidationError); // true
   console.log(error.getFieldErrors());
-  // { name: '长度必须大于等于1', email: '邮箱格式错误', age: '字段必填' }
+  // { email: '邮箱格式错误' }
+  // `string!` 只表示字段必填；若要限制空字符串，需要叠加长度约束。
 }
 ```
 
@@ -51,7 +56,7 @@ try {
 class ValidationError extends Error {
   name: 'ValidationError'        // 错误名称
   message: string                // 友好的错误消息
-  errors: Array<Object>          // 原始错误列表
+  errors: Array<Object>          // 格式化后的错误项列表（path/message/keyword/...）
   data: any                      // 原始输入数据
   statusCode: 400                // HTTP 状态码
 }
@@ -185,10 +190,9 @@ const fullUserSchema = dsl({
   updatedAt: 'date'
 });
 
-// POST /users - 创建用户（严格模式）
+// POST /users - 创建用户（排除系统字段）
 const createSchema = SchemaUtils
-  .omit(fullUserSchema, ['id', 'createdAt', 'updatedAt'])
-  .strict();
+  .omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
 
 app.post('/users', async (req, res, next) => {
   try {
@@ -204,17 +208,17 @@ app.post('/users', async (req, res, next) => {
   }
 });
 
-// GET /users/:id - 查询用户（移除敏感字段）
+// GET /users/:id - 查询用户（业务层显式移除敏感字段）
 const publicSchema = SchemaUtils
-  .omit(fullUserSchema, ['password'])
-  .clean();
+  .pick(fullUserSchema, ['id', 'name', 'email', 'age', 'createdAt', 'updatedAt']);
 
 app.get('/users/:id', async (req, res, next) => {
   try {
     const user = await db.users.findById(req.params.id);
+    const { password, ...publicUser } = user;
     const { validate } = require('schema-dsl');
-    const result = validate(publicSchema, user);
-    res.json(result.data); // 自动移除 password
+    const result = validate(publicSchema, publicUser);
+    res.json(result.data);
   } catch (error) {
     next(error);
   }
@@ -223,8 +227,7 @@ app.get('/users/:id', async (req, res, next) => {
 // PATCH /users/:id - 更新用户（部分验证）
 const updateSchema = SchemaUtils
   .pick(fullUserSchema, ['name', 'age'])
-  .partial()
-  .loose();
+  .partial();
 
 app.patch('/users/:id', async (req, res, next) => {
   try {
@@ -239,10 +242,9 @@ app.patch('/users/:id', async (req, res, next) => {
   }
 });
 
-// PUT /users/:id - 替换用户（严格模式）
+// PUT /users/:id - 替换用户（排除系统字段）
 const replaceSchema = SchemaUtils
-  .omit(fullUserSchema, ['id', 'createdAt', 'updatedAt'])
-  .strict();
+  .omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
 
 app.put('/users/:id', async (req, res, next) => {
   try {
@@ -258,6 +260,8 @@ app.put('/users/:id', async (req, res, next) => {
 });
 ```
 
+> ⚠️ `SchemaUtils` 当前只负责生成派生 Schema（如 `pick()` / `omit()` / `partial()` / `extend()`），不会自动删除运行时对象上的额外字段。返回公开响应时，请先在业务层显式投影数据，再用 `validate()` 校验投影结果。
+
 ---
 
 ## 错误处理
@@ -349,10 +353,9 @@ const baseUserSchema = dsl({
   updatedAt: 'date'
 });
 
-// 注册 Schema（排除系统字段，严格模式）
+// 注册 Schema（排除系统字段）
 const registerSchema = SchemaUtils
-  .omit(baseUserSchema, ['id', 'createdAt', 'updatedAt'])
-  .strict();
+  .omit(baseUserSchema, ['id', 'createdAt', 'updatedAt']);
 
 // 注册接口
 app.post('/register', async (req, res, next) => {
@@ -380,13 +383,14 @@ app.post('/register', async (req, res, next) => {
       updatedAt: new Date()
     });
     
-    // 5. 返回公开信息（移除密码）
+    // 5. 返回公开信息（先显式投影，再按公开 Schema 校验）
     const publicSchema = SchemaUtils
-      .omit(baseUserSchema, ['password'])
-      .clean();
+      .pick(baseUserSchema, ['id', 'username', 'email', 'age', 'createdAt', 'updatedAt']);
+    
+    const { password, ...publicUser } = user;
     
     const { validate } = require('schema-dsl');
-    const result = validate(publicSchema, user);
+    const result = validate(publicSchema, publicUser);
     
     res.status(201).json({
       success: true,
@@ -452,7 +456,7 @@ new ValidationError(errors, data)
 **属性**:
 - `name: 'ValidationError'`
 - `message: string` - 友好的错误消息
-- `errors: Array<Object>` - 原始错误列表
+- `errors: Array<Object>` - 格式化后的错误项列表（如 `path`、`message`、`keyword`、`params`）
 - `data: any` - 原始输入数据
 - `statusCode: 400` - HTTP 状态码
 
@@ -470,11 +474,18 @@ new ValidationError(errors, data)
 - [SchemaUtils 链式调用](schema-utils-chaining.md) - Schema 复用简化方法
 - [validate.md](validate.md) - 传统同步验证方法
 - [error-handling.md](error-handling.md) - 错误处理指南
-- [Express 示例](../examples/express-integration.js) - 完整 Express 集成示例
+- [validate-async 完整示例](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validate-async.ts) - 顶层 `validateAsync()`、`ValidationError` 与业务层异步检查示例
+
+---
+
+## 对应示例文件
+
+**示例入口**: [validate-async.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validate-async.ts)  
+**说明**: 覆盖 `validateAsync()` 的成功路径、`ValidationError` 捕获，以及“结构校验通过后再做业务层异步检查”的推荐方式。
 
 ---
 
 **版本**: v1.0.4  
 **更新日期**: 2025-12-29  
-**作者**: SchemaI-DSL Team
+**作者**: schema-dsl Team
 

package/docs/validate-batch.md

@@ -0,0 +1,49 @@
+# validateBatch 方法
+
+`Validator.validateBatch(schema, dataArray)` 用同一个已编译 Schema 验证多条数据。
+
+## 方法签名
+
+```javascript
+validator.validateBatch(schema, dataArray)
+```
+
+## 返回值
+
+返回一个数组，每一项都与单次 `validator.validate()` 的返回结构一致：
+
+- `valid` - 是否通过
+- `data` - 验证后的数据（通过时）
+- `errors` - 错误列表（失败时）
+
+```javascript
+[
+  { valid: true, data: { email: 'a@example.com' }, errors: [] },
+  { valid: false, data: { email: 'bad' }, errors: [/* ... */] }
+]
+```
+
+```javascript
+const { Validator, dsl } = require('schema-dsl');
+const validator = new Validator();
+const schema = dsl({ email: 'email!' });
+const results = validator.validateBatch(schema, [
+  { email: 'a@example.com' },
+  { email: 'bad' }
+]);
+console.log(results);
+```
+
+## 适用场景
+
+- 导入数据前的批量校验
+- 同一 schema 下的大量记录预检查
+- 希望只编译一次 schema，再对整批数据复用
+
+---
+
+## 对应示例文件
+
+**示例入口**: [validate-batch.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validate-batch.ts)  
+**说明**: 覆盖 `Validator.validateBatch()` 的单次编译、多条数据复用，以及失败项错误输出。
+

package/docs/validate-dsl-object-support.md

@@ -6,13 +6,13 @@
 
 ## 答案
 
-**现在可以了！** 🎉 从 v1.1.7 开始，`validate()` 和 `validateAsync()` 都支持直接传入 DSL 对象。
+**现在可以了！** 🎉 当前 TypeScript 重构版中，顶层 `validate()` 和 `validateAsync()` 都支持直接传入 DSL 对象。
 
 ---
 
 ## 支持的三种方式
 
-### 方式1：传入 DSL 对象（✅ v1.1.7 新增）
+### 方式1：传入 DSL 对象（✅ 当前版本支持）
 
 ```javascript
 const { validate } = require('schema-dsl');
@@ -96,17 +96,13 @@ const result = validate(
 
 ### 自动检测逻辑
 
-`validate()` 函数会自动检测传入的 schema 类型：
+顶层 `validate()` / `validateAsync()` 会先归一化传入的 schema：
 
 ```javascript
 function validate(schema, data, options = {}) {
-  // ✅ 自动检测并转换 DSL 对象
-  if (_isDslObject(schema)) {
-    schema = DslAdapter.parseObject(schema);
-  }
-  
-  const validator = new Validator(options);
-  return validator.validate(schema, data, options);
+  const normalizedSchema = _normalizeSchemaInput(schema);
+  const validator = getDefaultValidator();
+  return validator.validate(normalizedSchema, data, options);
 }
 ```
 
@@ -128,9 +124,9 @@ function validate(schema, data, options = {}) {
 
 ## 为什么之前必须是 schema？
 
-### 历史原因
+### 背景
 
-在 v1.1.7 之前，`validate()` 不会自动转换 DSL 对象：
+早期实现中，顶层 `validate()` 不会自动转换 DSL 对象：
 
 ```javascript
 // ❌ v1.1.6 及之前版本会失败
@@ -143,9 +139,9 @@ const result = validate(
 
 **原因**：`validate()` 会把 DSL 对象当作标准 JSON Schema，而 `"email!"` 不是有效的 JSON Schema 关键字。
 
-### 解决方案
+### 当前方案
 
-v1.1.7 添加了自动检测和转换逻辑：
+当前 TypeScript 重构版已补齐自动检测和转换逻辑：
 
 1. **检测 DSL 对象**：识别对象中的 DSL 字符串
 2. **自动转换**：调用 `DslAdapter.parseObject()` 转换为 JSON Schema
@@ -191,7 +187,7 @@ module.exports = {
       .pattern(/^[a-zA-Z0-9_]+$/)
       .messages({ 'string.pattern': '只能包含字母、数字和下划线' }),
     email: 'email!',
-    password: 'password:strong!',
+    password: dsl('string!').password('strong'),
     age: 'number:18-120'
   }),
   
@@ -326,13 +322,13 @@ const result = validate(
 ## 完整示例
 
 ```javascript
-const { validate, validateAsync } = require('schema-dsl');
+const { dsl, validate, validateAsync } = require('schema-dsl');
 
 // 示例1：同步验证
 const result = validate(
   {
     email: 'email!',
-    password: 'password:strong!',
+    password: dsl('string!').password('strong'),
     age: 'number:18-120',
     username: 'string:3-32!'
   },
@@ -372,7 +368,7 @@ if (result.valid) {
 
 **答：现在不必了！** 
 
-- ✅ v1.1.7 开始支持直接传入 DSL 对象
+- ✅ 当前版本支持直接传入 DSL 对象
 - ✅ 自动检测并转换，无需手动包裹
 - ✅ 完全向后兼容，不影响原有功能
 - ✅ 同时支持 JSON Schema、DslBuilder、DSL 对象三种方式
@@ -423,7 +419,7 @@ const result = validate(
 每次调用 `validate()` 时，DSL 对象都会被转换为 JSON Schema：
 
 ```javascript
-// ❌ 性能较差：每次请求都重复转换（~3.4秒/1000次）
+// ❌ 性能较差：每次请求都重复转换
 app.post('/api/user', (req, res) => {
   const result = validate(
     { email: 'email!', age: 'number!' },  // ❌ 每次请求都会执行 DSL → JSON Schema 转换
@@ -431,7 +427,7 @@ app.post('/api/user', (req, res) => {
   );
 });
 
-// ✅ 性能最优：项目启动时转换一次，复用 schema（~3.3秒/1000次）
+// ✅ 性能最优：项目启动时转换一次，复用 schema
 const userSchema = dsl({ email: 'email!', age: 'number!' });  // ✅ 启动时转换一次
 
 app.post('/api/user', (req, res) => {
@@ -439,6 +435,8 @@ app.post('/api/user', (req, res) => {
 });
 ```
 
+> ℹ️ 具体耗时取决于机器性能、Node 版本、schema 复杂度和命中率；这里强调的是“预先转换后复用通常显著快于每次请求都重新转换”的相对结论，而不是固定秒数。
+
 **性能差异**：约 3-5%（对于简单 schema）
 
 **✅ 您的理解完全正确！**
@@ -456,7 +454,7 @@ const userSchemas = {
       .pattern(/^[a-zA-Z0-9_]+$/)
       .messages({ 'string.pattern': '只能包含字母、数字和下划线' }),
     email: 'email!',
-    password: 'password:strong!',
+    password: dsl('string!').password('strong'),
     age: 'number:18-120'
   }),
   
@@ -498,7 +496,7 @@ app.post('/api/login', (req, res) => {
 | **原型开发** | ✅ 直接用 DSL 对象 | 快速迭代，无需在意性能 |
 | **测试代码** | ✅ 直接用 DSL 对象 | 简洁清晰，易于维护 |
 
-### Q3: 为什么之前不这样设计？
+### Q3: 为什么复杂场景仍然建议先用 `dsl()` 转换？
 
 **历史原因**：
 
@@ -512,14 +510,14 @@ app.post('/api/login', (req, res) => {
    ```
    这种设计让每个步骤的职责更清晰。
 
-2. **避免隐式转换**（最小惊喜原则）
+2. **避免在高频路径里滥用隐式转换**（最小惊喜原则）
    ```javascript
    // 用户传入什么，就是什么
    validate(jsonSchema, data);  // JSON Schema
    validate(dslBuilder, data);  // DslBuilder
    
-   // ❌ 之前不支持隐式转换
-   validate({ email: 'email!' }, data);  // 会被当作 JSON Schema
+    // ⚠️ 当前虽然支持隐式转换，但高频场景仍建议预先转换后复用
+    validate({ email: 'email!' }, data);
    ```
 
 3. **类型安全考虑**（TypeScript）
@@ -545,7 +543,7 @@ app.post('/api/login', (req, res) => {
    }
    ```
 
-**为什么现在改变了？**
+**为什么当前版本要补齐这个能力？**
 
 1. **用户反馈**：很多用户期望更简洁的 API
 2. **智能检测**：通过 `_isDslObject()` 准确区分 DSL 对象和 JSON Schema
@@ -557,8 +555,8 @@ app.post('/api/login', (req, res) => {
 
 | 设计方案 | 优点 | 缺点 |
 |---------|------|------|
-| **显式转换**（v1.1.6） | 职责清晰、类型安全、性能最优 | 代码冗长、学习成本高 |
-| **自动转换**（v1.1.7） | 简洁直观、学习成本低 | 隐式行为、可能误用 |
+| **显式转换** | 职责清晰、类型安全、性能最优 | 代码稍长 |
+| **自动转换**（当前顶层便捷函数） | 简洁直观、学习成本低 | 在高频路径里有额外转换开销 |
 
 **最终选择**：两者都支持，让用户自由选择！
 
@@ -571,3 +569,10 @@ const schema = dsl({ email: 'email!' });
 validate(schema, data);
 ```
 
+---
+
+## 对应示例文件
+
+**示例入口**: [validate-dsl-object-support.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validate-dsl-object-support.ts)  
+**说明**: 覆盖直接传入 DSL 对象、混合使用 `DslBuilder` 与 DSL 字符串，以及顶层 `validate()` / `validateAsync()` 的真实支持边界。
+

package/docs/validate.md

@@ -55,11 +55,13 @@ validator.validate(schema, data, options = {})
 ```javascript
 {
   valid: Boolean,     // 是否有效
-  errors: Array,      // 错误列表
-  data: Any          // 验证后的数据（可能被 useDefaults 修改）
+  errors: Array,      // 成功时为空数组，失败时为错误列表
+  data: Any          // 当前实现会返回本次验证数据（可能被 useDefaults 修改）
 }
 ```
 
+当前实现中，`data` 与 `errors` 都会随结果一并返回：成功时 `errors` 为空数组，验证失败时仍会保留 `data` 以便排查输入。
+
 ---
 
 ## 参数详解
@@ -75,12 +77,25 @@ JSON Schema 对象，支持 JSON Schema Draft 7 标准。
 
 ### options 对象属性
 
+`validator.validate(schema, data, options)` 当前按本次调用实际读取以下参数：
+
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | `format` | Boolean | 否 | `true` | 是否格式化错误信息 |
+| `locale` | String | 否 | — | 动态指定语言，如 `'zh-CN'`、`'en-US'`、`'ja-JP'` |
+| `messages` | Object | 否 | — | 自定义错误消息覆盖 |
+
+### 相关配置入口
+
+以下能力**不属于** `validator.validate(schema, data, options)` 的逐次调用参数：
+
+| 能力 | 正确入口 | 说明 |
+|------|----------|------|
+| `allErrors` / `useDefaults` / `coerceTypes` / `removeAdditional` / `cache` | `new Validator(options)` | 这些配置在创建 `Validator` 实例时注入到底层 AJV / 缓存层 |
+| `strict` | Schema 本身 | 如果需要禁止额外字段，请在 schema 层使用 `DslBuilder.strict()` 或等价的 schema 级约束 |
+| `coerce` | 顶层 `validate()` / `validateAsync()` 便捷函数 | 顶层 helper 默认会做字符串 → 数字 / 布尔值的便捷转换，传 `{ coerce: false }` 可关闭 |
 
-**图例说明**:
-- ✅ **标准功能**: 该参数来自 JSON Schema 或 ajv 标准
+如果你需要在**单次调用**中覆盖错误输出，请使用上表中的 `format`、`locale`、`messages`；如果你需要调整验证器行为，请优先在 `Validator` 构造阶段配置。
 
 ---
 
@@ -97,7 +112,7 @@ result.valid === false  // 验证失败
 
 ### errors (Array)
 
-验证错误列表，当 `valid` 为 `false` 时包含详细错误信息。
+验证错误列表。当前实现成功时返回空数组，验证失败时包含详细错误信息。
 
 **错误对象结构**：
 ```javascript
@@ -111,7 +126,7 @@ result.valid === false  // 验证失败
 
 ### data (Any)
 
-验证后的数据。如果 Validator 配置了 `useDefaults: true`，则会应用 Schema 中定义的默认值。
+验证后的数据。当前实现即使在验证失败时也会保留本次验证数据，便于排查输入；如果 Validator 配置了 `useDefaults: true`，则也可能反映 Schema 中应用后的默认值。
 
 ---
 
@@ -151,9 +166,10 @@ const result = validator.validate(schema, {
 
 console.log(result.valid);  // false
 console.log(result.errors); 
+// 当前实现返回格式化后的错误列表：
 // [
-//   { path: '', message: "must have required property 'name'" },
-//   { path: 'age', message: 'must be number' }
+//   { path: 'name', message: 'name不能为空' },
+//   { path: 'age', message: 'age应该是 number 类型' }
 // ]
 ```
 
@@ -348,8 +364,7 @@ processData(result.data);
 const result = validator.validate(schema, data);
 
 if (!result.valid) {
-  const error = new ValidationError('数据验证失败');
-  error.errors = result.errors;
+  const error = new ValidationError(result.errors, data);
   throw error;
 }
 ```
@@ -394,18 +409,23 @@ app.post('/api/users', (req, res) => {
 ### 建议 3: 使用缓存
 
 ```javascript
-// 使用缓存键
-const result = validator.validate(
-  schema, 
-  data,
-  { cacheKey: 'user-schema' }  // 自动缓存编译结果
-);
+// 显式编译并复用缓存键
+const validateUser = validator.compile(schema, 'user-schema');
+
+console.log(validateUser(data));
 ```
 
 ---
 
 ## 常见问题
 
+---
+
+## 对应示例文件
+
+**示例入口**: [validate.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validate.ts)  
+**说明**: 覆盖顶层 `validate()` 的成功/失败路径、默认类型转换，以及关闭 `coerce` 后的行为差异。
+
 ### Q1: 如何验证可选字段？
 
 不在 `required` 数组中的字段自动为可选：

package/docs/validation-guide.md

@@ -158,9 +158,9 @@ const dataList = [
 
 const results = validator.validateBatch(schema, dataList);
 // [
-//   { valid: true, errors: [] },
-//   { valid: false, errors: [...] },
-//   { valid: false, errors: [...] }
+//   { valid: true, data: {...}, errors: [] },
+//   { valid: false, data: {...}, errors: [...] },
+//   { valid: false, data: {...}, errors: [...] }
 // ]
 ```
 
@@ -275,8 +275,9 @@ const validator = new Validator({ allErrors: true });
 ### 4. 监控性能
 
 ```javascript
+console.time('schema-dsl.validate');
 const result = validate(schema, data);
-console.log(`验证耗时: ${result.performance?.duration}ms`);
+console.timeEnd('schema-dsl.validate');
 ```
 
 ---
@@ -437,18 +438,35 @@ const quickSchema = dsl({
 // 完整验证（详细）
 const fullSchema = dsl({
   username: 'string:3-32!'.pattern(/^[a-z]+$/),
-  email: 'email!'.custom(async (v) => checkEmailUnique(v))
+  email: 'email!'
 });
 
 // 先快速验证，再完整验证
-function validateWithFallback(data) {
+async function validateWithFallback(data) {
   const quick = validate(quickSchema, data);
   if (!quick.valid) return quick;
 
-  return validate(fullSchema, data);
+  const full = validate(fullSchema, data);
+  if (!full.valid) return full;
+
+  if (await checkEmailUnique(data.email)) {
+    return {
+      valid: false,
+      errors: [{ field: 'email', keyword: 'business', message: '邮箱已被占用' }]
+    };
+  }
+
+  return full;
 }
 ```
 
+---
+
+## 对应示例文件
+
+**示例入口**: [validation-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validation-guide.ts)  
+**说明**: 覆盖推荐的验证流程：定义可复用 schema、格式化错误、预编译复用以及批量验证。
+
 ### 5. 测试验证逻辑
 
 ```javascript

package/docs/validator.md

@@ -0,0 +1,39 @@
+# Validator 类概述
+
+`Validator` 是对 AJV 的封装，提供编译缓存、错误格式化、自定义关键字和批量验证能力。
+
+```javascript
+const { Validator, dsl } = require('schema-dsl');
+const validator = new Validator();
+const schema = dsl({ email: 'email!' });
+console.log(validator.validate(schema, { email: 'test@example.com' }));
+```
+
+## 缓存配置
+
+`Validator` 构造器支持两种缓存写法：
+
+```javascript
+new Validator({ cache: true });   // 使用默认缓存配置
+new Validator({ cache: false });  // 关闭缓存
+
+new Validator({
+  cache: {
+	enabled: true,
+	maxSize: 500,
+	ttl: 60 * 60 * 1000
+  }
+});
+```
+
+> 如果你希望直接传入 DSL 对象（例如 `validate({ email: 'email!' }, data)`），请使用顶层便捷函数 `validate()` / `validateAsync()`；`Validator` 实例方法仍建议接收标准 JSON Schema 或 `dsl({...})` 的转换结果。
+
+相关方法：`compile()`、`validate()`、`validateAsync()`、`validateBatch()`、`addKeyword()`、`addFormat()`。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [validator.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/validator.ts)  
+**说明**: 覆盖 `new Validator()` 的常见配置、单次验证、编译缓存命中和 `validateBatch()` 复用路径。
+