TypeBox TypeScript: دليل شامل، أمثلة، تثبيت

ما هو TypeBox ولماذا تحتاجه؟

TypeBox هي مكتبة قوية لـ TypeScript تتيح لك تعريف مخططات بيانات متوافقة مع معيار JSON Schema، وفي نفس الوقت تستخرج منها أنواع TypeScript ثابتة وصحيحة. ببساطة، هي جسر بين التحقق من البيانات في وقت التشغيل (عندما يعمل تطبيقك ويتحقق من البيانات فورياً) والأنواع في وقت الترجمة (عندما يتحقق TypeScript من صحة الكود قبل تنفيذه).

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

مدقق وقت التشغيل — يتحقق مما إذا كان الكائن يطابق المخطط أثناء تشغيل البرنامج.
نوع ثابت — يستنتج TypeScript النوع تلقائياً لاستخدامه في التعليقات التوضيحية.
JSON Schema — يمكن تسلسل المخطط إلى JSON واستخدامه في أدوات أخرى (مثل إنشاء نماذج UI أو التوثيق).

TypeBox مثالي لـ: إنشاء نقاط نهاية API مع التحقق من جسم الطلب، العمل مع ملفات الإعدادات، بناء نماذج معقدة مع التحقق من الحقول، وأي سيناريو تكون فيه سلامة الأنواع مهمة في جميع المراحل.

تثبيت TypeBox

TypeBox هي مكتبة لـ Node.js/TypeScript، لذا يتم تثبيتها عبر npm (أو yarn/pnpm).

npm install @sinclair/typebox

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

import { Type } from '@sinclair/typebox';

للعمل مع التحقق، ستحتاج أيضاً إلى المدقق نفسه. TypeBox لا يتضمنه افتراضياً لإتاحة الخيار للمطور. يُوصى باستخدام @sinclair/typebox/compiler (المترجم المدمج) أو ajv (مدقق JSON Schema الشهير). لنقم بتثبيت المترجم:

npm install @sinclair/typebox-compiler

أو إذا كنت تفضل AJV:

npm install ajv ajv-formats

ملاحظة: اسم المكتبة هو @sinclair/typebox وليس فقط typebox. هذا مهم للتثبيت الصحيح.

بداية سريعة مع مثال برمجي

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

import { Type } from '@sinclair/typebox';
import { TypeCompiler } from '@sinclair/typebox/compiler';

// 1. نحدد مخطط المستخدم
const UserSchema = Type.Object({
    id: Type.Number(),
    name: Type.String({ minLength: 2 }),
    email: Type.String({ format: 'email' }),
    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),
});

// 2. ننشئ مترجم للتحقق
const validator = TypeCompiler.Compile(UserSchema);

// 3. بيانات اختبارية
const validUser = {
    id: 1,
    name: 'أحمد',
    email: 'ahmed@example.com',
    age: 30,
};

const invalidUser = {
    id: 'ليس-رقماً',
    name: 'أ',
    email: 'بريد-غير-صالح',
};

// 4. التحقق
console.log(validator.Check(validUser));   // true
console.log(validator.Check(invalidUser)); // false

// 5. الحصول على النوع الثابت
type UserType = Static<typeof UserSchema>;
// الآن UserType هو { id: number; name: string; email: string; age?: number; }

في هذا المثال، قمنا بتعريف مخطط، وترجمته إلى مدقق، وتحققنا من كائنين. لاحظ استخدام Type.Optional للحقل age — يمكن أن يكون غائباً. كما استخدمنا format: 'email' للتحقق من تنسيق البريد الإلكتروني.