@dangao/bun-server 1.7.0 → 1.8.0

package/src/validation/class-validator.ts

@@ -0,0 +1,322 @@
+import 'reflect-metadata';
+import type { ValidationRuleDefinition, ClassValidationMetadata, ValidationOptions } from './types';
+import { ValidationError, type ValidationIssue } from './errors';
+
+const CLASS_VALIDATION_METADATA_KEY = Symbol('validation:class');
+const PROPERTY_VALIDATION_METADATA_KEY = Symbol('validation:property');
+const VALIDATE_CLASS_METADATA_KEY = Symbol('validation:validateClass');
+
+/**
+ * 标记类需要验证
+ * 应用此装饰器后，类的实例可以使用 validateObject 函数进行验证
+ */
+export function ValidateClass(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(VALIDATE_CLASS_METADATA_KEY, true, target);
+  };
+}
+
+/**
+ * 属性验证装饰器
+ * 用于 DTO 类的属性级别验证
+ *
+ * @example
+ * @ValidateClass()
+ * class CreateUserDto {
+ *   @Property(IsString(), MinLength(2))
+ *   name: string;
+ *
+ *   @Property(IsEmail())
+ *   email: string;
+ *
+ *   @Property(IsOptional(), IsNumber())
+ *   age?: number;
+ * }
+ */
+export function Property(...rules: ValidationRuleDefinition[]): PropertyDecorator {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'symbol') {
+      throw new Error('@Property decorator does not support symbol property keys');
+    }
+
+    // 获取或创建类级别的元数据数组
+    const existingMetadata: ClassValidationMetadata[] =
+      Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target.constructor) ?? [];
+
+    // 查找现有的属性元数据
+    let propertyMetadata = existingMetadata.find((m) => m.property === propertyKey);
+    if (!propertyMetadata) {
+      propertyMetadata = { property: propertyKey, rules: [] };
+      existingMetadata.push(propertyMetadata);
+    }
+
+    // 添加规则
+    propertyMetadata.rules.push(...rules);
+
+    // 保存元数据
+    Reflect.defineMetadata(CLASS_VALIDATION_METADATA_KEY, existingMetadata, target.constructor);
+  };
+}
+
+/**
+ * 获取类的验证元数据
+ */
+export function getClassValidationMetadata(target: new () => unknown): ClassValidationMetadata[] {
+  return Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target) ?? [];
+}
+
+/**
+ * 检查类是否标记为需要验证
+ */
+export function isValidateClass(target: new () => unknown): boolean {
+  return Reflect.getMetadata(VALIDATE_CLASS_METADATA_KEY, target) === true;
+}
+
+/**
+ * 验证单个值
+ */
+function validateValue(
+  value: unknown,
+  rules: ValidationRuleDefinition[],
+  property: string,
+  fullObject: unknown,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  let currentValue = value;
+  let shouldSkip = false;
+
+  for (const rule of rules) {
+    // 处理条件验证
+    if (rule.condition && !rule.condition(currentValue, fullObject)) {
+      shouldSkip = true;
+      break;
+    }
+
+    // 处理可选字段
+    if (rule.optional && (currentValue === undefined || currentValue === null)) {
+      shouldSkip = true;
+      break;
+    }
+
+    // 处理转换
+    if (rule.transform) {
+      currentValue = rule.transform(currentValue);
+    }
+
+    // 处理嵌套验证
+    if (rule.nested) {
+      if (rule.each && Array.isArray(currentValue)) {
+        // 数组嵌套验证
+        for (let i = 0; i < currentValue.length; i++) {
+          const item = currentValue[i];
+          if (typeof item === 'object' && item !== null && rule.nestedType) {
+            const nestedIssues = validateObjectInternal(item, rule.nestedType, `${property}[${i}]`);
+            issues.push(...nestedIssues);
+          }
+        }
+      } else if (typeof currentValue === 'object' && currentValue !== null && rule.nestedType) {
+        // 单个对象嵌套验证
+        const nestedIssues = validateObjectInternal(currentValue, rule.nestedType, property);
+        issues.push(...nestedIssues);
+      }
+      continue;
+    }
+
+    // 执行验证
+    const passed = rule.validate(currentValue, fullObject);
+    if (!passed) {
+      issues.push({
+        property,
+        rule: rule.name,
+        message: rule.message,
+        value: currentValue,
+      });
+    }
+  }
+
+  return shouldSkip ? [] : issues;
+}
+
+/**
+ * 内部验证函数
+ */
+function validateObjectInternal(
+  obj: unknown,
+  targetClass: new () => unknown,
+  prefix = '',
+): ValidationIssue[] {
+  const metadata = getClassValidationMetadata(targetClass);
+  const issues: ValidationIssue[] = [];
+
+  if (typeof obj !== 'object' || obj === null) {
+    issues.push({
+      property: prefix || 'root',
+      rule: 'isObject',
+      message: '必须是对象',
+      value: obj,
+    });
+    return issues;
+  }
+
+  const objRecord = obj as Record<string, unknown>;
+
+  for (const meta of metadata) {
+    const propertyPath = prefix ? `${prefix}.${meta.property}` : meta.property;
+    const value = objRecord[meta.property];
+    const propertyIssues = validateValue(value, meta.rules, propertyPath, obj);
+    issues.push(...propertyIssues);
+  }
+
+  return issues;
+}
+
+/**
+ * 验证对象
+ *
+ * @param obj - 要验证的对象
+ * @param targetClass - DTO 类
+ * @param options - 验证选项
+ * @throws {ValidationError} 验证失败时抛出
+ *
+ * @example
+ * @ValidateClass()
+ * class CreateUserDto {
+ *   @Property(IsString(), MinLength(2))
+ *   name: string;
+ *
+ *   @Property(IsEmail())
+ *   email: string;
+ * }
+ *
+ * const dto = { name: 'A', email: 'invalid' };
+ * validateObject(dto, CreateUserDto); // throws ValidationError
+ */
+export function validateObject<T>(
+  obj: unknown,
+  targetClass: new () => T,
+  options: ValidationOptions = {},
+): void {
+  const issues = validateObjectInternal(obj, targetClass);
+
+  if (options.stopAtFirstError && issues.length > 0) {
+    throw new ValidationError('Validation failed', [issues[0]]);
+  }
+
+  if (issues.length > 0) {
+    throw new ValidationError('Validation failed', issues);
+  }
+}
+
+/**
+ * 验证对象并返回验证结果（不抛出异常）
+ *
+ * @param obj - 要验证的对象
+ * @param targetClass - DTO 类
+ * @param options - 验证选项
+ * @returns 验证结果
+ */
+export function validateObjectSync<T>(
+  obj: unknown,
+  targetClass: new () => T,
+  options: ValidationOptions = {},
+): { valid: boolean; issues: ValidationIssue[] } {
+  const issues = validateObjectInternal(obj, targetClass);
+
+  if (options.stopAtFirstError && issues.length > 0) {
+    return { valid: false, issues: [issues[0]] };
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+/**
+ * 带嵌套类型的属性验证装饰器
+ * 用于嵌套对象验证
+ *
+ * @example
+ * @ValidateClass()
+ * class AddressDto {
+ *   @Property(IsString())
+ *   city: string;
+ * }
+ *
+ * @ValidateClass()
+ * class CreateUserDto {
+ *   @Property(IsString())
+ *   name: string;
+ *
+ *   @NestedProperty(AddressDto)
+ *   address: AddressDto;
+ * }
+ */
+export function NestedProperty<T>(nestedClass: new () => T): PropertyDecorator {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'symbol') {
+      throw new Error('@NestedProperty decorator does not support symbol property keys');
+    }
+
+    const existingMetadata: ClassValidationMetadata[] =
+      Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target.constructor) ?? [];
+
+    let propertyMetadata = existingMetadata.find((m) => m.property === propertyKey);
+    if (!propertyMetadata) {
+      propertyMetadata = { property: propertyKey, rules: [] };
+      existingMetadata.push(propertyMetadata);
+    }
+
+    propertyMetadata.rules.push({
+      name: 'validateNested',
+      message: '嵌套对象验证失败',
+      nested: true,
+      nestedType: nestedClass,
+      validate: (value) => typeof value === 'object' && value !== null && !Array.isArray(value),
+    });
+
+    Reflect.defineMetadata(CLASS_VALIDATION_METADATA_KEY, existingMetadata, target.constructor);
+  };
+}
+
+/**
+ * 数组嵌套属性验证装饰器
+ * 用于数组中每个元素的验证
+ *
+ * @example
+ * @ValidateClass()
+ * class ItemDto {
+ *   @Property(IsString())
+ *   name: string;
+ * }
+ *
+ * @ValidateClass()
+ * class OrderDto {
+ *   @ArrayNestedProperty(ItemDto)
+ *   items: ItemDto[];
+ * }
+ */
+export function ArrayNestedProperty<T>(nestedClass: new () => T): PropertyDecorator {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'symbol') {
+      throw new Error('@ArrayNestedProperty decorator does not support symbol property keys');
+    }
+
+    const existingMetadata: ClassValidationMetadata[] =
+      Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target.constructor) ?? [];
+
+    let propertyMetadata = existingMetadata.find((m) => m.property === propertyKey);
+    if (!propertyMetadata) {
+      propertyMetadata = { property: propertyKey, rules: [] };
+      existingMetadata.push(propertyMetadata);
+    }
+
+    propertyMetadata.rules.push({
+      name: 'validateNestedArray',
+      message: '数组元素验证失败',
+      nested: true,
+      nestedType: nestedClass,
+      each: true,
+      validate: (value) => Array.isArray(value),
+    });
+
+    Reflect.defineMetadata(CLASS_VALIDATION_METADATA_KEY, existingMetadata, target.constructor);
+  };
+}

package/src/validation/custom-validator.ts

@@ -0,0 +1,289 @@
+import type { ValidationRuleDefinition } from './types';
+
+export interface CustomValidatorOptions {
+  message?: string;
+}
+
+/**
+ * 创建自定义验证器
+ *
+ * @param name - 验证器名称
+ * @param validate - 验证函数，接收值和可选参数，返回布尔值
+ * @param defaultMessage - 默认错误消息
+ * @returns 验证规则工厂函数
+ *
+ * @example
+ * // 创建手机号验证器
+ * const IsPhoneNumber = createCustomValidator(
+ *   'isPhoneNumber',
+ *   (value) => typeof value === 'string' && /^1[3-9]\d{9}$/.test(value),
+ *   '必须是有效的手机号码'
+ * );
+ *
+ * // 使用
+ * class UserDto {
+ *   @Validate(IsPhoneNumber())
+ *   phone: string;
+ * }
+ *
+ * @example
+ * // 创建带参数的验证器
+ * const IsDivisibleBy = createCustomValidator(
+ *   'isDivisibleBy',
+ *   (value, divisor: number) => typeof value === 'number' && value % divisor === 0,
+ *   (divisor: number) => `必须能被 ${divisor} 整除`
+ * );
+ *
+ * // 使用
+ * class NumberDto {
+ *   @Validate(IsDivisibleBy(5))
+ *   value: number;
+ * }
+ */
+export function createCustomValidator<TArgs extends unknown[] = []>(
+  name: string,
+  validate: (value: unknown, ...args: TArgs) => boolean,
+  defaultMessage: string | ((...args: TArgs) => string),
+): (...args: TArgs) => (options?: CustomValidatorOptions) => ValidationRuleDefinition {
+  return (...args: TArgs) =>
+    (options: CustomValidatorOptions = {}): ValidationRuleDefinition => {
+      const message =
+        options.message ??
+        (typeof defaultMessage === 'function' ? defaultMessage(...args) : defaultMessage);
+
+      return {
+        name,
+        message,
+        validate: (value: unknown) => validate(value, ...args),
+      };
+    };
+}
+
+/**
+ * 创建简单自定义验证器（无参数）
+ *
+ * @param name - 验证器名称
+ * @param validate - 验证函数
+ * @param defaultMessage - 默认错误消息
+ * @returns 验证规则工厂函数
+ *
+ * @example
+ * const IsPhoneNumber = createSimpleValidator(
+ *   'isPhoneNumber',
+ *   (value) => typeof value === 'string' && /^1[3-9]\d{9}$/.test(value),
+ *   '必须是有效的手机号码'
+ * );
+ *
+ * // 使用
+ * @Validate(IsPhoneNumber())
+ * phone: string;
+ */
+export function createSimpleValidator(
+  name: string,
+  validate: (value: unknown) => boolean,
+  defaultMessage: string,
+): (options?: CustomValidatorOptions) => ValidationRuleDefinition {
+  return (options: CustomValidatorOptions = {}): ValidationRuleDefinition => ({
+    name,
+    message: options.message ?? defaultMessage,
+    validate,
+  });
+}
+
+/**
+ * 创建正则表达式验证器
+ *
+ * @param name - 验证器名称
+ * @param pattern - 正则表达式
+ * @param defaultMessage - 默认错误消息
+ * @returns 验证规则工厂函数
+ *
+ * @example
+ * const IsSlug = createRegexValidator(
+ *   'isSlug',
+ *   /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+ *   '必须是有效的 slug 格式'
+ * );
+ */
+export function createRegexValidator(
+  name: string,
+  pattern: RegExp,
+  defaultMessage: string,
+): (options?: CustomValidatorOptions) => ValidationRuleDefinition {
+  return createSimpleValidator(
+    name,
+    (value) => typeof value === 'string' && pattern.test(value),
+    defaultMessage,
+  );
+}
+
+// ============= 内置扩展验证器 =============
+
+/**
+ * 验证中国大陆手机号
+ */
+export const IsPhoneNumber = createSimpleValidator(
+  'isPhoneNumber',
+  (value) => typeof value === 'string' && /^1[3-9]\d{9}$/.test(value),
+  '必须是有效的手机号码',
+);
+
+/**
+ * 验证中国身份证号
+ */
+export const IsIdCard = createSimpleValidator(
+  'isIdCard',
+  (value) => {
+    if (typeof value !== 'string') return false;
+    // 15位身份证：6位地区码 + 6位出生日期(YYMMDD) + 3位顺序码
+    const pattern15 = /^[1-9]\d{5}\d{2}((0[1-9])|(1[0-2]))(([0-2]\d)|30|31)\d{3}$/;
+    // 18位身份证：6位地区码 + 8位出生日期(YYYYMMDD) + 3位顺序码 + 1位校验码
+    const pattern18 = /^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2]\d)|30|31)\d{3}[0-9Xx]$/;
+    return pattern15.test(value) || pattern18.test(value);
+  },
+  '必须是有效的身份证号码',
+);
+
+/**
+ * 验证 IP 地址 (IPv4)
+ */
+export const IsIPv4 = createSimpleValidator(
+  'isIPv4',
+  (value) => {
+    if (typeof value !== 'string') return false;
+    const parts = value.split('.');
+    if (parts.length !== 4) return false;
+    return parts.every((part) => {
+      const num = parseInt(part, 10);
+      return !Number.isNaN(num) && num >= 0 && num <= 255 && String(num) === part;
+    });
+  },
+  '必须是有效的 IPv4 地址',
+);
+
+/**
+ * 验证端口号
+ */
+export const IsPort = createSimpleValidator(
+  'isPort',
+  (value) => {
+    if (typeof value === 'string') {
+      const num = parseInt(value, 10);
+      return !Number.isNaN(num) && num >= 0 && num <= 65535;
+    }
+    if (typeof value === 'number') {
+      return Number.isInteger(value) && value >= 0 && value <= 65535;
+    }
+    return false;
+  },
+  '必须是有效的端口号 (0-65535)',
+);
+
+/**
+ * 验证邮政编码（中国）
+ */
+export const IsPostalCode = createSimpleValidator(
+  'isPostalCode',
+  (value) => typeof value === 'string' && /^[1-9]\d{5}$/.test(value),
+  '必须是有效的邮政编码',
+);
+
+/**
+ * 验证信用卡号（Luhn 算法）
+ */
+export const IsCreditCard = createSimpleValidator(
+  'isCreditCard',
+  (value) => {
+    if (typeof value !== 'string') return false;
+    const sanitized = value.replace(/[\s-]/g, '');
+    if (!/^\d{13,19}$/.test(sanitized)) return false;
+
+    // Luhn 算法
+    let sum = 0;
+    let isEven = false;
+    for (let i = sanitized.length - 1; i >= 0; i--) {
+      let digit = parseInt(sanitized[i], 10);
+      if (isEven) {
+        digit *= 2;
+        if (digit > 9) digit -= 9;
+      }
+      sum += digit;
+      isEven = !isEven;
+    }
+    return sum % 10 === 0;
+  },
+  '必须是有效的信用卡号',
+);
+
+/**
+ * 验证十六进制颜色值
+ */
+export const IsHexColor = createSimpleValidator(
+  'isHexColor',
+  (value) => typeof value === 'string' && /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(value),
+  '必须是有效的十六进制颜色值',
+);
+
+/**
+ * 验证 MAC 地址
+ */
+export const IsMacAddress = createSimpleValidator(
+  'isMacAddress',
+  (value) =>
+    typeof value === 'string' &&
+    /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/.test(value),
+  '必须是有效的 MAC 地址',
+);
+
+/**
+ * 验证语义化版本号
+ */
+export const IsSemVer = createSimpleValidator(
+  'isSemVer',
+  (value) =>
+    typeof value === 'string' &&
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/.test(
+      value,
+    ),
+  '必须是有效的语义化版本号',
+);
+
+/**
+ * 创建能被指定数字整除的验证器
+ */
+export const IsDivisibleBy = createCustomValidator(
+  'isDivisibleBy',
+  (value: unknown, divisor: number) =>
+    typeof value === 'number' && !Number.isNaN(value) && value % divisor === 0,
+  (divisor: number) => `必须能被 ${divisor} 整除`,
+);
+
+/**
+ * 创建范围验证器
+ */
+export const IsBetween = createCustomValidator(
+  'isBetween',
+  (value: unknown, min: number, max: number) =>
+    typeof value === 'number' && value >= min && value <= max,
+  (min: number, max: number) => `必须在 ${min} 和 ${max} 之间`,
+);
+
+/**
+ * 验证是否包含指定子字符串
+ */
+export const Contains = createCustomValidator(
+  'contains',
+  (value: unknown, substring: string) =>
+    typeof value === 'string' && value.includes(substring),
+  (substring: string) => `必须包含 "${substring}"`,
+);
+
+/**
+ * 验证是否不包含指定子字符串
+ */
+export const NotContains = createCustomValidator(
+  'notContains',
+  (value: unknown, substring: string) =>
+    typeof value === 'string' && !value.includes(substring),
+  (substring: string) => `不能包含 "${substring}"`,
+);

package/src/validation/errors.ts

@@ -1,8 +1,13 @@
 export interface ValidationIssue {
   /**
-   * 参数索引
+   * 参数索引（参数级别验证使用）
    */
-  index: number;
+  index?: number;
+
+  /**
+   * 属性路径（类级别验证使用，支持嵌套如 'user.address.city'）
+   */
+  property?: string;
 
   /**
    * 失败的规则名称
@@ -13,6 +18,16 @@ export interface ValidationIssue {
    * 错误信息
    */
   message: string;
+
+  /**
+   * 验证失败的值
+   */
+  value?: unknown;
+
+  /**
+   * 嵌套错误（用于嵌套对象验证）
+   */
+  children?: ValidationIssue[];
 }
 
 export class ValidationError extends Error {
@@ -23,6 +38,39 @@ export class ValidationError extends Error {
     this.name = 'ValidationError';
     this.issues = issues;
   }
+
+  /**
+   * 获取所有错误的扁平化列表
+   */
+  public getFlattened(): ValidationIssue[] {
+    const flatten = (issues: ValidationIssue[], prefix = ''): ValidationIssue[] => {
+      const result: ValidationIssue[] = [];
+      for (const issue of issues) {
+        const propertyPath = prefix ? `${prefix}.${issue.property ?? ''}` : (issue.property ?? '');
+        if (issue.children && issue.children.length > 0) {
+          result.push(...flatten(issue.children, propertyPath));
+        } else {
+          result.push({
+            ...issue,
+            property: propertyPath || undefined,
+          });
+        }
+      }
+      return result;
+    };
+    return flatten(this.issues);
+  }
+
+  /**
+   * 转换为简单的错误对象
+   */
+  public toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      issues: this.issues,
+    };
+  }
 }