Mongoose Paginate لجافا سكريبت (Node.js): دليل شامل مع أمثلة

مرحبًا بكم في PythonLib! سنشرح اليوم Mongoose Paginate — واحدة من أشهر المكتبات لتطبيق التقسيم إلى صفحات (Pagination) في تطبيقات Node.js التي تستخدم Mongoose ODM (Object Data Modeling) مع MongoDB.

1. ما هي هذه المكتبة ولماذا تحتاجها

Mongoose Paginate هي إضافة (Plugin) خفيفة الوزن لـ Mongoose، تضيف دالة paginate() إلى مخططاتك (Schemas). تتيح لك تقسيم مجموعات البيانات الكبيرة إلى صفحات بسهولة، وتجنب تحميل جميع المستندات دفعة واحدة.

لماذا تحتاجها؟ في التطبيقات الحقيقية (المدونات، المتاجر الإلكترونية، واجهات API)، تحتوي قواعد البيانات على آلاف بل ملايين السجلات. تحميلها كلها مرة واحدة يؤدي إلى:

ضغط هائل على الخادم (الذاكرة، المعالج).
بطء في أداء API (ينتظر المستخدم الرد لدقائق).
تجربة مستخدم سيئة (تمرير لا نهائي بدون أزرار "التالي" أو ترقيم صفحات).

Mongoose Paginate تحل هذه المشاكل بتوفير تطبيق جاهز ومختبر ومرن للتقسيم إلى صفحات. هي تحسب تلقائيًا العدد الإجمالي للمستندات، وتعيد الصفحة المطلوبة، وتوفر معلومات وصفية (الصفحة الحالية، إجمالي الصفحات، وجود صفحة تالية/سابقة).

2. التثبيت

يتم التثبيت عبر npm (Node Package Manager). تأكد من تثبيت Node.js و npm مسبقًا.

npm install mongoose-paginate-v2

ملاحظة مهمة: يوجد إصداران من المكتبة:

mongoose-paginate — الإصدار القديم، الأقل دعمًا.
mongoose-paginate-v2 — الإصدار الحديث والموصى به، مع ميزات وتحسينات أكثر.

في هذا المقال سنستخدم mongoose-paginate-v2.

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

لننشئ نموذجًا بسيطًا "مستخدم" ونطبق عليه التقسيم إلى صفحات.

// 1. استيراد التبعيات
const mongoose = require('mongoose');
const mongoosePaginate = require('mongoose-paginate-v2');

// 2. تعريف المخطط
const userSchema = new mongoose.Schema({
    name: String,
    email: String,
    age: Number,
    createdAt: { type: Date, default: Date.now }
});

// 3. إضافة إضافة التقسيم إلى صفحات للمخطط
userSchema.plugin(mongoosePaginate);

// 4. إنشاء النموذج
const User = mongoose.model('User', userSchema);

// 5. الاتصال بـ MongoDB (مثال مع قاعدة بيانات محلية)
async function main() {
    await mongoose.connect('mongodb://localhost:27017/testdb');

    // 6. إدراج بيانات اختبارية (إذا لم تكن موجودة)
    const count = await User.countDocuments();
    if (count === 0) {
        const users = [];
        for (let i = 1; i <= 50; i++) {
            users.push({ name: `مستخدم ${i}`, email: `user${i}@example.com`, age: 20 + (i % 30) });
        }
        await User.insertMany(users);
        console.log('تم إدراج 50 مستخدمًا');
    }

    // 7. استخدام التقسيم إلى صفحات
    const options = {
        page: 1,      // رقم الصفحة (الافتراضي 1)
        limit: 10,    // عدد العناصر في الصفحة (الافتراضي 10)
    };

    const result = await User.paginate({}, options);

    console.log('نتيجة التقسيم إلى صفحات:');
    console.log('المستندات:', result.docs);
    console.log('إجمالي المستندات:', result.totalDocs);
    console.log('إجمالي الصفحات:', result.totalPages);
    console.log('الصفحة الحالية:', result.page);
    console.log('هل توجد صفحة تالية:', result.hasNextPage);
    console.log('هل توجد صفحة سابقة:', result.hasPrevPage);

    await mongoose.disconnect();
}

main().catch(console.error);

هذا الكود سينشئ 50 مستخدمًا، ثم يستعلم عن الصفحة الأولى التي تحتوي على 10 مستخدمين. في وحدة التحكم، سترى ليس فقط المستندات نفسها، بل أيضًا المعلومات الوصفية.