TypeStack/class-validator في TypeScript: دليل شامل مع أمثلة

1. ما هي هذه المكتبة ولماذا نحتاجها؟

مكتبة TypeStack/class-validator هي أداة قوية للتحقق من صحة البيانات (Validation) في TypeScript و JavaScript، تعتمد على الـ Decorators. تتيح هذه المكتبة للمطورين كتابة قواعد التحقق مباشرة داخل الكلاسات (Classes) باستخدام Decorators الخصائص. هذا يجعل الكود أكثر قابلية للقراءة، ويوثق نفسه بنفسه، ويبسط بشكل كبير معالجة البيانات الواردة، خاصة عند العمل مع REST API أو النماذج أو أي مصادر بيانات أخرى.

لماذا نحتاجها؟ في تطوير الويب الحديث، تأتي البيانات من مصادر متعددة: طلبات HTTP، ملفات الإعدادات، قواعد البيانات. بدون التحقق الموثوق، قد تؤدي هذه البيانات إلى أخطاء وقت التشغيل، ثغرات أمنية، أو ببساطة إلى عمل غير صحيح للتطبيق. تحل class-validator هذه المشكلة من خلال توفير طريقة تعريفية (Declarative) للتحقق من البيانات. بدلاً من كتابة جمل if-else الطويلة، يمكنك ببساطة إضافة Decorators إلى خصائص الكلاس، وستقوم المكتبة تلقائياً بالتحقق من مطابقتها للقواعد المحددة.

ميزة رئيسية أخرى هي التكامل الوثيق مع TypeScript. تتيح الـ Decorators ليس فقط التحقق من البيانات، بل أيضاً تحديد أنواعها، مما يجعل عملية التطوير أكثر أماناً وقابلية للتنبؤ. تدعم المكتبة مجموعة واسعة من أدوات التحقق المدمجة (من فحوصات بسيطة لطول النص إلى تعبيرات منتظمة معقدة) وتسمح بإنشاء أدوات تحقق مخصصة بسهولة.

2. التثبيت

لتثبيت مكتبة class-validator والتبعية الإلزامية لها reflect-metadata، قم بتنفيذ الأمر التالي في terminal مشروعك:

npm install class-validator reflect-metadata

بعد التثبيت، تأكد من تفعيل الخيارات التالية في ملف tsconfig.json لضمان عمل الـ Decorators بشكل صحيح:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

من المهم أيضاً استيراد reflect-metadata في بداية تطبيقك (عادةً في الملف الرئيسي index.ts أو app.ts):

import "reflect-metadata";

3. البداية السريعة

لنلقِ نظرة على مثال عملي بسيط. سننشئ كلاس مستخدم مع التحقق من صحة الحقول:

import "reflect-metadata";
import { validate, IsString, IsEmail, MinLength } from "class-validator";

class User {
    @IsString()
    @MinLength(3, { message: "الاسم يجب أن يحتوي على 3 أحرف على الأقل" })
    name: string;

    @IsEmail({}, { message: "البريد الإلكتروني غير صحيح" })
    email: string;

    constructor(name: string, email: string) {
        this.name = name;
        this.email = email;
    }
}

async function main() {
    const user = new User("Jo", "invalid-email");
    const errors = await validate(user);

    if (errors.length > 0) {
        console.log("أخطاء التحقق:");
        errors.forEach(error => {
            console.log(`- ${error.property}: ${Object.values(error.constraints).join(", ")}`);
        });
    } else {
        console.log("تم التحقق بنجاح!");
    }
}

main();
// المخرجات:
// أخطاء التحقق:
// - name: الاسم يجب أن يحتوي على 3 أحرف على الأقل
// - email: البريد الإلكتروني غير صحيح

في هذا المثال، أنشأنا كلاس User، وأضفنا Decorators إلى خصائصه، ثم استدعينا الدالة validate(). تقوم هذه الدالة بإرجاع مصفوفة من الأخطاء إذا كانت البيانات لا تتوافق مع القواعد.