mongodb-paginate

library1.4.0jsnpmunverified

A library for MongoDB aggregation with built-in pagination, using the $facet operator to efficiently combine filtering, counting, and data retrieval in a single query. Version 1.4.0 supports raw MongoDB, Mongoose, and TypeScript. It organizes pipelines into pre-paging (filters), facet (count + data split), and post-paging (lookups/expensive ops) stages to minimize pipeline size early. Differentiates from mongoose-paginate by focusing on aggregation pipelines rather than simple find queries.

database

npm install mongodb-paginate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-PAGINATE

mongodb-paginate

databasejavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

paginate

✓ import paginate from 'mongodb-paginate'

✗ const paginate = require('mongodb-paginate')

ESM-only package; default import is the main paginate function.

dbConnection

✓ import { dbConnection } from 'mongodb-paginate'

Used to set database URL and name for raw MongoDB when passing collection name as string.

PaginationOptions

✓ import type { PaginationOptions } from 'mongodb-paginate'

TypeScript type for paging options like page and limit.

Shows raw MongoDB pagination with pre-paging filter, post-paging lookup, and paging options.

import paginate, { dbConnection } from 'mongodb-paginate'; // Set database connection details (only for raw MongoDB with string collection name) dbConnection.url = 'mongodb://127.0.0.1:27017'; dbConnection.dbName = 'test'; const prePagingStage = [ { $match: { featured: true } } ]; const postPagingStage = [ { $lookup: { from: 'category', localField: 'category', foreignField: '_id', as: 'category' } } ]; const pagingOptions = { page: 1, limit: 10 }; async function run() { const result = await paginate('product', prePagingStage, postPagingStage, pagingOptions); console.log(result); } run();

Debug

Known issues

breakingThe function signature expects prePagingStage and postPagingStage as separate arrays; mixing them will break pagination logic.

fix

Ensure all filtering stages are in prePagingStage and all post-paging stages (lookups, etc.) are in postPagingStage.

affects: >=1.0.0

gotchaWhen using Mongoose, pass the model directly, not the collection object; otherwise, $facet may not work correctly.

fix

Use: paginate(MyModel, prePagingStage, postPagingStage, pagingOptions)

affects: >=1.0.0

deprecatedSetting dbConnection properties globally is not thread-safe; future versions may require passing connection options to paginate().

fix

Consider passing collection instance directly instead of relying on dbConnection global.

affects: >=1.0.0

gotchaThe result object's 'pages' count may be 0 if total documents is 0, but 'page' still reports the requested page number.

fix

Always check result.totalDocs > 0 before assuming result.pages >= 1.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: dbConnection.url is not configurable

Trying to set dbConnection.url after first use (module caching).

fix

Set dbConnection.url and dbName before any paginate call, ideally at app startup.

MongoError: $facet is not allowed in this pipeline

Used $facet inside a pre-built pipeline that already contains $facet or in a non-supporting MongoDB version.

fix

Ensure MongoDB version >= 3.4 and do not embed $facet in prePagingStage or postPagingStage.

TypeError: paginate is not a function

Using CommonJS require() with an ESM-only package.

fix

Use dynamic import: const paginate = (await import('mongodb-paginate')).default;

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

mongooseoptionalOptional peer dependency when using Mongoose models

mongodboptionalRequired for raw MongoDB driver usage

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ImtiazChowdhury/mongo-paginate ↗

packagemongodb-paginate ↗

homepagehttps://github.com/ImtiazChowdhury/mongo-paginate#readme ↗