Typegoose لـ TypeScript: دليل شامل

Typegoose هي مكتبة غلاف قوية لـ Mongoose، تتيح لك تعريف نماذج MongoDB باستخدام الكلاسات (Classes) والديكورات (Decorators) في TypeScript. تحل هذه المكتبة مشكلة رئيسية في تطوير Node.js: عدم التوافق بين الكتابة الصارمة في TypeScript والطبيعة الديناميكية لـ Mongoose. بدلاً من تكرار الأنواع والمخططات يدويًا، يتيح لك Typegoose وصف النموذج مرة واحدة - ككلاس TypeScript، ويقوم تلقائيًا بإنشاء مخطط Mongoose منه.

لماذا تحتاج إلى هذا؟ أولاً، يقلل بشكل كبير من كمية الكود المتكرر. لم تعد بحاجة إلى كتابة واجهة منفصلة ومخطط منفصل - فكلاس TypeScript يؤدي كلا الوظيفتين. ثانيًا، يضمن Typegoose أمانًا كاملاً للأنواع في جميع المراحل: من إنشاء المستند إلى تنفيذ الاستعلامات. سيقوم محرر الأكواد (IDE) باقتراح الحقول والطرق وأنواعها، مما يمنع تقريبًا الأخطاء الناتجة عن الأخطاء الإملائية في أسماء الحقول أو أنواع البيانات غير الصحيحة. ثالثًا، تدعم المكتبة جميع إمكانيات Mongoose: الحقول الافتراضية (Virtuals)، الخطافات (Hooks pre/post)، الفهارس (Indexes)، populate، والوسائط الوسيطة (Middleware).

Typegoose مثالي للمشاريع الكبيرة التي تهم فيها قابلية صيانة الكود، وكذلك للفرق التي ترغب في الاستفادة من جميع مزايا البرمجة كائنية التوجه (OOP) في TypeScript. يتكامل بسهولة مع NestJS وExpress والأطر الأخرى، مما يوفر معيارًا موحدًا لوصف البيانات.

التثبيت

لتثبيت Typegoose وتبعياته، قم بتنفيذ الأمر التالي في الطرفية:

npm install @typegoose/typegoose mongoose
npm install -D @types/mongoose

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

yarn add @typegoose/typegoose mongoose
yarn add -D @types/mongoose

يتطلب Typegoose إصدار TypeScript 4.0 أو أعلى. تأكد من تفعيل الخيارات التالية في ملف tsconfig.json الخاص بك:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "commonjs"
  }
}

بداية سريعة

لنقم بإنشاء نموذج مستخدم بسيط وحفظه في MongoDB.

import { prop, getModelForClass } from '@typegoose/typegoose';
import mongoose from 'mongoose';

// 1. تعريف كلاس النموذج
class User {
  @prop({ required: true })
  public name!: string;

  @prop({ required: true, unique: true })
  public email!: string;

  @prop({ default: 0 })
  public age!: number;
}

// 2. الحصول على نموذج Mongoose
const UserModel = getModelForClass(User);

// 3. الاتصال بقاعدة البيانات والعمل عليها
async function main() {
  await mongoose.connect('mongodb://localhost:27017/test');

  // إنشاء مستخدم
  const user = await UserModel.create({
    name: 'أحمد',
    email: 'ahmed@example.com',
    age: 30,
  });

  console.log('تم الإنشاء:', user);

  // البحث عن مستخدم
  const found = await UserModel.findOne({ email: 'ahmed@example.com' });
  console.log('تم العثور:', found);
}

main().catch(console.error);

يوضح هذا المثال البسيط الفكرة الأساسية: كلاس User مع الديكور @prop يصف المخطط، ودالة getModelForClass تنشئ نموذج Mongoose جاهزًا للاستخدام.

الأساليب والوظائف الأساسية

1. @prop() — ديكور الخاصية

التوقيع: @prop(options?: PropOptions)

الوصف: يحدد حقلاً في مخطط Mongoose. يقبل كائن خيارات مشابه لخيارات الحقول في Mongoose (required, default, unique, ref, enum، إلخ).

import { prop } from '@typegoose/typegoose';

class Product {
  @prop({ required: true, type: String })
  public title!: string;

  @prop({ default: 0, min: 0 })
  public price!: number;

  @prop({ enum: ['active', 'inactive'], default: 'active' })
  public status!: string;
}

2.