chore(main): release 6.9.0 [skip-ci]

[github-actions]

🌱 A new release!

6.9.0 (2024-09-06)

The MongoDB Node.js team is pleased to announce version 6.9.0 of the mongodb package!

Release Notes

Driver support of upcoming MongoDB server release

Increased the driver's max supported Wire Protocol version and server version in preparation for the upcoming release of MongoDB 8.0.

MongoDB 3.6 server support deprecated

Warning

Support for 3.6 servers is deprecated and will be removed in a future version.

Support for explicit resource management

The driver now natively supports explicit resource management for MongoClient, ClientSession, ChangeStreams and cursors. Additionally, on compatible Node.js versions, explicit resource management can be used with cursor.stream() and the GridFSDownloadStream, since these classes inherit resource management from Node.js' readable streams.

This feature is experimental and subject to changes at any time. This feature will remain experimental until the proposal has reached stage 4 and Node.js declares its implementation of async disposable resources as stable.

To use explicit resource management with the Node driver, you must:

• Use Typescript 5.2 or greater (or another bundler that supports resource management)
• Enable tslib polyfills for your application
• Either use a compatible Node.js version or polyfill Symbol.asyncDispose (see the TS 5.2 release announcement for more information).

Explicit resource management is a feature that ensures that resources' disposal methods are always called when the resources' scope is exited. For driver resources, explicit resource management guarantees that the resources' corresponding close method is called when the resource goes out of scope.

// before:
{
  try {
    const client = MongoClient.connect('<uri>');
    try {
      const session = client.startSession();
      const cursor = client.db('my-db').collection("my-collection").find({}, { session });
      try {
        const doc = await cursor.next();
      } finally {
        await cursor.close();
      }
    } finally {
      await session.endSession();
    }
  } finally {
    await client.close();
  }
}

// with explicit resource management:
{
  await using client = MongoClient.connect('<uri>');

  await using session = client.startSession();
  await using cursor = client.db('my-db').collection('my-collection').find({}, { session });

  const doc = await cursor.next();
}
// outside of scope, the cursor, session and mongo client will be cleaned up automatically.

The full explicit resource management proposal can be found here.

Driver now supports auto selecting between IPv4 and IPv6 connections

For users on Node versions that support the autoSelectFamily and autoSelectFamilyAttemptTimeout options (Node 18.13+), they can now be provided to the MongoClient and will be passed through to socket creation. autoSelectFamily will default to true with autoSelectFamilyAttemptTimeout by default not defined. Example:

const client = new MongoClient(process.env.MONGODB_URI, { autoSelectFamilyAttemptTimeout: 100 });

Allow passing through allowPartialTrustChain Node.js TLS option

This option is now exposed through the MongoClient constructor's options parameter and controls the X509_V_FLAG_PARTIAL_CHAIN OpenSSL flag.

Fixed enableUtf8Validation option

Starting in v6.8.0 we inadvertently removed the ability to disable UTF-8 validation when deserializing BSON. Validation is normally a good thing, but it was always meant to be configurable and the recent Node.js runtime issues (v22.7.0) make this option indispensable for avoiding errors from mistakenly generated invalid UTF-8 bytes.

Add duration indicating time elapsed between connection creation and when the connection is ready

ConnectionReadyEvent now has a durationMS property that represents the time between the connection creation event and when the connection ready event is fired.

Add duration indicating time elapsed between the beginning and end of a connection checkout operation

ConnectionCheckedOutEvent/ConnectionCheckFailedEvent now have a durationMS property that represents the time between checkout start and success/failure.

Create native cryptoCallbacks 🔐

Node.js bundles OpenSSL, which means we can access the crypto APIs from C++ directly, avoiding the need to define them in JavaScript and call back into the JS engine to perform encryption. Now, when running the bindings in a version of Node.js that bundles OpenSSL 3 (should correspond to Node.js 18+), the cryptoCallbacks option will be ignored and C++ defined callbacks will be used instead. This improves the performance of encryption dramatically, as much as 5x faster. 🚀

This improvement was made to [email protected] which is available now!

Only permit mongocryptd spawn path and arguments to be own properties

We have added some defensive programming to the options that specify spawn path and spawn arguments for mongocryptd due to the sensitivity of the system resource they control, namely, launching a process. Now, mongocryptdSpawnPath and mongocryptdSpawnArgs must be own properties of autoEncryption.extraOptions. This makes it more difficult for a global prototype pollution bug related to these options to occur.

Support for range v2: Queryable Encryption supports range queries

Queryable encryption range queries are now officially supported. To use this feature, you must:

• use a version of mongodb-client-encryption > 6.1.0
• use a Node driver version > 6.9.0
• use an 8.0+ MongoDB enterprise server

Important

Collections and documents encrypted with range queryable fields with a 7.0 server are not compatible with range queries on 8.0 servers.

Documentation for queryable encryption can be found in the MongoDB server manual.

insertMany and bulkWrite accept ReadonlyArray inputs

This improves the typescript developer experience, developers tend to use ReadonlyArray because it can help understand where mutations are made and when enabling noUncheckedIndexedAccess leads to a better type narrowing experience.

Please note, that the array is read only but not the documents, the driver adds _id fields to your documents unless you request that the server generate the _id with forceServerObjectId

Fix retryability criteria for write concern errors on pre-4.4 sharded clusters

Previously, the driver would erroneously retry writes on pre-4.4 sharded clusters based on a nested code in the server response (error.result.writeConcernError.code). Per the common drivers specification, retryability should be based on the top-level code (error.code). With this fix, the driver avoids unnecessary retries.

The LocalKMSProviderConfiguration's key property accepts Binary for auto encryption

In #4160 we fixed a type issue where a local KMS provider at runtime accepted a BSON Binary instance but the Typescript inaccurately only permitted Buffer and string. The same change has now been applied to AutoEncryptionOptions.

BulkOperationBase (superclass of UnorderedBulkOperation and OrderedBulkOperation) now reports length property in Typescript

The length getter for these classes was defined manually using Object.defineProperty which hid it from typescript. Thanks to @sis0k0 we now have the getter defined on the class, which is functionally the same, but a greatly improved DX when working with types. 🎉

MongoWriteConcernError.code is overwritten by nested code within MongoWriteConcernError.result.writeConcernError.code

MongoWriteConcernError is now correctly formed such that the original top-level code is preserved

• If no top-level code exists, MongoWriteConcernError.code should be set to MongoWriteConcernError.result.writeConcernError.code
• If a top-level code is passed into the constructor, it shouldn't be changed or overwritten by the nested writeConcernError.code

Optimized cursor.toArray()

Prior to this change, toArray() simply used the cursor's async iterator API, which parses BSON documents lazily (see more here). toArray(), however, eagerly fetches the entire set of results, pushing each document into the returned array. As such, toArray does not have the same benefits from lazy parsing as other parts of the cursor API.

With this change, when toArray() accumulates documents, it empties the current batch of documents into the array before calling the async iterator again, which means each iteration will fetch the next batch rather than wrap each document in a promise. This allows the cursor.toArray() to avoid the required delays associated with async/await execution, and allows for a performance improvement of up to 5% on average! 🎉

Note: This performance optimization does not apply if a transform has been provided to cursor.map() before toArray is called.

Fixed mixed use of cursor.next() and cursor[Symbol.asyncIterator]

In 6.8.0, we inadvertently prevented the use of cursor.next() along with using for await syntax to iterate cursors. If your code made use of the following pattern and the call to cursor.next retrieved all your documents in the first batch, then the for-await loop would never be entered. This issue is now fixed.

const firstDoc = await cursor.next();

for await (const doc of cursor) {
    // process doc
    // ...
}

Features

• NODE-5459: add durations to connection pool events (#4166) (7295695)
• NODE-5614: add support for explicit resource management (#4177) (b3f3987)
• NODE-5754: allow auto select family options (#4185) (54efb7d)
• NODE-5908: support range v2 (#4141) (de253a7)
• NODE-6225: add property ownership check before referencing mongocryptdSpawnPath and mongocryptdSpawnArgs (#4151) (f48f8d3)
• NODE-6244: Bump max supported wire version and server version (#4163) (45bc098)
• NODE-6252: insertMany and bulkWrite permit readonly arrays (#4175) (4b219d3)
• NODE-6278: deprecate 3.6 servers (#4178) (35d8840)
• NODE-6309: Mark range API as stable (#4190) (f53e9d9)
• NODE-6365: pass through allowPartialTrustChain TLS flag (#4228) (d6c147d)

Bug Fixes

• NODE-5720: on pre-4.4 sharded servers, the node driver uses error.writeConcern.code to determine retryability (#4155) (b26c328)
• NODE-6241: allow Binary as local kms provider key for auto encryption (#4165) (d85f827)
• NODE-6259: replace dynamically assigned length property with a static getter (#4173) (320dde0)
• NODE-6276: preserve top level error code MongoWriteConcernError (#4183) (e902584)
• NODE-6284: make sparsity and trimFactor optional (#4189) (8622545)
• NODE-6355: respect utf8 validation options when iterating cursors (#4214) (8bfe187)
• NODE-6362: cache cursor deserialization options across deserialize calls (#4221) (833eaa4)
• NODE-6367: enable mixed use of iteration APIs (#4231) (08912c8)

Performance Improvements

• NODE-5906: optimize toArray to use batches (#4171) (5565d50)

Documentation

• Reference
• API
• Changelog

We invite you to try the mongodb library immediately, and report any issues to the NODE project.

---

[baileympearson]

run release_notes

[dariakp]

run release_notes

[nbbeeken]

run release_notes

[github-actions]

🤖 Created releases:

• v6.9.0
  🌻