class-transformer TypeScript: طرق، أمثلة، تثبيت

مقدمة عن class-transformer: ما هي ولماذا تحتاجها

class-transformer هي مكتبة قوية لـ TypeScript و JavaScript، تتيح لك تحويل الكائنات العادية (plain) إلى نسخ من الكلاسات والعكس. تحل مشكلة أساسية: عند التعامل مع بيانات من API أو قواعد البيانات أو ملفات JSON، تحصل على كائنات بسيطة بدون دوال أو أنواع. class-transformer "تُحيي" هذه البيانات، محوّلة إياها إلى كائنات كلاس كاملة مع التحقق والتحويل والتسلسل.

أبرز حالات الاستخدام:

تحويل JSON من API إلى كائنات كلاس محددة الأنواع — مثلاً، بعد استلام رد من REST API، يمكنك تحويل JSON تلقائياً إلى نسخ من نماذجك.
التحقق من البيانات وتحويلها — باستخدام الديكورات، يمكنك تحديد الحقول الإجبارية والتي تحتاج تحويل (مثل نص إلى رقم أو تاريخ).
تسلسل الكائنات إلى JSON — التحويل العكسي من نسخ الكلاسات إلى كائنات بسيطة لإرسالها للعميل أو حفظها.
التعامل مع الكائنات المتداخلة والمصفوفات — المكتبة تستطيع تحويل الهياكل المتداخلة بشكل تكراري.

غالباً ما تُستخدم class-transformer مع class-validator (للتحقق) وأطر العمل الشهيرة مثل NestJS و TypeORM و MikroORM.

التثبيت

يتم تثبيت المكتبة عبر npm أو yarn:

npm install class-transformer --save

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

yarn add class-transformer

لتفعيل الديكورات في TypeScript، يجب تفعيل دعم الديكورات التجريبية في ملف tsconfig.json:

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

يُوصى أيضاً بتثبيت reflect-metadata لضمان عمل الديكورات بشكل صحيح:

npm install reflect-metadata --save

وقم باستيراده في بداية تطبيقك (عادةً في الملف الرئيسي index.ts أو main.ts):

import 'reflect-metadata';

بداية سريعة مع مثال كود

لننشئ نموذج مستخدم بسيط ونحول بيانات JSON إلى نسخة من الكلاس.

import { plainToClass, Expose, Type } from 'class-transformer';
import 'reflect-metadata';

// تعريف كلاس User
class User {
    @Expose()
    id: number;

    @Expose()
    firstName: string;

    @Expose()
    lastName: string;

    @Expose()
    @Type(() => Date)
    createdAt: Date;

    // دالة الكلاس — متاحة فقط بعد التحويل
    getFullName(): string {
        return `${this.firstName} ${this.lastName}`;
    }
}

// بيانات مثال من API (كائن عادي)
const plainUser = {
    id: 1,
    firstName: 'أحمد',
    lastName: 'السيد',
    createdAt: '2024-01-15T10:30:00Z'
};

// تحويل الكائن العادي إلى نسخة من كلاس User
const userInstance = plainToClass(User, plainUser);

console.log(userInstance instanceof User); // true
console.log(userInstance.getFullName());   // "أحمد السيد"
console.log(userInstance.createdAt);       // كائن Date: Tue Jan 15 2024 13:30:00 GMT+0300

كما ترى، حصلنا على كائن كلاس كامل بالدوال والأنواع المحولة بشكل صحيح (النص الزمني أصبح كائن Date).