Superstruct لـ TypeScript: دليل شامل مع أمثلة

مقدمة عن Superstruct

Superstruct هي مكتبة خفيفة الوزن لكنها قوية للتحقق من صحة (Validation) وتحليل (Parsing) هياكل البيانات في TypeScript و JavaScript. تتيح لك وصف الشكل المتوقع للبيانات (كائنات، مصفوفات، نصوص، أرقام، إلخ) باستخدام "مخططات" (structs) بسيطة ومعبرة، ثم التحقق مما إذا كانت البيانات الفعلية تتطابق مع هذه المخططات.

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

لماذا تحتاج Superstruct؟

• التحقق من البيانات من مصادر خارجية: استجابات API، بيانات النماذج، ملفات الإعدادات، localStorage — في أي مكان قد تأتي فيه البيانات بتنسيق غير متوقع.
• إنشاء كائنات نقل بيانات (DTO) آمنة: تضمن أن البيانات المنقولة بين طبقات التطبيق تتوافق مع الهيكل المتوقع.
• التحليل والتحويل: لا تتحقق Superstruct من البيانات فحسب، بل يمكنها أيضًا تحويلها (مثل تحويل النصوص إلى أرقام).
• توثيق قابل للقراءة: مخططات Superstruct بحد ذاتها تعتبر توثيقًا ممتازًا لشكل البيانات.

التثبيت

Superstruct هي حزمة npm، لذا يتم التثبيت عبر مدير الحزم الخاص بـ Node.js:

npm install superstruct

أو، إذا كنت تستخدم Yarn:

yarn add superstruct

بعد التثبيت، يمكنك استيراد المكتبة إلى ملف TypeScript الخاص بك:

import { struct, string, number, object, array, optional, union, literal, enums, size, refine, assert, is, validate } from 'superstruct';

البداية السريعة

لنقم بإنشاء مخطط بسيط لمستخدم والتحقق من البيانات.

import { object, string, number, assert } from 'superstruct';

// 1. تعريف المخطط (struct)
const User = object({
    id: number(),
    name: string(),
    email: string(),
});

// 2. البيانات التي نريد التحقق منها
const userData = {
    id: 1,
    name: 'أحمد',
    email: 'ahmed@example.com',
};

// 3. التحقق من الصحة
try {
    assert(userData, User);
    console.log('البيانات صحيحة!');
} catch (e) {
    console.error('خطأ في التحقق:', e.message);
}

// 4. إذا كانت البيانات غير صحيحة، سيرمي assert استثناءً
const badData = { id: 'ليس رقمًا', name: 'سارة' };
try {
    assert(badData, User);
} catch (e) {
    console.error('خطأ:', e.message);
    // الإخراج: Expected a number for `id`, but received: "ليس رقمًا"
}

الطرق والدوال الأساسية

توفر Superstruct مجموعة من المصانع (factories) لإنشاء المخططات. إليك 10 طرق أساسية:

1. string()

الوصف: تنشئ مخططًا يتحقق من أن القيمة هي نص (string).

المعلمات: لا يوجد.

import { string, assert } from 'superstruct';

const NameSchema = string();
assert('مرحبًا', NameSchema); // صحيح
// assert(123, NameSchema); // خطأ: Expected a string, but received: 123

2. number()

الوصف: تتحقق من أن القيمة هي رقم (بما في ذلك NaN، ما لم يُحدد خلاف ذلك).

المعلمات: لا يوجد.

import { number, assert } from 'superstruct';

const AgeSchema = number();
assert(30, AgeSchema); // صحيح
// assert('30', AgeSchema); // خطأ

3. boolean()

الوصف: تتحقق من أن القيمة هي قيمة منطقية (true أو false).

المعلمات: لا يوجد.

import { boolean, assert } from 'superstruct';

const IsActiveSchema = boolean();
assert(true, IsActiveSchema); // صحيح

4. object(schem