Zod TypeScript: طرق، أمثلة، تثبيت

مقدمة إلى Zod: ما هو ولماذا تحتاجه

\n\n

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

\n\n

Zod هي مكتبة للتحقق من صحة البيانات وتصنيفها بشكل تصريحي لـ TypeScript و JavaScript. تتيح لك إنشاء مخططات (schemas) تعمل في نفس الوقت كمدقق للبيانات أثناء التنفيذ، وكمصدر حقيقة للأنواع الثابتة في TypeScript. الفلسفة الأساسية لـ Zod هي "مخطط واحد، غرضان": تكتب المخطط مرة واحدة، وتحصل على التحقق من الصحة والنوع المستنتج تلقائيًا.

\n\n

المزايا الرئيسية لـ Zod:

أمان الأنواع: استنتاج تلقائي لأنواع TypeScript من المخططات.
التصريحية: بناء جملة مقروء وموجز.
قابلية التركيب: يمكن دمج المخططات وتوسيعها.
أخطاء مفصلة: رسائل خطأ واضحة للتحقق من الصحة.
بدون تبعيات: المكتبة لا تتطلب حزمًا إضافية.

\n\n

تثبيت Zod

\n\n

Zod هي حزمة npm، لذلك يتم التثبيت عبر مدير حزم Node.js. المكتبة مكتوبة بلغة TypeScript وتأتي مع ملفات إعلان الأنواع الجاهزة، لذلك لا يلزم تثبيت إضافي لـ @types/zod.

\n\n

# التثبيت عبر npm\nnpm install zod\n\n# التثبيت عبر yarn\nyarn add zod\n\n# التثبيت عبر pnpm\npnpm add zod

\n\n

بعد التثبيت، يمكنك استيراد Zod في مشروعك:

\n\n

import { z } from "zod";

\n\n

ملاحظة: لا يتم تثبيت Zod عبر pip، لأنه مكتبة للنظام البيئي JavaScript/TypeScript، وليس Python.

\n\n

بداية سريعة مع مثال كود

\n\n

لنقم بإنشاء مخطط بسيط للتحقق من صحة بيانات المستخدم ونرى فورًا كيف يجمع Zod بين التحقق من الصحة والتصنيف.

\n\n

import { z } from "zod";\n\n// 1. تعريف المخطط\nconst UserSchema = z.object({\n    id: z.number().positive(),\n    name: z.string().min(2, "يجب أن يحتوي الاسم على حرفين على الأقل"),\n    email: z.string().email("بريد إلكتروني غير صحيح"),\n    age: z.number().int().min(18, "يجب أن لا يقل العمر عن 18 عامًا").optional(),\n});\n\n// 2. استنتاج النوع تلقائيًا من المخطط\ntype User = z.infer<typeof UserSchema>;\n\n// 3. التحقق من صحة البيانات\nconst validData = {\n    id: 1,\n    name: "آنا",\n    email: "anna@example.com",\n    age: 25,\n};\n\nconst result = UserSchema.safeParse(validData);\n\nif (result.success) {\n    // result.data له النوع User\n    console.log("تم التحقق بنجاح:", result.data);\n} else {\n    // result.error يحتوي على معلومات مفصلة عن الأخطاء\n    console.log("أخطاء التحقق:", result.error.errors);\n}\n\n// مثال مع بيانات غير صحيحة\nconst invalidData = {\n    id: -1,\n    name: "أ",\n    email: "ليس-بريد",\n};\n\nconst invalidResult = UserSchema.safeParse(invalidData);\nif (!invalidResult.success) {\n    console.log("الأخطاء:", invalidResult.error.errors);\n    // سيطبع:\n    // - id: يجب أن يكون رقمًا موجبًا\n    // - name: يجب أن يحتوي الاسم على حرفين على الأقل\n    // - email: بريد إلكتروني غير صحيح\n}

\n\n