Registry / database / mongodb-cursor-pagination

mongodb-cursor-pagination

library1.10.0jsnpmunverified

Cursor-based pagination for MongoDB collections, written in TypeScript. v1.10.0 (stable, actively maintained) follows the Relay cursor connection spec, providing cursor-based pagination as a more stable alternative to offset-based pagination (which can miss/duplicate items when data changes between pages). The package ships TypeScript types and offers two main functions: `findPaginated` for simple queries and `aggregatePaginated` for aggregation pipelines. Based on mongo-cursor-pagination but with a cleaner API that returns standard pagination metadata (hasNextPage, hasPreviousPage, startCursor, endCursor). Peer dependency on mongodb driver 6.x.

database

npm install mongodb-cursor-pagination

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-CURSOR-PAG

mongodb-cursor-pagination

databasejavascriptv1.10.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.

findPaginated

✓ import { findPaginated } from 'mongodb-cursor-pagination'

✗ import findPaginated from 'mongodb-cursor-pagination'

Named export; no default export. TypeScript types bundled. ESM-only since v1.

aggregatePaginated

✓ import { aggregatePaginated } from 'mongodb-cursor-pagination'

✗ const aggregatePaginated = require('mongodb-cursor-pagination').aggregatePaginated

Named export for aggregation pipelines. CJS not supported – this lib is ESM-only.

PaginationInput

✓ import { PaginationInput } from 'mongodb-cursor-pagination'

TypeScript type for the input parameters (first, after, last, before, skip, sortAscending, sortField, paginatedField).

Demonstrates cursor-based pagination using findPaginated with forward pagination (first + after) and TypeScript types.

import { MongoClient } from 'mongodb'; import { findPaginated } from 'mongodb-cursor-pagination'; async function paginate() { const client = await MongoClient.connect(process.env.MONGO_URI ?? 'mongodb://localhost:27017'); const db = client.db(); const collection = db.collection('users'); // Get first page let result = await findPaginated(collection, { first: 10, query: {}, sortAscending: false, }); console.log('First page:', result.pageInfo); // Next page using cursor if (result.pageInfo.hasNextPage) { result = await findPaginated(collection, { first: 10, after: result.pageInfo.endCursor, }); console.log('Second page:', result.pageInfo); } await client.close(); } paginate().catch(console.error);

Debug

Known issues

breakingv1.0.0 migrated from CommonJS to ESM only. No default export – use named imports.

fix

Replace require('mongodb-cursor-pagination') with import { findPaginated, aggregatePaginated } from 'mongodb-cursor-pagination'

affects: >=1.0.0

breakingv1.0.0 requires mongodb driver 6.x. v0.x used mongodb driver 5.x or earlier.

fix

Update mongodb peer dependency to ^6.0.0

affects: >=1.0.0

breakingv1.0.0 does not support aggregation cursors via findPaginated – use aggregatePaginated instead.

fix

For aggregation pipelines, use aggregatePaginated(collection, pipeline, options)

affects: >=1.0.0

gotchaThe 'query' option in findPaginated does not accept aggregate expressions – use 'filter' in MongoDB collection.find instead.

fix

Pass a plain filter object to the 'query' option. For complex filtering, consider using aggregatePaginated with $match.

affects: >=1.0.0

gotchaCursor encoding: the returned startCursor and endCursor are base64-encoded strings, not raw ObjectIds.

fix

Use the provided cursor values directly – do not decode them manually.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'mongodb-cursor-pagination'

Package not installed or resolution fails due to ESM-only nature in a CJS project.

fix

npm install mongodb-cursor-pagination && use import syntax. If using require, migrate to ESM or use dynamic import (import()).

TypeError: (0 , mongodb_cursor_pagination.findPaginated) is not a function

Incorrect import – likely used default import instead of named import.

fix

Change to: import { findPaginated } from 'mongodb-cursor-pagination'

Error: Cursor must be a valid cursor string

Passing an invalid or non-base64 value to 'after' or 'before' options.

fix

Use the cursor values from previous result.pageInfo.endCursor or startCursor directly.

Upgrade

Version history

1.10.0latest on npm

Audit

Dependencies

mongodbrequiredRuntime peer dependency: the pagination functions operate on MongoDB collections and aggregation cursors.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/murshidazher/mongo-cursor-pagination ↗

packagemongodb-cursor-pagination ↗

homepagehttps://github.com/murshidazher/mongo-cursor-pagination#readme ↗