reflect-metadata في TypeScript: دليل شامل مع أمثلة

مرحبًا بك في الدليل الشامل لمكتبة reflect-metadata الخاصة بـ TypeScript. تُعد هذه المكتبة حجر الأساس للعديد من الأطر الحديثة مثل Angular وNestJS وTypeORM. تتيح لك إمكانية إضافة وقراءة البيانات الوصفية (بيانات عن البيانات) للكلاسات والطرق والخصائص والمعاملات أثناء تشغيل البرنامج. إذا كنت تريد فهم كيفية عمل المُزينات (Decorators) وحقن التبعية (Dependency Injection) في TypeScript، فأنت بحاجة لإتقان reflect-metadata.

1. ما هي reflect-metadata ولماذا نحتاجها؟

reflect-metadata هي مكتبة توفر تطبيقًا (polyfill) للكائن المدمج Reflect، والذي يُعد جزءًا من مواصفات ES2016 (ES7). الهدف الرئيسي للمكتبة هو توفير واجهة برمجة تطبيقات (API) للتعامل مع البيانات الوصفية التي يمكن ربطها بعناصر الكود المختلفة (الكلاسات، الطرق، الخصائص). في JavaScript القياسي، هذه الوظيفة غير موجودة، لذا يتطلب TypeScript تثبيت حزمة منفصلة.

لماذا نحتاج هذا؟ تخيل أنك تكتب إطار عمل (Framework). تحتاج إلى معرفة التبعيات المطلوبة لكلاس معين، أو المسارات (routes) المرتبطة بطرق المتحكم (Controller)، أو الحقول التي يجب تحويلها إلى JSON. بدون البيانات الوصفية، سيكون عليك تخزين هذه المعلومات في ملفات تكوين منفصلة أو استخدام أنماط معقدة. reflect-metadata تسمح لك بتخزين هذه المعلومات مباشرة في الكود، مما يجعله أكثر توثيقًا ذاتيًا وأسهل للتحليل.

ترتبط المكتبة ارتباطًا وثيقًا بالمُزينات (Decorators). المُزين هو دالة تُطبق على كلاس أو طريقة أو خاصية. داخل المُزين، يمكنك استدعاء Reflect.defineMetadata لحفظ أي معلومات، ثم في مكان آخر من البرنامج، استخدام Reflect.getMetadata لاسترجاعها. هذا هو الأساس لتنفيذ حقن التبعية (Dependency Injection)، ورسم الخرائط العلائقية للكائنات (ORM)، والتحقق من الصحة (Validation)، والعديد من الأنماط الأخرى.

2. التثبيت

يتم تثبيت المكتبة عبر npm (Node Package Manager). تأكد من تثبيت Node.js (الإصدار 12 أو أحدث).

npm install reflect-metadata --save

بعد التثبيت، يجب استيراد المكتبة في بداية ملف الإدخال الخاص بك (عادةً main.ts أو index.ts) لتكون متاحة بشكل عام.

import "reflect-metadata";

هام: يجب أن يتم الاستيراد قبل أي كود آخر يستخدم Reflect. إذا كنت تستخدم إطار عمل (مثل Angular)، فسيقوم بذلك تلقائيًا نيابة عنك. بخلاف ذلك، أضف هذا السطر في بداية الملف.

يجب أيضًا تفعيل دعم المُزينات والبيانات الوصفية في ملف tsconfig.json:

{
  "compilerOptions": {
    "target": "ES6",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

العلامة emitDecoratorMetadata تجبر مترجم TypeScript على توليد بيانات وصفية للأنواع للعناصر المُزينة. هذا ضروري لعمل العديد من الأطر.

3. البداية السريعة — مثال عملي بسيط

لنقم بإنشاء مثال بسيط يوضح كيفية إضافة بيانات وصفية إلى كلاس وقراءتها.

import "reflect-metadata";

// 1. تعريف مفتاح للبيانات الوصفية
const METADATA_KEY = "my_custom_key";

// 2. إنشاء مُزين يضيف بيانات وصفية
function MyDecorator(value: string) {
    return function (target: any) {
        // target هو مُنشئ الكلاس
        Reflect.defineMetadata(METADATA_KEY, value, target);
    };
}

// 3. تطبيق المُزين على كلاس
@MyDecorator("هذا هو الكلاس الخاص بي")
class MyClass {
    greet() {
        console.l