schema-dsl 2.3.0 → 2.3.1

package/examples/schema-utils-chaining.examples.js

@@ -0,0 +1,250 @@
+/**
+ * SchemaUtils 核心方法示例
+ *
+ * 展示 v2.1.0 简化后的核心 4 个方法：
+ * 1. omit() - 排除字段
+ * 2. pick() - 保留字段
+ * 3. partial() - 部分验证
+ * 4. extend() - 扩展字段
+ *
+ * @version 2.1.0 (简化版)
+ * @date 2025-12-29
+ */
+
+const { dsl, validate, SchemaUtils } = require('../index');
+
+console.log('========================================');
+console.log('  SchemaUtils 核心方法示例');
+console.log('========================================\n');
+
+// ===== 定义基础 Schema =====
+
+const fullUserSchema = dsl({
+  id: 'objectId!',
+  name: 'string:1-50!',
+  email: 'email!',
+  password: 'string:8-32!',
+  age: 'integer:18-120',
+  role: 'admin|user|guest',
+  createdAt: 'date',
+  updatedAt: 'date'
+});
+
+console.log('基础 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('必填字段:', fullUserSchema.required);
+console.log('');
+
+// ===== 1. omit() - 排除字段 =====
+
+console.log('========== 1. omit() - 排除字段 ==========\n');
+
+const publicSchema = SchemaUtils.omit(fullUserSchema, ['password', 'createdAt', 'updatedAt']);
+
+console.log('原 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('omit 后字段:', Object.keys(publicSchema.properties));
+console.log('password 字段被移除:', publicSchema.properties.password === undefined);
+console.log('');
+
+// ===== 2. pick() - 保留字段 =====
+
+console.log('========== 2. pick() - 保留字段 ==========\n');
+
+const nameEmailSchema = SchemaUtils.pick(fullUserSchema, ['name', 'email']);
+
+console.log('原 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('pick 后字段:', Object.keys(nameEmailSchema.properties));
+console.log('只保留 name 和 email');
+console.log('');
+
+// ===== 3. partial() - 部分验证 =====
+
+console.log('========== 3. partial() - 部分验证 ==========\n');
+
+const partialSchema = SchemaUtils.partial(fullUserSchema);
+
+console.log('原 Schema 必填字段:', fullUserSchema.required);
+console.log('partial Schema 必填字段:', partialSchema.required);
+
+// 测试：缺少必填字段
+const result4 = validate(partialSchema, {
+  name: 'John'
+  // 缺少其他必填字段
+});
+
+console.log('\n验证结果（缺少必填字段）:');
+console.log('  valid:', result4.valid);
+if (result4.valid) {
+  console.log('  数据:', result4.data);
+}
+console.log('');
+
+// 部分验证 - 只验证指定字段
+const nameAgeSchema = SchemaUtils.partial(fullUserSchema, ['name', 'age']);
+
+console.log('partial(schema, [name, age]) 保留字段:', Object.keys(nameAgeSchema.properties));
+
+const result5 = validate(nameAgeSchema, {
+  name: 'John',
+  age: 30
+});
+
+console.log('验证结果（只验证 name 和 age）:');
+console.log('  valid:', result5.valid);
+console.log('');
+
+// ===== 4. extend() - 扩展字段 =====
+
+console.log('========== 4. extend() - 扩展字段 ==========\n');
+
+const extendedSchema = SchemaUtils.extend(fullUserSchema, {
+  avatar: 'url',
+  bio: 'string:0-500'
+});
+
+console.log('原 Schema 字段:', Object.keys(fullUserSchema.properties));
+console.log('extend 后字段:', Object.keys(extendedSchema.properties));
+console.log('新增字段: avatar, bio');
+console.log('');
+
+// ===== 5. 链式调用 =====
+
+console.log('========== 5. 链式调用 ==========\n');
+
+// 示例 1: omit
+console.log('示例 1: omit (创建用户 Schema)');
+const createSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+console.log('  字段:', Object.keys(createSchema.properties));
+console.log('');
+
+// 示例 2: pick + partial
+console.log('示例 2: pick + partial (更新用户 Schema)');
+const updateSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'age'])
+  .partial();
+
+console.log('  字段:', Object.keys(updateSchema.properties));
+console.log('  必填字段:', updateSchema.required);
+console.log('');
+
+// 示例 3: pick + extend (用户建议的常见场景)
+console.log('示例 3: pick + extend (自定义用户 Schema)');
+const customSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'email'])
+  .extend({ avatar: 'url', bio: 'string:0-500' });
+
+console.log('  字段:', Object.keys(customSchema.properties));
+console.log('');
+
+// 示例 4: omit + extend
+console.log('示例 4: omit + extend (增强用户 Schema)');
+const enhancedSchema = SchemaUtils
+  .omit(fullUserSchema, ['password'])
+  .extend({ avatar: 'url', bio: 'string:0-500' });
+
+console.log('  字段:', Object.keys(enhancedSchema.properties));
+console.log('  新增字段: avatar, bio');
+console.log('');
+
+// ===== 6. 实际 CRUD 场景 =====
+
+console.log('========== 6. 实际 CRUD 场景 ==========\n');
+
+console.log('场景 1: POST /users - 创建用户');
+const postSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+const postData = {
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'password123',
+  age: 30,
+  role: 'user'
+};
+
+const postResult = validate(postSchema, postData);
+console.log('  验证结果:', postResult.valid);
+console.log('  数据:', postResult.data);
+console.log('');
+
+console.log('场景 2: GET /users/:id - 查询用户');
+const getSchema = SchemaUtils.omit(fullUserSchema, ['password']);
+
+const userData = {
+  id: '507f1f77bcf86cd799439011',
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'password123',  // 已从 schema 移除，但验证时会被忽略
+  age: 30,
+  role: 'user',
+  createdAt: new Date(),
+  updatedAt: new Date()
+};
+
+const getResult = validate(getSchema, userData);
+console.log('  验证结果:', getResult.valid);
+console.log('  保留字段:', Object.keys(getResult.data));
+console.log('');
+
+console.log('场景 3: PATCH /users/:id - 部分更新用户');
+const patchSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'age'])
+  .partial();
+
+const patchData = {
+  name: 'John Updated'
+  // 只更新 name，age 缺失也可以
+};
+
+const patchResult = validate(patchSchema, patchData);
+console.log('  验证结果:', patchResult.valid);
+console.log('  数据:', patchResult.data);
+console.log('');
+
+console.log('场景 4: PUT /users/:id - 替换用户');
+const putSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+const putData = {
+  name: 'John Replaced',
+  email: 'john.new@example.com',
+  password: 'newpassword123',
+  age: 31,
+  role: 'admin'
+};
+
+const putResult = validate(putSchema, putData);
+console.log('  验证结果:', putResult.valid);
+console.log('  数据:', putResult.data);
+console.log('');
+
+// ===== 7. 不可变性验证 =====
+
+console.log('========== 7. 不可变性验证 ==========\n');
+
+const original = dsl({
+  name: 'string!',
+  email: 'email!'
+});
+
+const modified = SchemaUtils.omit(original, ['email']);
+
+console.log('原 Schema 字段:', Object.keys(original.properties));
+console.log('修改后 Schema 字段:', Object.keys(modified.properties));
+console.log('原 Schema 未被修改:', original.properties.email !== undefined);
+console.log('');
+
+console.log('========================================');
+console.log('  所有示例运行完成！');
+console.log('========================================\n');
+
+console.log('核心方法总结:');
+console.log('  1. omit() - 排除字段（50%场景）');
+console.log('  2. pick() - 保留字段（30%场景）');
+console.log('  3. partial() - 部分验证（25%场景）');
+console.log('  4. extend() - 扩展字段（15%场景）');
+console.log('');
+console.log('常见组合:');
+console.log('  - POST: omit(系统字段)');
+console.log('  - GET: omit(敏感字段)');
+console.log('  - PATCH: pick(可修改字段).partial()');
+console.log('  - 自定义: pick(基础字段).extend(新字段)');
+

package/examples/simple-example.js

@@ -69,7 +69,7 @@ console.log('✨ 5. Schema合并');
 const baseUser = dsl({ name: 'string!', email: 'email!' });
 const withAge = dsl({ age: 'number:18-120' });
 
-const fullUser = SchemaUtils.merge(baseUser, withAge);
+const fullUser = SchemaUtils.extend(baseUser, withAge);
 
 console.log('合并后字段:', Object.keys(fullUser.properties));
 console.log('');
@@ -114,7 +114,7 @@ console.log(`
    })
 
 3. 强大
-   SchemaUtils.merge()    // 灵活组合
+   SchemaUtils.extend()   // 扩展字段
    validateBatch()        // 快50倍
 
 🎉 简洁 + 直观 + 强大 = 完美验证库！

package/index.js

@@ -220,6 +220,12 @@ dsl.config = function(options = {}) {
 
 // ========== 导出 ==========
 
+// 导入 ValidationError
+const ValidationError = require('./lib/errors/ValidationError');
+
+// 导入 validateAsync
+const { validateAsync } = require('./lib/adapters/DslAdapter');
+
 module.exports = {
   // 统一DSL API
   dsl,
@@ -235,10 +241,14 @@ module.exports = {
 
   // 便捷方法（推荐）
   validate,                    // 便捷验证（单例）
+  validateAsync,               // v2.1.0 新增：异步验证
   getDefaultValidator,         // 获取单例Validator
   ErrorFormatter,
   CacheManager,
 
+  // 错误类 (v2.1.0 新增)
+  ValidationError,
+
   // 错误消息系统
   ErrorCodes,
   MessageTemplate,
@@ -266,5 +276,7 @@ module.exports = {
   CONSTANTS,
 
   // 版本信息
-  VERSION: '2.3.0'
+  VERSION: '2.1.0'
 };
+
+

package/lib/adapters/DslAdapter.js

@@ -646,8 +646,54 @@ function dsl(definition) {
   throw new Error('Invalid DSL definition: must be string or object');
 }
 
+/**
+ * 便捷验证函数（同步）
+ *
+ * @param {Object|DslBuilder} schema - JSON Schema或DslBuilder实例
+ * @param {*} data - 待验证数据
+ * @param {Object} options - 验证选项
+ * @returns {Object} 验证结果 { valid, errors, data }
+ *
+ * @example
+ * const result = validate(userSchema, inputData);
+ * if (!result.valid) {
+ *   console.error(result.errors);
+ * }
+ */
+function validate(schema, data, options = {}) {
+  const Validator = require('../core/Validator');
+  const validator = new Validator(options);
+  return validator.validate(schema, data, options);
+}
+
+/**
+ * 便捷异步验证函数
+ *
+ * @param {Object|DslBuilder} schema - JSON Schema或DslBuilder实例
+ * @param {*} data - 待验证数据
+ * @param {Object} options - 验证选项
+ * @returns {Promise<*>} 验证通过返回数据
+ * @throws {ValidationError} 验证失败抛出异常
+ *
+ * @example
+ * try {
+ *   const data = await validateAsync(userSchema, inputData);
+ *   console.log('验证通过:', data);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('验证失败:', error.errors);
+ *   }
+ * }
+ */
+async function validateAsync(schema, data, options = {}) {
+  const Validator = require('../core/Validator');
+  const validator = new Validator(options);
+  return validator.validateAsync(schema, data, options);
+}
+
 // 导出
 module.exports = dsl;
 module.exports.DslAdapter = DslAdapter;
 module.exports.DslBuilder = DslBuilder;
-
+module.exports.validate = validate;
+module.exports.validateAsync = validateAsync;

package/lib/core/Validator.js

@@ -116,6 +116,21 @@ class Validator {
       schema = schema.toSchema();
     }
 
+    // 检查是否需要移除额外字段 (clean 模式)
+    if (schema && schema._removeAdditional) {
+      // 创建新的 Validator 实例，启用 removeAdditional
+      const tempValidator = new Validator({
+        ...this.ajvOptions,
+        removeAdditional: true
+      });
+
+      // 移除标记字段并深拷贝，避免修改原 schema
+      const cleanSchema = JSON.parse(JSON.stringify(schema));
+      delete cleanSchema._removeAdditional;
+
+      return tempValidator.validate(cleanSchema, data, options);
+    }
+
     try {
       // 如果schema是函数，说明已编译
       let validate;
@@ -174,6 +189,51 @@ class Validator {
     }
   }
 
+  /**
+   * 异步验证方法（验证失败自动抛出异常）
+   *
+   * @param {Object|Function} schema - JSON Schema对象或DslBuilder实例
+   * @param {*} data - 待验证的数据
+   * @param {Object} options - 验证选项（可选）
+   * @param {boolean} options.format - 是否格式化错误（默认true）
+   * @param {string} options.locale - 语言环境（如 'zh-CN', 'en-US'）
+   * @returns {Promise<*>} 验证通过返回处理后的数据
+   * @throws {ValidationError} 验证失败抛出异常
+   *
+   * @example
+   * // 基础使用
+   * try {
+   *   const data = await validator.validateAsync(userSchema, inputData);
+   *   console.log('验证通过:', data);
+   * } catch (error) {
+   *   if (error instanceof ValidationError) {
+   *     console.error('验证失败:', error.errors);
+   *   }
+   * }
+   *
+   * @example
+   * // Express 中使用
+   * app.post('/users', async (req, res, next) => {
+   *   try {
+   *     const data = await validator.validateAsync(userSchema, req.body);
+   *     const user = await db.users.insert(data);
+   *     res.json(user);
+   *   } catch (error) {
+   *     next(error);
+   *   }
+   * });
+   */
+  async validateAsync(schema, data, options = {}) {
+    const result = this.validate(schema, data, options);
+
+    if (!result.valid) {
+      const ValidationError = require('../errors/ValidationError');
+      throw new ValidationError(result.errors, data);
+    }
+
+    return result.data;
+  }
+
   /**
    * 批量验证
    * @param {Object} schema - JSON Schema对象

package/lib/errors/ValidationError.js

@@ -0,0 +1,191 @@
+/**
+ * ValidationError - 验证错误类
+ *
+ * 用于 validateAsync() 方法，验证失败时自动抛出
+ *
+ * @module lib/errors/ValidationError
+ * @version 2.1.0
+ */
+
+/**
+ * 验证错误类
+ *
+ * @class ValidationError
+ * @extends Error
+ *
+ * @property {string} name - 错误名称（固定为 'ValidationError'）
+ * @property {string} message - 错误消息（所有错误的汇总）
+ * @property {Array<Object>} errors - 详细错误列表
+ * @property {*} data - 原始验证数据
+ * @property {number} statusCode - HTTP 状态码（默认 400）
+ *
+ * @example
+ * // 创建错误
+ * const errors = [
+ *   { path: '/name', message: '字段必填', keyword: 'required' }
+ * ];
+ * const error = new ValidationError(errors, inputData);
+ *
+ * @example
+ * // 在 Express 中使用
+ * app.use((error, req, res, next) => {
+ *   if (error instanceof ValidationError) {
+ *     return res.status(error.statusCode).json(error.toJSON());
+ *   }
+ *   next(error);
+ * });
+ */
+class ValidationError extends Error {
+  /**
+   * 构造函数
+   * @param {Array<Object>} errors - 错误列表
+   * @param {string} errors[].path - 字段路径（如 '/name'）
+   * @param {string} errors[].message - 错误消息
+   * @param {string} errors[].keyword - 验证关键字（如 'required', 'format'）
+   * @param {Object} errors[].params - 错误参数
+   * @param {*} data - 原始数据
+   */
+  constructor(errors, data) {
+    // 生成友好的错误消息
+    const messages = errors.map(e => {
+      if (e.path) {
+        const field = e.path.replace(/^\//, '');
+        // 只有字段名非空时才添加前缀
+        return field ? `${field}: ${e.message}` : e.message;
+      }
+      return e.message;
+    }).join('; ');
+
+    // 检查是否所有错误都完全没有 path 属性（而不是空路径）
+    const hasNoPath = errors.every(e => e.path === undefined || e.path === null);
+
+    // 如果都是无 path 属性的错误，使用简单格式；否则使用标准格式
+    super(hasNoPath ? `Validation failed - ${messages}` : `Validation failed: ${messages}`);
+
+    this.name = 'ValidationError';
+    this.errors = errors;
+    this.data = data;
+    this.statusCode = 400;
+
+    // 保持堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationError);
+    }
+  }
+
+  /**
+   * 转换为 JSON 格式（用于 API 响应）
+   *
+   * @returns {Object} JSON 对象
+   * @returns {string} return.error - 错误名称
+   * @returns {string} return.message - 错误消息
+   * @returns {number} return.statusCode - 状态码
+   * @returns {Array<Object>} return.details - 详细错误列表
+   *
+   * @example
+   * const json = error.toJSON();
+   * res.status(400).json(json);
+   * // {
+   * //   error: 'ValidationError',
+   * //   message: 'Validation failed: name: 字段必填',
+   * //   statusCode: 400,
+   * //   details: [...]
+   * // }
+   */
+  toJSON() {
+    return {
+      error: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.errors.map(e => ({
+        field: e.path ? e.path.replace(/^\//, '') : null,
+        message: e.message,
+        keyword: e.keyword,
+        params: e.params
+      }))
+    };
+  }
+
+  /**
+   * 获取指定字段的错误
+   *
+   * @param {string} field - 字段名称（如 'name' 或 '/name'）
+   * @returns {Object|null} 错误对象或 null
+   *
+   * @example
+   * const nameError = error.getFieldError('name');
+   * if (nameError) {
+   *   console.log('姓名错误:', nameError.message);
+   * }
+   */
+  getFieldError(field) {
+     // 规范化字段名（移除前导斜杠）
+    const normalizedField = field.replace(/^\//, '');
+
+    // 查找匹配的错误（支持多种路径格式）
+    return this.errors.find(e => {
+      if (!e.path) return false;
+      const errorField = e.path.replace(/^\//, '');
+      return errorField === normalizedField;
+    }) || null;
+  }
+
+  /**
+   * 获取所有字段的错误映射
+   *
+   * @returns {Object} 字段错误映射 { fieldName: errorMessage }
+   *
+   * @example
+   * const fieldErrors = error.getFieldErrors();
+   * // { name: '字段必填', email: '邮箱格式错误' }
+   */
+  getFieldErrors() {
+    const result = {};
+    this.errors.forEach(e => {
+      if (e.path) {
+        const field = e.path.replace(/^\//, '');
+        if (field) {
+          result[field] = e.message;
+        }
+      }
+    });
+    return result;
+  }
+
+  /**
+   * 检查是否包含指定字段的错误
+   *
+   * @param {string} field - 字段名称
+   * @returns {boolean} 是否包含错误
+   *
+   * @example
+   * if (error.hasFieldError('name')) {
+   *   console.log('姓名字段有错误');
+   * }
+   */
+  hasFieldError(field) {
+    return this.getFieldError(field) !== null;
+  }
+
+  /**
+   * 获取错误数量
+   *
+   * @returns {number} 错误数量
+   *
+   * @example
+   * console.log(`共 ${error.getErrorCount()} 个错误`);
+   */
+  getErrorCount() {
+    return this.errors.length;
+  }
+}
+
+// Support calling without new
+const ValidationErrorProxy = new Proxy(ValidationError, {
+  apply: function(target, thisArg, argumentsList) {
+    return new target(...argumentsList);
+  }
+});
+
+module.exports = ValidationErrorProxy;
+