عن المشروع

Zod هي مكتبة للتحقق من صحة البيانات مصممة أولاً لـ TypeScript. تحدد مخططًا، وتحلل البيانات باستخدامه، وتحصل على نتيجة متحقق منها وذات أنواع قوية. تعمل في Node.js والمتصفحات الحديثة، ولا تحتوي على أي اعتماديات خارجية، وتقدم حزمة أساسية صغيرة (حوالي 2kb مضغوطة). واجهة برمجة التطبيقات غير قابلة للتغيير: تعيد الطرق نسخة جديدة بدلاً من تعديل المخطط الحالي. يمكن استخدامها من TypeScript أو JavaScript العادي وتتضمن تحويلًا مدمجًا إلى JSON Schema. تبدأ الاستخدامات الأساسية بتحديد مخطط، على سبيل المثال كائن يحتوي على حقل نصي وحقل رقمي. استدعاء `.parse` على المخطط يتحقق من المدخل ويعيد نسخة عميقة ذات أنواع قوية. إذا استخدم المخطط تحسينات أو تحويلات غير متزامنة، يلزم استخدام `.parseAsync()` بدلاً من ذلك. عند فشل التحقق، ترمي `.parse()` خطأ `ZodError` يحتوي على معلومات تفصيلية عن المشكلة مثل النوع المتوقع، ورمز الخطأ، ومسار الحقل المخالف، ورسالة. لتجنب try/catch، تعيد `.safeParse()` اتحادًا متمايزًا إما مع البيانات المحللة أو الخطأ؛ وتغطي `.safeParseAsync()` المخططات غير المتزامنة. يمكن استنتاج الأنواع من المخططات باستخدام `z.infer<>`. عندما تختلف أنواع الإدخال والإخراج، على سبيل المثال من خلال `.transform()`، تستخرج `z.input<>` و `z.output<>` كلًا منها بشكل مستقل. سمة بارزة هي الترجمة المسبقة (ahead-of-time compilation). تعيد `z.compile(schema)` نسخة من المخطط مع مسار سريع مترجم للمدخلات الصالحة، بينما تعود المدخلات غير الصالحة إلى المحلل العادي بحيث يبقى الإبلاغ عن الأخطاء متطابقًا. يفيد README بتسريع وسطي قدره 2.4x عبر مجموعة قياس مرجعي من 55 مخططًا، مع زيادة تتناسب مع تعقيد المخطط (المصفوفات الكبيرة من الكائنات والكائنات ذات 20 مفتاحًا حوالي 9x، والكائنات المتداخلة حوالي 4.5x، بينما لا تحصل مخططات النصوص المجردة على أي تسريع). يمكن أيضًا تفعيل الترجمة بشكل عام عن طريق استيراد `zod/compile` قبل الوحدات التي تحدد المخططات. تستخدم الترجمة `new Function`، ويتم تعطيل الوضع العام تلقائيًا عند ضبط `z.config({ jitless: true })`، مثل في بيئات CSP؛ واستدعاء `z.compile()` مباشرة هو اختيار صريح. المخططات ذات التحسينات أو التحويلات غير المتزامنة، وبعض الإنشاءات الأخرى، لا يمكن ترجمتها؛ في هذه الحالة تعيد `z.compile()` المخطط دون تغيير ويستمر في استخدام المحلل العادي، ما لم يتم تمرير `{ strict: true }` لرمي أخطاء محددة. عند المدخلات غير الصالحة، قد تعمل التحسينات والتحويلات مرتين. اشتقاق مخطط جديد من مخطط مترجم يعيد مخططًا غير مترجم، لذا يجب ترجمة المخطط النهائي. التثبيت يتم عبر `npm install zod`. يربط المشروع بوثائق على zod.dev، ومجتمع Discord، وقنوات التواصل الاجتماعي. وهي مرخصة بموجب MIT.