enhanced-validator v1.0.0

Enhanced Validator 技術文件

概述

EnhancedValidator 是一個基於 TypeScript 的驗證函式庫，提供全面的物件資料結構驗證功能。它支援巢狀物件驗證、自訂驗證規則、資料轉換，以及彈性的驗證模式。

主要特色

• 基於 TypeScript 的型別安全驗證
• 使用點記法的巢狀物件驗證
• 可擴展的驗證規則
• 自訂驗證函式
• 資料轉換功能
• 多種驗證模式（快速失敗或全部驗證）
• 豐富的內建驗證器
• 詳細的錯誤報告

基本使用方法

// 定義資料結構
interface UserData {
  username: string;
  email: string;
  profile: {
    age: number;
    birthDate: string;
  };
}

// 建立驗證器實例
const validator = new EnhancedValidator<UserData>();

// 設定驗證規則
validator
  .field('username')
    .isRequired('使用者名稱為必填')
    .isString('使用者名稱必須是字串')
    .matches(/^[a-zA-Z0-9_]{3,20}$/, '使用者名稱格式不正確')
  .field('email')
    .isRequired('電子郵件為必填')
    .matches(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/, '電子郵件格式不正確')
  .field('profile.age')
    .isNumber('年齡必須是數字')
    .isPositive('年齡必須是正數')
  .field('profile.birthDate')
    .isPastDate('生日必須是過去的日期');

// 驗證資料
const data = {
  username: 'john_doe',
  email: 'john@example.com',
  profile: {
    age: 25,
    birthDate: '1998-01-01'
  }
};

const result = await validator.validate(data);

驗證方法

基本驗證

• isRequired(): 檢查欄位是否存在且不為空
• notEmpty(): 檢查字串是否不為空
• isString(): 檢查是否為字串
• isNumber(): 檢查是否為數字
• isBoolean(): 檢查是否為布林值

日期相關驗證

• isFutureDate(): 檢查是否為未來日期
• isPastDate(): 檢查是否為過去日期
• isWeekday(): 檢查是否為平日
• isWeekend(): 檢查是否為週末

字串相關驗證

• containsLowercase(): 包含小寫字母
• containsUppercase(): 包含大寫字母
• containsNumber(): 包含數字
• containsSpecialChar(): 包含特殊字元
• isAlphanumeric(): 僅包含字母和數字
• isNumericString(): 純數字字串
• isSlug(): 符合 slug 格式

檔案相關驗證

• isValidFileExtension(): 檢查檔案副檔名

數字相關驗證

• isPositive(): 檢查是否為正數
• isNegative(): 檢查是否為負數

其他驗證

• isBase64(): 檢查是否為有效的 Base64 字串
• matches(): 使用正則表達式驗證
• custom(): 自訂驗證函式

驗證結果格式

interface ValidationResult<T> {
  success: boolean;        // 驗證是否成功
  data?: T;               // 轉換後的資料（僅在成功時存在）
  errors: ValidationError[]; // 所有錯誤列表
  fieldErrors: {          // 依欄位分類的錯誤
    [K in keyof T]?: ValidationError[];
  };
}

interface ValidationError {
  field: string;          // 錯誤欄位
  message: string;        // 錯誤訊息
  code?: string;          // 錯誤代碼
  params?: Record<string, unknown>; // 額外參數
}

進階功能

驗證模式設定

// 設定快速失敗模式（遇到第一個錯誤就停止）
validator.setValidationMode('fail-fast');

// 設定全部驗證模式（檢查所有欄位）
validator.setValidationMode('all');

資料轉換

validator
  .field('age')
    .isString()
    .transform(value => parseInt(value as string))
    .isPositive();

自訂驗證

validator
  .field('password')
    .custom(
      value => {
        const pwd = value as string;
        return pwd.length >= 8 && /[A-Z]/.test(pwd);
      },
      '密碼必須至少8個字元且包含大寫字母'
    );

最佳實踐

1. 使用 TypeScript 介面定義資料結構
2. 針對每個欄位提供清晰的錯誤訊息
3. 適當使用驗證模式
4. 善用巢狀物件驗證功能
5. 需要時使用資料轉換功能
6. 為複雜驗證邏輯建立自訂驗證函式

錯誤處理

const result = await validator.validate(data);
if (!result.success) {
  // 處理整體錯誤
  console.log('驗證錯誤：', result.errors);

  // 處理特定欄位錯誤
  if (result.fieldErrors.username) {
    console.log('使用者名稱錯誤：', result.fieldErrors.username);
  }
}