mongodb-legacy

MongoDB Node.js Driver with Optional Callback Support Legacy Package

Attention :memo:

This is a wrapper of the mongodb driver, if you are starting a new project you likely just want to use the driver directly:

• Driver Source
• Driver NPM Package

Upgrading to version 5? Take a look at our upgrade guide here!

Purpose

This package is intended to assist in migrating to promise based APIs. We have wrapped every driver method to continue offering the optional callback support some projects may be relying on to incrementally migrate to promises. Any new APIs added to the driver will not offer optional callback support. If callback usage is needed for any new APIs, we would suggest using .then/.catch or node's callbackify to get that desired API.

The main driver package mongodb will be dropping optional callback support in the next major version (v5) in favor of async/await syntax.

Drawbacks

• The legacy driver wraps the native driver, which may lead to a slight performance penalty.
• As discussed in the versioning section below, it is recommended that mongodb-legacy replace the direct dependency on mongodb. This allows for the legacy driver to automatically pull in features and fixes from the native driver. However, this also removes control of which version of mongodb is installed. If users wish to control the version of mongodb directly, the lockfile will need to be edited manually.

Example usage of equivalent callback and promise usage

// Just add '-legacy' to my mongodb import
import { MongoClient } from 'mongodb-legacy';
const client = new MongoClient();
const db = client.db();
const collection = db.collection('pets');

// Legacy projects may have intermixed API usage:
app.get('/endpoint_promises', (req, res) => {
  collection
    .findOne({})
    .then(result => {
      res.end(JSON.stringify(result));
    })
    .catch(error => {
      res.errorHandling(error);
    });
});

app.get('/endpoint_callbacks', (req, res) => {
  collection.findOne({}, (error, result) => {
    if (error) return res.errorHandling(error);
    res.end(JSON.stringify(result));
  });
});

How to install

In your existing project add mongodb-legacy to your package.json with the following command.

npm install mongodb-legacy

Release Integrity

Releases are created automatically and signed using the Node team's GPG key. This applies to the git tag as well as all release packages provided as part of a GitHub release. To verify the provided packages, download the key and import it using gpg:

gpg --import node-driver.asc

The GitHub release contains a detached signature file for the NPM package (named mongodb-legacy-X.Y.Z.tgz.sig).

The following command returns the link npm package.

npm view mongodb-legacy@vX.Y.Z dist.tarball

Using the result of the above command, a curl command can return the official npm package for the release.

To verify the integrity of the downloaded package, run the following command:

gpg --verify mongodb-legacy-X.Y.Z.tgz.sig mongodb-legacy-X.Y.Z.tgz

[!NOTE] No verification is done when using npm to install the package. The contents of the Github tarball and npm's tarball are identical.

Versioning

We recommend replacing your mongodb dependency with this one. This package uses caret semver range for the main mongodb package, (ex. ^4.10.0) which will adopt minor version bumps as they are released.

Users can expect to be able to upgrade to v5 or later adopting the changes and features shipped in that version while using this module to maintain any callback code they still need to work on migrating.

MongoDB Node.js Driver Version Compatibility Table

The following version combinations with the MongoDB Node.js Driver are considered stable.

	mongodb-legacy@4.x	mongodb-legacy@5.x	mongodb-legacy@6.x
mongodb@6.x	N/A	N/A	✓
mongodb@5.x	N/A	✓	N/A
mongodb@4.x	✓	N/A	N/A
mongodb@3.x	N/A	N/A	N/A

API

The API is inherited from the driver, which is documented here. If it is relevant to inspect the precise differences, you can peruse the type definitions of wrapped APIs.

The wrappers are implemented as subclasses of each of the existing driver's classes with extra logic to handle the optional callback behavior. And all other driver exports are re-exported directly from the wrapper. This means any new APIs added to the driver will be automatically pulled in as long as the updated driver is installed.

Take this hypothetical example:

// Just add '-legacy' to my mongodb import
import { MongoClient } from 'mongodb-legacy';
const client = new MongoClient();
const db = client.db();

const collection = db.collection('pets');
// Returns an instance of LegacyFindCursor which is a subclass of FindCursor
const dogCursor = collection.find({ kind: 'dog' });
// Using .next with callbacks still works!
dogCursor.next((error, dog) => {
  if (error) return handling(error);
  console.log(dog);
});
// Brand new hypothetical api that pets all dogs! (does not support callbacks)
dogCursor.petAll().then(result => {
  console.log('all dogs got pats!');
});

NOTE: The petAll() api is brand new in this hypothetical example and so would not support an optional callback. If adopting this API is deep inside code that already relies on eventually calling a callback to indicate the end of an operation it is possible to use .then/.catch chains to handle the cases that are needed. We recommend offloading this complexity to node's callbackify utility: callbackify(() => dogCursor.petAll())(callback)

The new example petAll() API will be pulled in since we're building off the existing driver API. The typescript definitions work the same way so next() still reports its promise and callback variants and the petAll() API is pulled in from the driver's definitions.

Bugs or Features

You can reach out on our JIRA: https://jira.mongodb.org/projects/NODE and let us know any issues your run into while using this package.

License

Apache 2.0

:copyright: 2022-present MongoDB

Changelog

6.1.3 (2024-10-14)

Bug Fixes

• NODE-6420: support options for aggregationcursor/findcursor.explain() (#52) (99bd9ed)