Docs Menu

Docs HomeNode.js

What's New

On this page

  • What's New in 4.12
  • What's New in 4.11
  • What's New in 4.10
  • What's New in 4.9
  • What's New in 4.8
  • What's New in 4.7
  • What's New in 4.6
  • What's New in 4.5
  • What's New in 4.4
  • What's New in 4.3
  • What's New in 4.2
  • What's New in 4.1
  • What's New in 4.0
  • What's New in 3.7
  • What's New in 3.6

Learn what's new in:


Upgrade Driver to Version 4.12.1

The 4.12.1 Node.js driver includes a fix to a regression in monitoring logic that could cause processes to crash.

New features of the 4.12 Node.js driver release include:

  • Redefinition of the ChangeStream class as an async iterable. You can use ChangeStream instances in any context that expects an AsyncIterator.

    • Notably, change streams can now be used in Javascript for-await loops:

      const changeStream =;
      for await (const change of changeStream) {
      console.log("Received change: ", change);
  • Fix to server monitoring when the driver skips monitoring events. In this release, the driver always updates its view of the topology when processing monitoring events.

  • Performance improvements with buffering as a result of modification to data structures used internally in the driver.

To learn more, see the v4.12.0 Release Highlights.

The 4.11 Node.js driver release includes recursive schema support, meaning that you can use recursive types as the schema in the Collection class. The driver also provides type safety for dot notation queries up to a depth of nine in this release. Typescript compiles your code beyond a depth of nine, but types fall back to any at this level. The recursive type depth limit is a current limitation in TypeScript.

Suppose we have a collection of type Collection<CircularSchema>:

interface CircularSchema {
name: string;
ref: CircularSchema;

TypeScript enforces type checking below a depth of nine. The following code causes a TypeScript compilation error because the name property value must be a string type:

collection.findOne({ '': 25 })

At a depth greater than nine, TypeScript compiles your code but no longer type checks it. The following code assigns an int to a string property but does not cause a compilation error because the referenced property is at a depth of 11:

'': 25

To learn more, see the v4.11.0 Release Highlights.

New features of the 4.10 Node.js driver release include:

  • Callback Deprecation

    • Callbacks are now deprecated in favor of Promises. Callbacks will be removed in the next major release. The Node driver team recommends migrating to promises where possible:

      • Use async/await syntax.

      • Use the Node.js callbackify utility:

        require('util').callbackify(() => collection.findOne())(callback)
      • Use then syntax:

        collection.findOne().then(res => callback(null, res), err => callback(err))
    • If you are unable to migrate to Promises in a large codebase, you can use the MongoDB Node.js driver with optional callback support package.

To learn more, see v4.10.0 Release Highlights.

New features of the 4.9 Node.js driver release include:

  • Fixed an inconsistency with writeConcern options in the type definitions.

  • Included the latest BSON release, which adds automatic UUID support. See the BSON release notes here.

To learn more, see v4.9.0 Release Highlights.

New features of the 4.8 Node.js driver release include:

  • Added auto-completion and type safety for nested keys in an update filter

  • client.startSession() can now be called before connecting to MongoDB

  • estimatedDocumentCount() method can now accept a comment

To learn more, see v4.8.0 Release Highlights.

New features of the 4.7 Node.js driver release include:

  • The MongoClient.connect() method is now optional when connecting to your MongoDB instance

  • Ability to compress messages with the Zstandard compression algorithm

  • Added support for the maxConnecting connection option

  • Ability for change stream documents to show your documents before and after an update

  • Added support for new change stream fields related to Cluster to Cluster Replication

  • The estimatedDocumentCount() method now uses the $count database command

  • Improved connecting to MongoDB in the AWS Lambda Init phase


Deprecation Notice

The ResumeOptions interface is deprecated. Use the ChangeStreamCursorOptions interface instead.

New features of the 4.6 Node.js driver release include:

  • Improved the ChangeStreamDocument in TypeScript.

  • Even distribution of server selection based on load across servers.

To learn more, see v4.6.0 Release Highlights.

See v4.5.0 Release Highlights on GitHub.

New features of the 4.4 Node.js driver release include:

  • KMIP provider support when using CSFLE.

  • TLS support when using CSFLE.

  • Hostname canonicalization now accepts "none", "forward", and "forwardAndReverse" as authMechanismProperties when using GSSAPI.

  • In the 4.0.0 release of the driver, the deprecated collection.count() method was inadvertently changed to behave like collection.countDocuments(). In this release, the collection.count() method is updated to match legacy behavior:

    • If a query is provided, collection.count() behaves the same as collection.countDocuments() and performs a collection scan.

    • If no query is provided, collection.count() behaves the same as collection.estimatedDocumentCount() and relies on collection metadata.


    Deprecation Notice

    The cursor.count() method is deprecated and will be removed in the next major version, along with collection.count(). Use the collection.estimatedDocumentCount() or collection.countDocuments() methods instead.

New features of the 4.3 Node.js driver release include:

New features of the 4.2 Node.js driver release include:

New features of the 4.1 Node.js driver release include:

  • Added load balanced connection support for all cluster types including the beta Serverless platform.

  • Added support for the advanceClusterTime() method to determine if the ClientSession should update its cluster time.


In this release of the driver, the deprecated collection.count() method was inadvertently changed to behave like collection.countDocuments(). This behavior is corrected in version 4.4.

New features of the 4.0 Node.js driver release include:

  • We've migrated the driver to TypeScript. You can now harness the type hinting and intellisense features in editors that support it to develop your MongoDB applications. Enjoy the benefits of this work in pure JavaScript projects as well.

  • The underlying BSON library used by this version is now migrated to TypeScript.

  • Inline documentation is now consistently formatted to improve display in editors.

  • If you are a user of the community types @types/mongodb, there will likely be issues adopting the types from our codebase. We could not achieve a one to one match in types due to the details of writing the codebase in TypeScript.

We'd love to hear your TypeScript related feature requests. Please submit ideas on our JIRA project here.

The minimum supported version of Node.js is now v12.9 or greater for version 4 of the driver. Support for our 3.x branches will continue until summer 2022 to allow time to upgrade.


3.x supports back to Node.js v4.

Our Cursor implementation is now updated to make it clear what is possible before and after execution of an operation.


const fc = collection.find({a: 2.3}).skip(1)
for await (const doc of fc) {
fc.limit(1) // incorrect usage, cursor already executing

There was inconsistency surrounding how the cursor would error if a setting was applied after cursor execution began. Now, the cursor will throw an error when attempting to apply operations in an invalid state, similar to the following:

MongoError: Cursor is already initialized

  • Affected classes:

    • AbstractCursor

    • FindCursor

    • AggregationCursor

    • ChangeStreamCursor (This is the underlying cursor for ChangeStream)

    • ListCollectionsCursor

Our Cursor types no longer extend Readable directly. They must be transformed into a stream by calling


const cursor = collection.find({})
const stream =
stream.on("data", data => console.log)
stream.on("error", () => client.close())

Use hasNext() and next() for manual iteration. Use for await of syntax or any Promise helpers for asynchronous iteration.

With type hinting, you should find that options passed to a MongoClient are enumerated and discoverable. We've made a large effort to process all options in the driver to give early warnings about incompatible settings to get your app up and running in a correct state quickly.

  • checkServerIdentity is no longer checked before being passed to the underlying Node API. Previously, accepted values were false, or a function. Now, the argument must be a function. Specifying a boolean will result in an error being thrown.

  • It is longer required to specify useUnifiedTopology or useNewUrlParser.

This method no longer supports a strict option, which returned an error if the collection did not exist. To assert the existence of a collection, use the listCollections() method instead.


const collections = (await db.listCollections({}, { nameOnly: true })
({name}) => name
if (!collections.includes(myNewCollectionName)) {
throw new Error(`${myNewCollectionName} doesn't exist`);

BulkWriteError is now renamed to MongoBulkWriteError.

When running bulk operations that make writes you can encounter errors depending on your settings. Import the new class name MongoBulkWriteError when testing for errors in bulk operations.

DB is no longer an EventEmitter. Listen for events directly from your MongoClient instance.

The helper, deprecated since MongoDB 3.4, is now removed. Use the aggregation pipeline $group operator instead.

  • gssapiServiceName is now removed. Use authMechanismProperties.SERVICE_NAME in the URI or as an option on MongoClientOptions.


    // or
    new MongoClient(url, { SERVICE_NAME: "alternateServiceName" })
  • Specifying username and password as options is only supported in the URI or as an option on MongoClientOptions.


    new MongoClient("mongodb://username:password@<host><port>")
    // or
    new MongoClient(url, { auth: { username: "<>", password: "<>" } })

The GridStore API (already deprecated in 3.x) is now replaced with GridFSBucket. For more information on GridFS, see the mongodb manual.

Below are some snippets that represent equivalent operations.


// old way
const gs = new GridStore(db, filename, mode[, options])
// new way
const bucket = new GridFSBucket(client.db('test')[,options])

GridFSBucket uses the Node.js Stream API. You can replicate file seeking by using the start and end options, creating a download stream from your GridFSBucket.


bucket.openDownloadStreamByName(filename, { start: 0, end: 100 })


await client.connect();
const filename = 'test.txt'; // whatever local file name you want
const db = client.db();
const bucket = new GridFSBucket(db);
.on('error', console.error)
.on('finish', () => {
console.log('done writing to db!');
.then(files => {
.pipe(fs.createWriteStream('downloaded_' + filename))
.on('error', console.error)
.on('finish', () => {
console.log('done downloading!');


GridFSBucket does not need to be closed like GridStore.


// old way
GridStore.unlink(db, name, callback);
// new way

File metadata that used to be accessible on the GridStore instance can be found by querying the bucket.


const fileMetaDataList: GridFSFile[] = bucket.find({}).toArray();
  • We internally now only manage a unifiedTopology when you connect to a mongod. The differences between this and previous versions is detailed here.

  • It is longer required to specify useUnifiedTopology or useNewUrlParser.

  • You must use the new directConnection option to connect to uninitialized replica set members.

Support is now added for fine-grained verbosity modes. You can learn more about each mode here.

The instrument() method is now removed. Use command monitoring instead. See our guide on command monitoring for more information.

For a detailed list of breaking changes, removals, and associated JIRA tickets, see the detailed list here.

New features of the 3.7 Node.js driver release include:

  • Added support for load balancer mode while enabling the useUnifiedTopology option

  • Added support for Stable API while enabling the useUnifiedTopology option

New features of the 3.6 Node.js driver release include:

  • Added support for the MONGODB-AWS authentication mechanism using Amazon Web Services (AWS) Identity and Access Management (IAM) credentials

  • Added support for Online Certificate Status Protocol (OCSP)

  • The find() method supports allowDiskUse() for sorts that require too much memory to execute in RAM

  • The update() and replaceOne() methods support index hints

  • A reduction in recovery time for topology changes and failover events

  • Improvements in validation testing for the default writeConcern

  • Authentication requires fewer round trips to the server, resulting in faster connection setup

  • Shorter Salted Challenge Response Authentication Mechanism (SCRAM) conversations

  • Ability to create collections and indexes for multiple document transactions

  • Running validation for a collection in the background

←  Compatibility
Share Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.