Valibot TypeScript: دليل شامل، أمثلة وتثبيت

مقدمة: ما هي Valibot ولماذا تحتاجها؟

Valibot هي مكتبة حديثة، معيارية وخفيفة الوزن للتحقق من صحة البيانات (Validation) بلغة TypeScript و JavaScript. على عكس المكتبات الكبيرة مثل Zod أو Joi، تم تصميم Valibot مع التركيز على تقليل حجم الحزمة النهائية (Bundle Size) وإمكانية حذف الكود غير المستخدم (Tree-shaking).

الفلسفة الأساسية لـ Valibot هي "ادفع فقط مقابل ما تستخدمه". إذا كنت بحاجة فقط للتحقق من أن سلسلة نصية (String) لا تقل عن طول معين، يمكنك استيراد دالتي string و minLength فقط، دون الحاجة لاستيراد المكتبة بأكملها. هذا يجعل Valibot خيارًا مثاليًا للمشاريع التي يكون فيها حجم حزمة JavaScript النهائية مهمًا (مثل تطبيقات الهاتف المحمول أو مكتبات المكونات).

المكتبة مدعومة بالكامل بأنواع TypeScript وتوفر تكاملًا ممتازًا معها، حيث تستنتج الأنواع تلقائيًا من مخططات التحقق. تدعم Valibot الأنواع البدائية البسيطة (سلاسل نصية، أرقام، قيم منطقية) والهياكل المعقدة (كائنات، مصفوفات، أنواع الاتحاد (Union Types)، والمخططات التكرارية).

التثبيت

يتم توزيع Valibot عبر مدير الحزم npm. للتثبيت، قم بتنفيذ الأمر التالي في terminal مشروعك:

npm install valibot

إذا كنت تستخدم yarn:

yarn add valibot

لـ pnpm:

pnpm add valibot

بعد التثبيت، يمكنك استيراد الدوال التي تحتاجها في ملف TypeScript الخاص بك:

import { string, number, object, minLength, maxValue } from 'valibot';

بداية سريعة مع مثال برمجي

لنقم بإنشاء مخطط تحقق بسيط لنموذج تسجيل مستخدم. سنتحقق من الاسم، البريد الإلكتروني والعمر.

import { object, string, number, email, minLength, maxValue, safeParse } from 'valibot';

// 1. تعريف المخطط
const UserSchema = object({
  name: string([minLength(2, 'يجب أن يحتوي الاسم على حرفين على الأقل')]),
  email: string([email('البريد الإلكتروني غير صحيح')]),
  age: number([maxValue(120, 'لا يمكن أن يتجاوز العمر 120 عامًا')])
});

// 2. البيانات المراد التحقق منها
const inputData = {
  name: 'آنا',
  email: 'anna@example.com',
  age: 30
};

// 3. التحقق
const result = safeParse(UserSchema, inputData);

if (result.success) {
  console.log('البيانات صحيحة:', result.output);
  // result.output له النوع { name: string; email: string; age: number; }
} else {
  console.error('أخطاء التحقق:', result.issues);
  // result.issues هي مصفوفة من الكائنات التي تصف الأخطاء
}

في هذا المثال، استخدمنا safeParse وهي طريقة آمنة لا ترمي استثناءً (Exception)، بل تعيد كائنًا يحتوي على حقل success. إذا نجح التحقق، ستجد البيانات التي تم التحقق منها مع الأنواع الصحيحة في result.output.

الدوال والأساليب الأساسية

توفر Valibot العديد من الدوال لإنشاء المخططات. دعنا نستعرض أهمها.

1. `string()`

الوظيفة: تنشئ مخططًا للتحقق من القيم النصية. تقبل مصفوفة اختيارية من أدوات التحقق (Validators) لإجراء فحوصات إضافية (الطول، النمط، إلخ).

المعاملات:

validations (اختياري): مصفوفة من دوال التحقق، مثل minLength، maxLength، email، url، regex وغيرها.

مثال:

import { string, minLength, maxLength, email } from 'valibot';

const UsernameSchema = string([minLength(3), maxLength(20)]);
const EmailSchema = string([email()]);

console.log(safeParse(UsernameSchema, 'Jo')); // { success: false, issues: [...] }
console.log(safeParse(EmailSchema, 'test@test.com')); // { success: true, output: 'test@test.com' }