Mongoose Paginate para JavaScript (Node.js): guia completo com exemplos

Bem-vindo ao PythonLib! Hoje vamos explorar o Mongoose Paginate — uma das bibliotecas mais populares para implementar paginação em aplicações Node.js que utilizam Mongoose ODM (Object Data Modeling) para MongoDB.

1. O que é e por que usar

Mongoose Paginate é um plugin leve para Mongoose que adiciona o método paginate() aos seus schemas. Ele permite dividir facilmente grandes conjuntos de dados em páginas, evitando carregar todos os documentos de uma vez.

Por que isso é necessário? Em aplicações reais (blogs, e-commerces, APIs), os bancos de dados contêm milhares, às vezes milhões de registros. Carregar tudo simultaneamente resulta em:

• Alta carga no servidor (memória, processador).
• API lenta (o usuário espera minutos pela resposta).
• Má experiência do usuário (scroll infinito sem paginação ou botões "Próximo").

O Mongoose Paginate resolve esses problemas fornecendo uma implementação de paginação pronta, testada e flexível. Ele calcula automaticamente o total de documentos, retorna a página solicitada e fornece meta-informações (página atual, total de páginas, se existe próxima/anterior).

2. Instalação

A instalação é feita via npm (Node Package Manager). Certifique-se de ter Node.js e npm instalados.

npm install mongoose-paginate-v2

Importante: Existem duas versões da biblioteca:

• mongoose-paginate — versão antiga, com menos suporte.
• mongoose-paginate-v2 — versão atual, recomendada, com mais recursos e correções.

Neste artigo, usaremos o mongoose-paginate-v2.

3. Início rápido — exemplo mínimo funcional

Vamos criar um modelo simples "Usuário" e aplicar paginação a ele.

// 1. Importar dependências
const mongoose = require('mongoose');
const mongoosePaginate = require('mongoose-paginate-v2');

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

// 3. Adicionar o plugin de paginação ao schema
userSchema.plugin(mongoosePaginate);

// 4. Criar o modelo
const User = mongoose.model('User', userSchema);

// 5. Conectar ao MongoDB (exemplo com banco local)
async function main() {
    await mongoose.connect('mongodb://localhost:27017/testdb');

    // 6. Inserir dados de teste (se não existirem)
    const count = await User.countDocuments();
    if (count === 0) {
        const users = [];
        for (let i = 1; i <= 50; i++) {
            users.push({ name: `Usuário ${i}`, email: `usuario${i}@exemplo.com`, age: 20 + (i % 30) });
        }
        await User.insertMany(users);
        console.log('50 usuários inseridos');
    }

    // 7. Usar paginação
    const options = {
        page: 1,      // Número da página (padrão: 1)
        limit: 10,    // Itens por página (padrão: 10)
    };

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

    console.log('Resultado da paginação:');
    console.log('Documentos:', result.docs);
    console.log('Total de documentos:', result.totalDocs);
    console.log('Total de páginas:', result.totalPages);
    console.log('Página atual:', result.page);
    console.log('Tem próxima página:', result.hasNextPage);
    console.log('Tem página anterior:', result.hasPrevPage);

    await mongoose.disconnect();
}

main().catch(console.error);

Este código cria 50 usuários e depois solicita a primeira página com 10 usuários. No console, você verá não apenas os documentos, mas também as meta-informações.