الإقليم ٦ — الحدود التي لا تُوثَق: التحقّق وقت التشغيل (Zod)

النبذة

هذا الإقليم قصيرٌ مفاهيمياً لكنه يختم أهمَّ خيطٍ في المنهج كلّه. منذ الإقليم ١ تحمل علامةً: الأنواع تُمحى وقت التشغيل. ومنذ الإقليم ٣ تركنا req.body معلّقاً كـ any لا يُوثَق. ومنذ ٥ رأينا Prisma يعيد النوعَ من جهة القاعدة. الآن نعيده من جهة الشبكة، ونفهم لماذا لا غنى عن حارسٍ يعمل وقت التشغيل حيث لا أنواع. من يفهم هذا الإقليم، يفهم لماذا تنهار برامجُ كثيرةٌ رغم أنها "مكتوبةُ النوع".

اللغز المستفزّ

ts
type CreateUserInput = { username: string; email: string; password: string; role: "USER" | "ADMIN" };

export async function createUser(req: Request, res: Response) {
  const body = req.body as CreateUserInput;          // "أنا متأكّد أنه بهذا الشكل"
  const hash = await bcrypt.hash(body.password, 10);  // ...هل أنت متأكّد؟
  await prisma.user.create({ data: { ...body, password: hash } });
}

ليش: الهاوية الأساسيّة — وأين تنتهي ضمانةُ المترجم

ثبّت هذه الحقيقةَ فوق كل ما سبق:

إذن كلُّ حدٍّ (boundary) يحتاج بوّابةً تعمل وقت التشغيل. تحويلُ المجهول (unknown) إلى معلومٍ موثوقٍ ليس ترفاً — هو الوحيدُ الذي يجعل بقيّةَ برنامجك المكتوبِ-النوع صادقاً. بلا هذه البوّابة، كلُّ أنواعِك بعد الحدّ أوهامٌ مبنيّةٌ على كذبة as.

ثلاثُ طبقاتِ حراسةٍ — الآن تكتمل الصورة

جمعنا عبر المنهج ثلاثةَ حرّاسٍ، كلٌّ يحرس شيئاً مختلفاً في زمنٍ مختلف. لا يغني أحدُهم عن الآخر:

مثالٌ يوضّح لِمَ الثلاثة: تفرّدُ username. Zod لا يستطيع فحصَه (لا يرى القاعدة)، فيمرّ. القاعدةُ تفرضه ذرّياً (٤). والمترجمُ لا علاقةَ له أصلاً. ومثالٌ معاكس: "كلمةُ المرور ٨ أحرفٍ على الأقلّ" — Zod يفحصها بلطفٍ ويعطي رسالةً للمستخدم، بينما القاعدةُ لا تكترث. كلٌّ في موضعه.

ليش وكيف: Zod — السكيمةُ قيمةٌ وقتَ التشغيل

في TS، النوعُ خياليٌّ يُمحى. فكرةُ Zod: اجعل السكيمةَ قيمةً حقيقيّةً (كائنَ JS موجوداً وقت التشغيل) تعرف كيف تفحص قيمةً مجهولةً وتقرّر: مطابِقةٌ (أعِدها مكتوبةَ النوع) أو لا (أعِد أخطاءً مفصّلة).

ts
import { z } from "zod";

const createUserSchema = z.object({
  username: z.string().trim().min(3, "3 أحرف على الأقل"),
  email: z.email("بريدٌ غير صالح"),
  password: z.string().min(8, "8 أحرف على الأقل"),
  role: z.enum(["USER", "ADMIN"]).optional(),
});

createUserSchema ليس نوعاً — هو كائنٌ تستطيع أن تطبعه وتمرّره وتنادي عليه دوالّ. هذا هو الفرق: يعيش وقت التشغيل حيث الأنواعُ ميّتة.

الفحص: safeParse مقابل parse

ts
const result = createUserSchema.safeParse(req.body);   // لا يرمي — يرجّع نتيجة
if (!result.success) {
  const errors = z.flattenError(result.error);         // { fieldErrors, formErrors }
  return res.status(400).json({ error: "Invalid user data", details: errors.fieldErrors });
}
const data = result.data;     // ← الآن موثوقٌ ومكتوبُ النوع

safeParse يرجّع { success, data } أو { success: false, error } بلا رميٍ (مشروعك يستعمله). parse يرمي استثناءً عند الفشل (مفيدٌ مع معالِج الأخطاء في Express 5 الذي يلتقط الرفض — الإقليم ٣). وflattenError يحوّل الأخطاءَ إلى fieldErrors لكل حقل — جاهزةً لواجهةٍ تعرضها بجانب كل خانة.

الميزةُ القاتلة: z.infer — توليدُ النوع من السكيمة (الوجه المقابل لـ Prisma)

ts
type CreateUserInput = z.infer<typeof createUserSchema>;
// = { username: string; email: string; password: string; role?: "USER" | "ADMIN" }

عرّفتَ التحقّق مرّةً (قيمةٌ وقت التشغيل)، فاشتُقّ النوعُ الساكن منه مجّاناً. هذا مصدرُ الحقيقة الواحد عند الحدّ: لا تكتب النوعَ والتحقّقَ منفصلين فيتباعدان. وهنا يكتمل التناظرُ الذي وعدتُ به في الإقليم ٥:

"حلّل، لا تتحقّق فقط" (parse, don't validate)

فرقٌ دقيقٌ مهم: لا تفحص req.body ثم تمرّر any كما هو. حوّله (parse) إلى قيمةٍ جديدةٍ مكتوبةِ النوع، واستعمل مخرجَ Zod لا الإدخالَ الخام. هكذا يصير كلُّ ما بعد البوّابة موثوقاً ومكتوبَ النوع، ويختفي any من بقيّة المسار. (وZod يقدر أيضاً أن يحوّل: z.coerce.number() يحوّل نصَّ الـ query إلى رقم؛ .trim() ينظّف؛ فالمخرجُ ليس فحصاً فقط بل تطبيعاً.)

الأمن: البوّابةُ خطُّ الدفاع الأول

التحقّقُ ليس راحةً فقط — هو أمنٌ: يرفض الأنواعَ الخاطئة، ويقصّ الحقولَ الزائدة (ضدّ mass assignment: role: "ADMIN" في تسجيلٍ يجب أن يُرفَض أو يُتجاهَل لا أن يُسنَد)، ويحدّ الأطوالَ (ضدّ حمولاتٍ مفجِّرة). إنه البوّابةُ التي تلي helmet/cors/rate-limit في سلسلتك (٣)، وتسبق الهويةَ والمنطق. (يربط بعقلية حدود الموارد ضد إساءة الاستعمال من Docker والـ rate-limit.)

اللغز / البناء من الصفر

الخلاصة — أين تتّصل هذه العقدة بالشجرة

الوصلة للواقع (نمط SelfLab)

user.schema.ts وuser.controller.ts يصيران واضحين تماماً:

ts
// user.schema.ts — السكيمةُ قيمةٌ وقت التشغيل
export const createUserSchema = z.object({
  firstName: z.string().trim().min(2, "..."),
  email: z.email({ error: "..." }),
  password: z.string().min(8, "..."),
  role: z.enum(["USER", "ADMIN"]).optional(),
});

// user.controller.ts — البوّابة
const validation = createUserSchema.safeParse(req.body);
if (!validation.success) {
  const errors = z.flattenError(validation.error);
  return res.status(400).json({ error: "Invalid user data", details: errors.fieldErrors });
}
const { firstName, ... } = validation.data;   // موثوقٌ من هنا فصاعداً

تقرؤه الآن كتجسيدٍ حرفيٍّ للدرس: safeParse البوّابة، flattenError رسائلُ الحقول، validation.data المخرجُ الموثوق، ورمزُ 400 (طلبُك خاطئ، الإقليم ٠). وتملك الآن تحسينَه: حوّله إلى validate(schema) middleware معادِ الاستخدام (لغز د) كي لا يتكرّر في كل متحكّم، وضعه في السلسلة بعد helmet/cors.