mongodb-legacy
v6.1.3
Published
The legacy MongoDB driver with callback support for Node.js
Downloads
33,078
Readme
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:
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 onmongodb
. 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 ofmongodb
is installed. If users wish to control the version ofmongodb
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 [email protected] 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.
| | [email protected]
| [email protected]
| [email protected]
|
| ------------- | -------------------- | -------------------- | -------------------- |
| [email protected]
| N/A | N/A | ✓ |
| [email protected]
| N/A | ✓ | N/A |
| [email protected]
| ✓ | N/A | N/A |
| [email protected]
| 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
:copyright: 2022-present MongoDB