Registry / database / mongodb-cross-cursor

mongodb-cross-cursor

library1.0.17jsnpmunverified

A MongoDB driver extension (v1.0.17) that enables consuming MongoDB cursors across multiple Node.js instances, useful in microservice environments. It works by leveraging internal MongoDB wire protocol commands to persist cursor state across restarts or upgrades. Unlike approaches using `limit/skip` (which become slow over large datasets) or range-based queries (costly across indexes), this package directly manipulates cursor internals. It supports mongoose peer dependency ^6 || ^7 || ^8 || ^9 and mongodb driver ^4 || ^5 || ^6 || ^7. Includes TypeScript types. Active development with occasional releases.

database

npm install mongodb-cross-cursor

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-CROSS-CURS

mongodb-cross-cursor

databasejavascriptv1.0.17

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.

initiate

✓ import { initiate } from 'mongodb-cross-cursor';

✗ const initiate = require('mongodb-cross-cursor').initiate;

Both ESM and CJS supported; named export.

MongoCrossCursor

✓ import MongoCrossCursor from 'mongodb-cross-cursor';

✗ const MongoCrossCursor = require('mongodb-cross-cursor').MongoCrossCursor;

Default export is the class; CJS users should use require('mongodb-cross-cursor') directly.

MongoCrossCursor class

✓ const instance = new MongoCrossCursor(sharedCursor, client, dbName, collectionName, batchSize);

✗ const instance = new MongoCrossCursor(sharedCursor);

Constructor requires exactly 5 arguments: sharedCursor object, MongoClient, db name, collection name, batch size.

Demonstrates initiating a shared cursor and then resuming it with iteration.

import { MongoClient } from 'mongodb'; import MongoCrossCursor, { initiate } from 'mongodb-cross-cursor'; async function main() { const client = new MongoClient(process.env.MONGO_URI ?? 'mongodb://localhost:27017'); await client.connect(); const db = client.db('test'); const collection = db.collection('articles'); // Initiate a cursor const instance = await initiate(collection.find({ published: true })); const sharedCursor = instance.sharedCursor; // { sessionId, cursorId } console.log('Shared cursor:', sharedCursor); // Later, resume in same or different process const resumed = new MongoCrossCursor(sharedCursor, client, 'test', 'articles', 100); for await (const result of resumed.iterate()) { console.log(result); } await client.close(); } main().catch(console.error);

Debug

Known issues

breakingConstructor arguments changed between v0.x and v1.x; sharedCursor must contain both sessionId and cursorId fields.

fix

Ensure sharedCursor object has sessionId and cursorId properties.

affects: >=1.0.0

gotchaRequires mongodb driver version 4, 5, 6, or 7; does not support older versions.

fix

Upgrade mongodb driver to ^4 || ^5 || ^6 || ^7.

affects: >=1.0.0

deprecatedThe initiate function is the preferred method for creating cursors; constructing MongoCrossCursor directly for initial creation may be removed in future.

fix

Use initiate() to start a new cursor, then constructor only for resuming.

affects: >=1.0.0

gotchaThe iterate() method returns an async generator; forgetting to use for-await-of results in no iteration.

fix

Use 'for await (const doc of instance.iterate())' instead of 'for (const doc of instance.iterate())'.

affects: >=1.0.0

gotchaDo not close the MongoClient while iterating; the cursor will break.

fix

Ensure client stays connected until iteration completes.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: MongoCrossCursor is not a constructor

Using default import incorrectly; likely importing as {MongoCrossCursor} instead of default.

fix

Use: import MongoCrossCursor from 'mongodb-cross-cursor'; or const MongoCrossCursor = require('mongodb-cross-cursor');

Error: sharedCursor must have sessionId and cursorId

Passing an incomplete sharedCursor object.

fix

Ensure sharedCursor has both sessionId (string) and cursorId (string) fields.

MongoServerError: cursor not found

Cursor timed out or was killed on the server; mongodb-cursor-timeout or collection dropped.

fix

Increase cursor timeout settings via MongoDB driver options; ensure collection exists.

TypeError: instance.next is not a function

Using .next() on an instance that was created without calling initiate() or using wrong version.

fix

Use iterate() method instead of next(), or ensure you're using v1.x+ where next() may not be available.

Upgrade

Version history

1.0.17latest on npm

Audit

Dependencies

mongooseoptionalPeer dependency for Mongoose integration

mongodbrequiredPeer dependency - core MongoDB driver

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/crisp-oss/node-mongodb-native-cross-cursor ↗

packagemongodb-cross-cursor ↗

homepagehttps://github.com/crisp-oss/node-mongodb-native-cross-cursor#readme ↗