Zod 4: الدليل الكامل للتحقق في TypeScript

أصبحت مكتبة Zod في صمت النسيج الرابط لمنظومة TypeScript الحديثة. فهي تتحقّق من أجسام طلبات الـ API، وتُنمّط متغيرات البيئة، وتشكّل المخرجات المنظّمة لاستدعاءات نماذج الذكاء الاصطناعي، وتُشغّل مكتبات النماذج من React Hook Form إلى TanStack Form. وعندما تُطلق المكتبة الأكثر استخدامًا للمخطّطات إصدارًا رئيسيًا، فعلى كل فريق يلمس TypeScript أن ينتبه.

إصدار Zod 4 هو ذلك الإصدار الرئيسي، وهو ليس تحديثًا شكليًا. لقد أُعيدت كتابة بنيته الداخلية لتحقيق قفزات في السرعة، وخُفّض حجم الحزمة إلى النصف، وأُضيفت موجة من الواجهات تسدّ ثغرات قديمة. يستعرض هذا الدليل ما تغيّر، والميزات الجديدة الجديرة بالاعتماد أولًا، وكيفية الترقية من Zod 3 دون كسر بيئة الإنتاج.

لماذا يهمّ Zod 4

العنوان الأبرز هو الأداء. يحلّل Zod 4 النصوص أسرع بنحو 14 مرة من Zod 3، والمصفوفات أسرع بنحو 7 مرات، والكائنات أسرع بنحو 6.5 مرة. والأهم بالنسبة للمشاريع الكبيرة أنه يقلّل عمليات إنشاء أنواع TypeScript بنحو 100 مرة، فيتوقف الإكمال التلقائي في المحرر وعمليات بناء tsc عن التباطؤ مع المخطّطات المتداخلة بعمق. كما انكمش حجم الحزمة الأساسية بنحو 57 بالمئة.

يستحق هذا الرقم الأخير تأكيدًا خاصًا. فإن كنت تشحن Zod إلى المتصفح داخل تدفّق التحقق من نموذج أو دالة طرفية، كنت تدفع ضريبة حقيقية على حجم الحزمة. يقسم Zod 4 هذه الضريبة إلى النصف، ويخفضها المتغيّر الجديد القابل للتشذيب أكثر بكثير.

صيغ النصوص على المستوى الأعلى

في Zod 3 كانت صيغ النصوص دوالّ متسلسلة: z.string().email(). أما Zod 4 فيرفعها إلى دوالّ على المستوى الأعلى، وهي أسرع في التحليل وأفضل في التشذيب الشجري.

import * as z from "zod";
 
// الصيغة الجديدة المفضّلة
const Email = z.email();
const Id = z.uuidv7();
const Link = z.url();
const Token = z.jwt();
const Address = z.ipv4();
 
// لا يزال بإمكانك تخصيص نمط التحقق
const StrictEmail = z.email({ pattern: z.regexes.html5Email });

لا تزال الدوال المتسلسلة القديمة مثل z.string().email() تعمل لكنها مهملة، لذا يُفضّل أن يعتمد الكود الجديد الدوالّ على المستوى الأعلى. كما يضيف Zod 4 صيغًا عددية دقيقة مثل z.int32() وz.uint32() وz.float64() وz.int64() للحالات التي يهمّ فيها عرض البتات فعلًا.

ملفات وتحويل منطقي من الدرجة الأولى

تُزيل إضافتان عمليتان الكثير من الشيفرة المتكررة التي كان كل فريق يكتبها يدويًا. أصبح التحقق من الملفات أصيلًا، وهو مثالي لنقاط رفع الملفات:

const Upload = z.file()
  .min(10_000)              // بايت
  .max(1_000_000)
  .mime(["image/png", "image/webp"]);

وأخيرًا تقوم z.stringbool() بما طالما أردته عند قراءة متغيرات البيئة أو سلاسل الاستعلام، إذ تحوّل القيم النصية المرنة إلى قيم منطقية حقيقية:

const FeatureFlag = z.stringbool();
FeatureFlag.parse("true");   // true
FeatureFlag.parse("yes");    // true
FeatureFlag.parse("0");      // false

الـ Codecs: تحويلات ثنائية الاتجاه

تمثّل الـ codecs أكثر الأفكار جدّةً في Zod 4. يصف الـ codec كيفية التحويل بين تمثيلين في كلا الاتجاهين، فيمكنك فكّ تشفير صيغة واردة وإعادة تشفيرها عند الخروج باستخدام مخطّط واحد. المثال الكلاسيكي هو نص تاريخ بصيغة ISO تريد التعامل معه ككائن Date حقيقي.

const ISODate = z.codec(
  z.iso.datetime(),   // مخطّط الإدخال
  z.date(),           // مخطّط الإخراج
  {
    decode: (str) => new Date(str),
    encode: (date) => date.toISOString(),
  }
);
 
z.decode(ISODate, "2026-06-19T10:00:00Z"); // كائن Date
z.encode(ISODate, new Date());             // نص ISO

ولأن z.encode() وz.decode() تعملان مع أي مخطّط لا مع الـ codecs فقط، يمكنك بناء مصدر حقيقة واحد لتحليل البيانات عند الدخول وتسلسلها عند الخروج. وهذا يلغي فئة كاملة من المحوّلات اليدوية غير المتطابقة.

أنواع تعاودية أنظف

كانت المخطّطات التعاودية تتطلب استدعاء z.lazy() المربك مع تعليق نوع صريح. يدعم Zod 4 صياغة الـ getter، فتُنمّط شجرة من الفئات نفسها دون أي تحويل قسري:

const Category = z.object({
  name: z.string(),
  get subcategories() {
    return z.array(Category);
  },
});

النوع المستنتَج تعاودي بالكامل، ويفهمه محرّرك.

البيانات الوصفية والسجلات وJSON Schema

يضيف Zod 4 نظام بيانات وصفية منظّم عبر .meta() وسجلّ عام، ثم يبني فوقه توافقية حقيقية. يمكنك إرفاق عناوين وأوصاف بأي مخطّط وتحويله بالكامل إلى JSON Schema، وهو تحديدًا ما تحتاجه لمستندات OpenAPI أو توليد النماذج ديناميكيًا أو تعريفات استدعاء الدوال في نماذج الذكاء الاصطناعي.

const User = z.object({
  id: z.uuidv7().meta({ description: "المفتاح الأساسي" }),
  email: z.email(),
  age: z.int().min(0).meta({ title: "العمر بالسنوات" }),
});
 
const jsonSchema = z.toJSONSchema(User);
// جاهز للتمرير إلى OpenAPI أو تعريف أداة ذكاء اصطناعي

تتجاوز أهمية هذا التوثيق بكثير. فالمخطّط نفسه الذي يتحقق من بياناتك يمكنه الآن توليد الـ JSON Schema الذي يحتاجه نموذج الذكاء الاصطناعي للمخرجات المنظّمة، ما يزيل الازدواجية التي كانت تعيش بين طبقة التحقق وتعريفات أدواتك.

أخطاء أفضل

كان تخصيص الأخطاء مبعثرًا بين message وinvalid_type_error وrequired_error وerrorMap في Zod 3. يوحّد Zod 4 كل ذلك تحت معامل واحد هو error يقبل نصًا أو دالة.

const Name = z.string({
  error: (issue) =>
    issue.input === undefined ? "الاسم مطلوب" : "يجب أن يكون نصًا",
});

ولعرض الأخطاء للمستخدمين، تحوّل z.prettifyError() الخطأ الخام إلى نص متعدد الأسطر نظيف، وتتيح z.config(z.locales.en()) ترجمة الرسائل عبر اللغات المدعومة، وهو مكسب حقيقي للمنتجات متعددة اللغات الشائعة في أسواق منطقة الشرق الأوسط وشمال إفريقيا.

Zod Mini للحوسبة الطرفية

إن كان حجم الحزمة هو قيدك، يكشف zod/mini محرّك التحقق نفسه عبر واجهة دالّية قابلة للتشذيب الشجري بالكامل. تستورد فقط الأجزاء التي تستخدمها، ويبقى منطق المحلّل مشتركًا.

import * as z from "zod/mini";
 
const Schema = z.object({
  name: z.string(),
  email: z.optional(z.email()),
});

المقايضة هي سهولة الاستخدام. فأنت تكتب z.optional(z.string()) بدلًا من z.string().optional(). وبالنسبة لدالة طرفية أو حزمة عميل حسّاسة للحجم، فهذا ثمن عادل مقابل بصمة أصغر بكثير.

الترقية من Zod 3

يعمل معظم كود Zod 3 على Zod 4 دون تغيير، لكن بضعة أنماط تحتاج انتباهًا:

• معاملات الأخطاء. استبدل message وinvalid_type_error وrequired_error وerrorMap بمعامل error الموحّد.
• صيغ النصوص. لا تزال الدوال المتسلسلة مثل .email() و.uuid() تعمل لكنها مهملة. انتقل إلى z.email() وz.uuidv4() كلما لمست ملفًا.
• التنقيحات. لم تعد .refine() تلفّ المخطّطات في ZodEffects، فيمكنك تسلسل دوال مثل .min() بعد التنقيح بحرية.
• القيم الحرفية. استخدم z.literal([200, 201, 202]) بدلًا من لفّ عدة قيم حرفية في اتحاد.

النهج العملي هو ترقية الاعتمادية، وتشغيل فاحص الأنواع ومجموعة الاختبارات، وإصلاح حفنة تحذيرات الإهمال تدريجيًا بدلًا من إعادة كتابة كل شيء دفعة واحدة.

الخلاصة

إصدار Zod 4 من الإصدارات الرئيسية النادرة التي تجمع بين السرعة والقدرة دون فرض إعادة كتابة مؤلمة. مكاسب الأداء وحجم الحزمة وحدها تبرّر الترقية، وتضع الـ codecs الجديدة وتصدير JSON Schema ونظام البيانات الوصفية مكتبة Zod كعمود فقري للمخطّطات في تطبيقات عصر الذكاء الاصطناعي، حيث يجب على التعريف نفسه أن يتحقق من البيانات ويوثّق واجهة برمجية ويصف أداة لنموذج.

إن كنت تبني منتجات TypeScript اليوم، فلم يعد التحقق من المخطّطات أمرًا ثانويًا يُلصق بأطراف تطبيقك. إنه العقد الذي يربط بياناتك وواجهاتك وتكاملات الذكاء الاصطناعي معًا. ويجعل Zod 4 فرض هذا العقد أسرع وإعادة استخدامه أسهل بكثير. في نقطة، نعدّ التنميط القوي والحدود المتحقَّق منها أساس البرمجيات الموثوقة، وأصبح Zod 4 الآن جزءًا افتراضيًا من ذلك الأساس.