Mongoose Paginate para JavaScript (Node.js): guía completa con ejemplos

¡Bienvenido a PythonLib! Hoy vamos a explorar Mongoose Paginate, una de las librerías más populares para implementar paginación en aplicaciones Node.js que usan Mongoose ODM (Object Data Modeling) para MongoDB.

1. ¿Qué es y para qué sirve?

Mongoose Paginate es un plugin ligero para Mongoose que añade el método paginate() a tus esquemas. Te permite dividir fácilmente grandes conjuntos de datos en páginas, evitando cargar todos los documentos de una sola vez.

¿Por qué es necesario? En aplicaciones reales (blogs, tiendas online, APIs), las bases de datos contienen miles, a veces millones de registros. Cargarlos todos al mismo tiempo implica:

Gran carga en el servidor (memoria, CPU).
API lenta (el usuario espera la respuesta durante minutos).
Mala experiencia de usuario (scroll infinito sin paginación o botones "Siguiente").

Mongoose Paginate resuelve estos problemas ofreciendo una implementación de paginación lista para usar, probada y flexible. Calcula automáticamente el total de documentos, devuelve la página solicitada y proporciona metainformación (página actual, total de páginas, si existe página siguiente/anterior).

2. Instalación

La instalación se realiza a través de npm (Node Package Manager). Asegúrate de tener Node.js y npm instalados previamente.

npm install mongoose-paginate-v2

Importante: Existen dos versiones de la librería:

mongoose-paginate — versión antigua, con menos soporte.
mongoose-paginate-v2 — versión actual y recomendada, con más funcionalidades y correcciones.

En este artículo usaremos mongoose-paginate-v2.

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear un modelo simple "Usuario" y aplicarle paginación.

// 1. Importamos las dependencias
const mongoose = require('mongoose');
const mongoosePaginate = require('mongoose-paginate-v2');

// 2. Definimos el esquema
const userSchema = new mongoose.Schema({
    name: String,
    email: String,
    age: Number,
    createdAt: { type: Date, default: Date.now }
});

// 3. Agregamos el plugin de paginación al esquema
userSchema.plugin(mongoosePaginate);

// 4. Creamos el modelo
const User = mongoose.model('User', userSchema);

// 5. Nos conectamos a MongoDB (ejemplo con BD local)
async function main() {
    await mongoose.connect('mongodb://localhost:27017/testdb');

    // 6. Insertamos datos de prueba (si no existen)
    const count = await User.countDocuments();
    if (count === 0) {
        const users = [];
        for (let i = 1; i <= 50; i++) {
            users.push({ name: `Usuario ${i}`, email: `usuario${i}@example.com`, age: 20 + (i % 30) });
        }
        await User.insertMany(users);
        console.log('Se insertaron 50 usuarios');
    }

    // 7. Usamos la paginación
    const options = {
        page: 1,      // Número de página (por defecto 1)
        limit: 10,    // Cantidad de elementos por página (por defecto 10)
    };

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

    console.log('Resultado de la paginación:');
    console.log('Documentos:', result.docs);
    console.log('Total de documentos:', result.totalDocs);
    console.log('Total de páginas:', result.totalPages);
    console.log('Página actual:', result.page);
    console.log('¿Hay página siguiente?:', result.hasNextPage);
    console.log('¿Hay página anterior?:', result.hasPrevPage);

    await mongoose.disconnect();
}

main().catch(console.error);

Este código creará 50 usuarios y luego consultará la primera página con 10 usuarios. En la consola verás no solo los documentos, sino también la metainformación.