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

ما هي مكتبة typia ولماذا تحتاجها؟

typia هي مكتبة قوية لـ TypeScript توفر التحقق من الأنواع في وقت التشغيل (runtime type validation) بميزة فريدة: تقوم بتوليد كود التحقق في وقت الترجمة (compile-time) وليس أثناء التنفيذ. هذا يجعلها واحدة من أسرع مكتبات التحقق من البيانات في نظام TypeScript البيئي.

المشاكل الرئيسية التي تحلها typia:

الأداء: على عكس المكتبات الشائعة (zod, yup, io-ts)، لا تستخدم typia الانعكاس (reflection) أو الديكوراتورز. بدلاً من ذلك، تقوم بتوليد كود تحقق محسّن في مرحلة البناء، مما يحقق زيادة في السرعة تتراوح بين 10 إلى 100 مرة.
أمان الأنواع: تحصل على ضمان أن البيانات القادمة من مصادر خارجية (API، قواعد البيانات، النماذج) تتوافق مع واجهات TypeScript الخاصة بك.
أقل كود مكرر: لست بحاجة لكتابة مخططات تحقق منفصلة — تستخدم typia أنواع TypeScript الموجودة لديك مباشرة.
دعم الأنواع المعقدة: Union, intersection, conditional types, mapped types — كلها تعمل "فوراً" دون إعدادات إضافية.

المكتبة مفيدة بشكل خاص لـ:

تطوير الواجهات الخلفية (Backend) على Node.js مع TypeScript
تطبيقات الواجهات الأمامية (Frontend) التي تحتاج التحقق من النماذج أو استجابات API
الهندسة المعمارية للخدمات المصغرة (Microservices) حيث سرعة التسلسل/إلغاء التسلسل مهمة
المشاريع التي يكون فيها الأداء وأمان الأنواع أمراً حاسماً

التثبيت

يتكون تثبيت typia من خطوتين: المكتبة نفسها ومحوّل TypeScript (المترجم).

الخطوة 1. التثبيت عبر npm

npm install typia
# أو
yarn add typia
# أو
pnpm add typia

الخطوة 2. تثبيت المحوّل

npm install --save-dev typia-transform
# أو
yarn add -D typia-transform
# أو
pnpm add -D typia-transform

الخطوة 3. إعداد tsconfig.json

أضف الإضافة (plugin) إلى ملف tsconfig.json الخاص بك:

{
  "compilerOptions": {
    "plugins": [
      {
        "transform": "typia-transform"
      }
    ]
  }
}

الخطوة 4. الاستخدام مع ttypescript (موصى به)

قم بتثبيت ttypescript للتحويل التلقائي:

npm install --save-dev ttypescript

ثم استبدل tsc بـ ttsc في نصوص package.json الخاصة بك:

{
  "scripts": {
    "build": "ttsc",
    "start": "node dist/index.js"
  }
}

هام: تتطلب typia إصدار TypeScript 4.4 أو أعلى. بدون المحوّل، لن تعمل المكتبة.

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

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

import typia from "typia";

// تعريف الواجهة
interface IUser {
  id: number;
  name: string;
  email: string;
  age: number;
  isActive: boolean;
}

// إنشاء دالة التحقق
const validateUser = typia.createValidate<IUser>();

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

// التحقق
const result = validateUser(testData);

if (result.success) {
  console.log("البيانات صالحة:", result.data);
} else {
  console.log("خطأ في التحقق:", result.errors);
}

// مثال مع بيانات غير صحيحة
const badData = {
  id: "ليس رقماً", // يجب أن يكون number
  name: "أحمد",
  email: "ليس بريداً إلكترونياً",
  age: -5,
  isActive: "نعم", // يجب أن يكون boolean
};

const badResult = validateUser(badData);
console.log("الأخطاء:", badResult.errors);

يوضح هذا المثال مدى سهولة التحقق من البيانات باستخدام واجهة TypeScript فقط. لا حاجة لمخططات إضافية أو ديكوراتورز!