diff --git a/README.md b/README.md index 1707f63e20f..aec488782fe 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,19 @@ The official [MongoDB](https://www.mongodb.com/) driver for Node.js. -**NOTE: v4.x was recently released with breaking API changes. You can find a list of changes [here](https://github.com/mongodb/node-mongodb-native/blob/4.0/HISTORY.md).** +**Upgrading to version 4? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/4.0/docs/CHANGES_4.0.0.md)!** ## Quick Links -| what | where | -|---------------|------------------------------------------------------------------------------------------------------------------| -| documentation | [https://docs.mongodb.com/drivers/node](https://docs.mongodb.com/drivers/node) | -| api-doc | [https://mongodb.github.io/node-mongodb-native/4.0/](https://mongodb.github.io/node-mongodb-native/4.0/) | -| npm package | [https://www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb) | -| source | [https://github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native) | -| mongodb | [https://www.mongodb.com](https://www.mongodb.com) | +| what | where | +| ------------- | ------------------------------------------------------------------------------------------------------ | +| documentation | [docs.mongodb.com/drivers/node](https://docs.mongodb.com/drivers/node) | +| api-doc | [mongodb.github.io/node-mongodb-native/4.0/](https://mongodb.github.io/node-mongodb-native/4.0/) | +| npm package | [www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb) | +| source | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native) | +| mongodb | [www.mongodb.com](https://www.mongodb.com) | +| changelog | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/4.0/docs/HISTORY.md) | +| upgrade to v4 | [docs/CHANGES_4.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/4.0/docs/CHANGES_4.0.0.md) | ### Bugs / Feature Requests @@ -103,7 +105,7 @@ For complete MongoDB installation instructions, see [the manual](https://docs.mo 1. Download the right MongoDB version from [MongoDB](https://www.mongodb.org/downloads) 2. Create a database directory (in this case under **/data**). -3. Install and start a ``mongod`` process. +3. Install and start a `mongod` process. ```bash mongod --dbpath=/data @@ -194,7 +196,7 @@ const filteredDocs = await collection.find({ a: 3 }).toArray() console.log('Found documents filtered by { a: 3 } =>', filteredDocs) ``` -Only the documents which match ``'a' : 3`` should be returned. +Only the documents which match `'a' : 3` should be returned. ### Update a document @@ -223,7 +225,7 @@ performance. The following function creates an index on the **a** field in the **documents** collection. ```js -const indexName = await collection.createIndex({a: 1}) +const indexName = await collection.createIndex({ a: 1 }) console.log('index name =', indexName) ``` diff --git a/docs/CHANGES_4.0.0.md b/docs/CHANGES_4.0.0.md index 68ab2e7e46b..dd86af64a05 100644 --- a/docs/CHANGES_4.0.0.md +++ b/docs/CHANGES_4.0.0.md @@ -1,39 +1,334 @@ -# Changes in 4.x +# Changes in 4.x (and how to migrate!) -WIP +_Hello dear reader, **thank you** for adopting version 4.x of the MongoDB Node.js driver, from the bottom of our developer hearts we thank you so much for taking the time to upgrade to our latest and greatest offering of a stunning database experience. +We hope you enjoy your upgrade experience and this guide gives you all the answers you are searching for. +If anything, and we mean anything, hinders your upgrade experience please let us know via [JIRA](https://jira.mongodb.org/browse/NODE). +We know breaking changes are hard but they are sometimes for the best. +Anyway, enjoy the guide, see you at the end!_ -## Versioned API +## Key Changes -Versioned API is a new feature in MongoDB 5.0 that allows user-selectable API versions, subsets of MongoDB server semantics, to be declared on a client. During communication with a server, clients with a declared API version will force the server to behave in a manner compatible with the API version. Declaring an API version on a client can be used to ensure consistent responses from a server, providing long term API stability for an application. The declared API version is applied to all commands run through the client, including those sent through the generic RunCommand helper. Specifying versioned API options in the command document AND declaring an API version on the client is not supported and will lead to undefined behaviour. +### Typescript -### Declare an API version on a client: +We've migrated the driver to Typescript! +Users can now harness the power of type hinting and intellisense in editors that support it to develop their MongoDB applications. +Even pure JavaScript projects can benefit from the type definitions with the right linting setup. +Along with the type hinting there's consistent and helpful docs formatting that editors should be able to display while developing. +Recently we migrated our BSON library to TypeScript as well, this version of the driver pulls in that change. + +#### Community Types users (@types/mongodb) + +If you are a user of the community types (@types/mongodb) there will likely be compilation errors while adopting the types from our codebase. +Unfortunately we could not achieve a one to one match in types due to the details of writing the codebase in Typescript vs definitions for the user layer API along with the breaking changes of this major version. Please let us know if there's anything that is a blocker to upgrading [on JIRA](https://jira.mongodb.org/browse/NODE). + +### Node.js Version + +We now require node 12.9 or greater for version 4 of the driver. +If that's outside your support matrix at this time, that's okay! +Bug fix support for our 3.x branch will not be ending until summer 2022, which has support going back as far as Node.js v4! + +### Cursor changes + +Affected classes: + +- `AbstractCursor` +- `FindCursor` +- `AggregationCursor` +- `ChangeStreamCursor` + - This is the underlying cursor for `ChangeStream` +- `ListCollectionsCursor` + +Our Cursor implementation has been updated to clarify what is possible before and after execution of an operation. Take this example: + +```javascript +const cursor = collection.find({ a: 2.3 }).skip(1); +for await (const doc of cursor) { + console.log(doc); + fc.limit(1); // bad. +} +``` + +Prior to the this release there was inconsistency surrounding how the cursor would error if a setting like limit was applied after cursor execution had begun. +Now, an error along the lines of: `Cursor is already initialized` is thrown. + +#### ChangeStream must be used as an iterator or an event emitter + +You cannot use ChangeStream as an iterator after using as an EventEmitter nor visa versa. +Previously the driver would permit this kind of usage but it could lead to unpredictable behavior and obscure errors. +It's unlikely this kind of usage was useful but to be sure we now prevent it by throwing a clear error. ```javascript -// Declare API version "1" for the client -client = new MongoClient(uri, { serverApi: { version: '1' } }); +const changeStream = db.watch(); +changeStream.on('change', doc => console.log(doc)); +await changeStream.next(); // throws: Cannot use ChangeStream as iterator after using as an EventEmitter +``` + +Or the reverse: -cursor = client.db('database').collection('coll').find(...); +```javascript +const changeStream = db.watch(); +await changeStream.next(); +changeStream.on('change', doc => console.log(doc)); // throws: Cannot use ChangeStream as an EventEmitter after using as an iterator ``` -### Strict mode +#### Stream API -Declaring a `strict` API version will cause the MongoDB server to reject all commands that are not part of the declared API version. This includes command options and aggregation pipeline stages. For example, the following `find` call would fail because the `tailable` option is not part of version 1: +The Cursor no longer extends Readable directly, it must be transformed into a stream by calling cursor.stream(), for example: ```javascript -// Declare API version "1" for the client, with strict on -client = new MongoClient(uri, { serverApi: { version: '1', strict: true } }); +const cursor = collection.find({}); +const stream = cursor.stream(); +stream.on('data', data => console.log(data)); +stream.on('end', () => client.close()); +``` + +`Cursor.transformStream()` has been removed. `Cursor.stream()` accepts a transform function, so that API was redundant. + +### MongoClientOptions interface + +With type hinting users should find that the options passed to a MongoClient are completely enumerated and easily discoverable. +In 3.x there were options, like `maxPoolSize`, that were only respected when `useUnifiedTopology=true` was enabled, vs `poolSize` when `useUnifiedTopology=false`. +We've de-duped these options and put together some hefty validation to help process all options upfront to give early warnings about incompatible settings in order to help your app get up and running correctly quicker! + +#### Unified Topology Only -// Fails with an error -cursor = client.db('database').collection('coll').find({ ... }, { tailable: true }); +We internally now only manage a Unified Topology when you connect to your MongoDB. +The [differences are described in detail here](https://mongodb.github.io/node-mongodb-native/3.6/reference/unified-topology/). + +Feel free to remove the `useUnifiedTopology` and `useNewUrlParser` options at your leisure, they are no longer used by the driver. + +**NOTE:** With the unified topology, in order to connect to replicaSet nodes that have not been initialized you must use the new `directConnection` option. + +#### Authentication + +Specifying username and password as options is only supported in these two formats: + +- `new MongoClient(url, { auth: { username: '', password: '' } })` +- `new MongoClient('mongodb://username:password@myDb.host')` + +#### Check Server Identity Inconsistency + +Specifying `checkServerIdentity === false` (along with enabling tls) is different from leaving it `undefined`. +The 3.x version intercepted `checkServerIdentity: false` and turned it into a no-op function which is the required way to skip checking the server identity by nodejs. +Setting this option to `false` is only for testing anyway as it disables essential verification to TLS. +So it made sense for our library to directly expose the option validation from Node.js. +If you need to test TLS connections without verifying server identity pass in `{ checkServerIdentity: () => {} }`. + +#### Kerberos / GSSAPI + +`gssapiServiceName` has been removed. +Users should use `authMechanismProperties.SERVICE_NAME` like so: + +- In a URI query param: `?authMechanismProperties=SERVICE_NAME:alternateServiceName` +- Or as an option: `{ authMechanismProperties: { SERVICE_NAME: 'alternateServiceName' } }` + +### db.collection no longer accepts a callback + +The only option that required the use of the callback was strict mode. +The strict option would return an error if the collection does not exist. +Users who wish to ensure operations only execute against existing collections should use `db.listCollections` directly. + +For example: + +```javascript +const collections = (await db.listCollections({}, { nameOnly: true }).toArray()).map( + ({ name }) => name +); // map to get string[] +if (!collections.includes(myNewCollectionName)) { + throw new Error(`${myNewCollectionName} doesn't exist`); +} ``` -### Deprecation Errors +### BulkWriteError renamed to MongoBulkWriteError + +In 3.x we exported both the names above, we now only export `MongoBulkWriteError`. +Users testing for `BulkWriteError`s should be sure to import the new class name `MongoBulkWriteError`. + +### Db no longer emits events + +The Db instance is no longer an EventEmitter, all events your application is concerned with can be listened to directly from the `MongoClient` instance. + +### Collection.group() removed + +The collection `group()` helper has been deprecated in MongoDB since 3.4 and is now removed from the driver. +The same functionality can be achieved using the aggregation pipeline's `$group` operator. + +### GridStore removed -The `deprecationErrors` option can be used to enable command failures when using functionality that is deprecated from version 1. Note that at the time of this writing, no deprecations in version 1 exist. +The deprecated GridStore API has been removed from the driver. +For more information on GridFS [see the mongodb manual](https://docs.mongodb.com/manual/core/gridfs/). + +Below are some snippets that represent equivalent operations: + +#### Construction + +```javascript +// old way +const gs = new GridStore(db, filename, mode[, options]) +// new way +const bucket = new GridFSBucket(client.db('test')[, options]) +``` + +#### File seeking + +Since GridFSBucket uses the Node.js Stream API you can replicate file seek-ing by using the start and end options creating a download stream from your GridFSBucket + +```javascript +bucket.openDownloadStreamByName(filename, { start: 23, end: 52 }); +``` + +#### File Upload & File Download + +```javascript +await client.connect(); +const filename = 'test.txt'; // whatever local file name you want +const db = client.db(); +const bucket = new GridFSBucket(db); + +fs.createReadStream(filename) + .pipe(bucket.openUploadStream(filename)) + .on('error', console.error) + .on('finish', () => { + console.log('done writing to db!'); + + bucket + .find() + .toArray() + .then(files => { + console.log(files); + + bucket + .openDownloadStreamByName(filename) + .pipe(fs.createWriteStream('downloaded_' + filename)) + .on('error', console.error) + .on('finish', () => { + console.log('done downloading!'); + client.close(); + }); + }); + }); +``` + +Notably, **GridFSBucket does not need to be closed like GridStore.** + +#### File Deletion + +Deleting files hasn't changed much: + +```javascript +GridStore.unlink(db, name, callback); // Old way +bucket.delete(file_id); // New way! +``` + +#### Finding File Metadata + +File metadata that used to be accessible on the GridStore instance can be found by querying the bucket + +```typescript +const fileMetaDataList: GridFSFile[] = bucket.find({}).toArray(); +``` + +#### Hashing an upload + +The automatic MD5 hashing has been removed from the upload family of functions. +This makes the default Grid FS behavior compliant with systems that do not permit usage of MD5 hashing. +The `disableMD5` option is no longer used and has no effect. + +If you still want to add an MD5 hash to your file upload, here's a simple example that can be used with [any hashing algorithm](https://nodejs.org/dist/latest-v14.x/docs/api/crypto.html#crypto_crypto_createhash_algorithm_options) provided by Node.js: ```javascript -// Declare API version "1" for the client, with deprecationErrors on -client = new MongoClient(uri, { serverApi: { version: '1', deprecationErrors: true } }); +const bucket = new GridFSBucket(db); + +// can be whatever algorithm is supported by your local openssl +const hash = crypto.createHash('md5'); +hash.setEncoding('hex'); // we want a hex string in the end + +const _id = new ObjectId(); // we could also use file name to do the update lookup -// Note: since API version "1" is the initial version, there are no deprecated commands to provide as an example yet. +const uploadStream = fs + .createReadStream('./test.txt') + .on('data', data => hash.update(data)) // keep the hash up to date with the file chunks + .pipe(bucket.openUploadStreamWithId(_id, 'test.txt')); + +const md5 = await new Promise((resolve, reject) => { + uploadStream + .once('error', error => reject(error)) + .once('finish', () => { + hash.end(); // must call hash.end() otherwise hash.read() will be `null` + resolve(hash.read()); + }); +}); + +await db.collection('fs.files').updateOne({ _id }, { $set: { md5 } }); ``` + +## Intentional Breaking Changes + +- [`NODE-3368`](https://jira.mongodb.org/browse/NODE-3368): make name prop on error classes read-only ([#2879](https://github.com/mongodb/node-mongodb-native/pull/2879)) +- [`NODE-3291`](https://jira.mongodb.org/browse/NODE-3291): standardize error representation in the driver ([#2824](https://github.com/mongodb/node-mongodb-native/pull/2824)) +- [`NODE-3272`](https://jira.mongodb.org/browse/NODE-3272): emit correct event type when SRV Polling ([#2825](https://github.com/mongodb/node-mongodb-native/pull/2825)) +- [`NODE-1812`](https://jira.mongodb.org/browse/NODE-1812): replace returnOriginal with returnDocument option ([#2803](https://github.com/mongodb/node-mongodb-native/pull/2803)) +- [`NODE-3157`](https://jira.mongodb.org/browse/NODE-3157): update find and modify interfaces for 4.0 ([#2799](https://github.com/mongodb/node-mongodb-native/pull/2799)) +- [`NODE-2961`](https://jira.mongodb.org/browse/NODE-2961): clarify empty BulkOperation error message ([#2697](https://github.com/mongodb/node-mongodb-native/pull/2697)) +- [`NODE-1709`](https://jira.mongodb.org/browse/NODE-1709): stop emitting topology events from `Db` ([#2251](https://github.com/mongodb/node-mongodb-native/pull/2251)) +- [`NODE-2704`](https://jira.mongodb.org/browse/NODE-2704): integrate MongoOptions parser into driver ([#2680](https://github.com/mongodb/node-mongodb-native/pull/2680)) +- [`NODE-2757`](https://jira.mongodb.org/browse/NODE-2757): add collation to FindOperators ([#2679](https://github.com/mongodb/node-mongodb-native/pull/2679)) +- [`NODE-2602`](https://jira.mongodb.org/browse/NODE-2602): createIndexOp returns string, CreateIndexesOp returns array ([#2666](https://github.com/mongodb/node-mongodb-native/pull/2666)) +- [`NODE-2936`](https://jira.mongodb.org/browse/NODE-2936): conform CRUD result types to specification ([#2651](https://github.com/mongodb/node-mongodb-native/pull/2651)) +- [`NODE-2590`](https://jira.mongodb.org/browse/NODE-2590): adds async iterator for custom promises ([#2578](https://github.com/mongodb/node-mongodb-native/pull/2578)) +- [`NODE-2458`](https://jira.mongodb.org/browse/NODE-2458): format sort in cursor and in sort builder ([#2573](https://github.com/mongodb/node-mongodb-native/pull/2573)) +- [`NODE-2820`](https://jira.mongodb.org/browse/NODE-2820): pull CursorStream out of Cursor ([#2543](https://github.com/mongodb/node-mongodb-native/pull/2543)) +- [`NODE-2850`](https://jira.mongodb.org/browse/NODE-2850): only store topology on MongoClient ([#2594](https://github.com/mongodb/node-mongodb-native/pull/2594)) +- [`NODE-2423`](https://jira.mongodb.com/browse/NODE-2423): deprecate `oplogReplay` for find commands ([24155e7](https://github.com/mongodb/node-mongodb-native/commit/24155e7905422460afc7e6abb120c596f40712c1)) + +## Removals + +- [`NODE-2752`](https://jira.mongodb.org/browse/NODE-2752): remove strict/callback mode from Db.collection helper ([#2817](https://github.com/mongodb/node-mongodb-native/pull/2817)) +- [`NODE-2978`](https://jira.mongodb.org/browse/NODE-2978): remove deprecated bulk ops ([#2794](https://github.com/mongodb/node-mongodb-native/pull/2794)) +- [`NODE-1722`](https://jira.mongodb.org/browse/NODE-1722): remove top-level write concern options ([#2642](https://github.com/mongodb/node-mongodb-native/pull/2642)) +- [`NODE-1487`](https://jira.mongodb.org/browse/NODE-1487): remove deprecated Collection.group helper ([#2609](https://github.com/mongodb/node-mongodb-native/pull/2609)) +- [`NODE-2816`](https://jira.mongodb.org/browse/NODE-2816): remove deprecated find options ([#2571](https://github.com/mongodb/node-mongodb-native/pull/2571)) +- [`NODE-2320`](https://jira.mongodb.org/browse/NODE-2320): remove deprecated GridFS API ([#2290](https://github.com/mongodb/node-mongodb-native/pull/2290)) +- [`NODE-2713`](https://jira.mongodb.com/browse/NODE-2713): remove `parallelCollectionScan` helper ([#2449](https://github.com/mongodb/node-mongodb-native/pull/2449)) ([9dee21f](https://github.com/mongodb/node-mongodb-native/commit/9dee21feefab9a8f20e289e6ff7abece40ef7d0b)) +- [`NODE-2324`](https://jira.mongodb.com/browse/NODE-2324): remove Cursor#transformStream ([#2574](https://github.com/mongodb/node-mongodb-native/pull/2574)) ([a54be7a](https://github.com/mongodb/node-mongodb-native/commit/a54be7afd665d92337a8ba2e206cc3e6ce5e5773)) +- [`NODE-2318`](https://jira.mongodb.com/browse/NODE-2318): remove legacy topology types ([6aa2434](https://github.com/mongodb/node-mongodb-native/commit/6aa2434628e85ead8e5be620c27ebe8ab08a1c05)) +- [`NODE-2560`](https://jira.mongodb.com/browse/NODE-2560): remove reIndex ([#2370](https://github.com/mongodb/node-mongodb-native/pull/2370)) ([6b510a6](https://github.com/mongodb/node-mongodb-native/commit/6b510a689ab0dc44b3302ad21c171e75f9059716)) +- [`NODE-2736`](https://jira.mongodb.com/browse/NODE-2736): remove the collection save method ([#2477](https://github.com/mongodb/node-mongodb-native/pull/2477)) ([d5bb496](https://github.com/mongodb/node-mongodb-native/commit/d5bb49637853c841b47df020807edf9adb5ef804)) +- [`NODE-1722`](https://jira.mongodb.com/browse/NODE-1722): remove top-level write concern options ([#2642](https://github.com/mongodb/node-mongodb-native/issues/2642)) ([6914e87](https://github.com/mongodb/node-mongodb-native/commit/6914e875b37fb0ad444105ad24839d50c5c224d4)) +- [`NODE-2506`](https://jira.mongodb.com/browse/NODE-2506): remove createCollection strict mode ([#2506](https://github.com/mongodb/node-mongodb-native/pull/2506)) ([bb13764](https://github.com/mongodb/node-mongodb-native/commit/bb137643b2a95bd5898d2fef4d761de5f2e2cde0)) +- [`NODE-2562`](https://jira.mongodb.com/browse/NODE-2562): remove geoHaystackSearch ([#2315](https://github.com/mongodb/node-mongodb-native/pull/2315)) ([5a1b61c](https://github.com/mongodb/node-mongodb-native/commit/5a1b61c9f2baf8f6f3cec4c34ce2db52272cd49d)) +- [`NODE-3427`](https://jira.mongodb.org/browse/NODE-3427): remove md5 hashing from GridFS API ([#2899](https://github.com/mongodb/node-mongodb-native/pull/2740)) ([a488d88](https://github.com/mongodb/node-mongodb-native/commit/a488d8838e0d046b0eae243504258a0896ffb383)) +- [`NODE-2317`](https://jira.mongodb.org/browse/NODE-2317): remove deprecated items ([#2740](https://github.com/mongodb/node-mongodb-native/pull/2740)) ([listed below](#removed-deprecations)) + +## Removed deprecations + +- `Collection.prototype.find / findOne` options: + - `fields` - use `projection` instead +- `Collection.prototype.save` - use `insertOne` instead +- `Collection.prototype.dropAllIndexes` +- `Collection.prototype.ensureIndex` +- `Collection.prototype.findAndModify` - use `findOneAndUpdate`/`findOneAndReplace` instead +- `Collection.prototype.findAndRemove` - use `findOneAndDelete` instead +- `Collection.prototype.parallelCollectionScan` +- `MongoError.create` +- `Topology.destroy` +- `Cursor.prototype.each` - use `forEach` instead +- `Db.prototype.eval` +- `Db.prototype.ensureIndex` +- `Db.prototype.profilingInfo` +- `MongoClient.prototype.logout` +- `MongoClient.prototype.addUser` - creating a user without roles +- `MongoClient.prototype.connect` +- `Remove MongoClient.isConnected` - calling connect is a no-op if already connected +- `Remove MongoClient.logOut` +- `require('mongodb').instrument` + - Use command monitoring: `client.on('commandStarted', (ev) => {})` +- Top-Level export no longer a function: `typeof require('mongodb') !== 'function'` + - Must construct a MongoClient and call `.connect()` on it. +- Removed `Symbol` export, now `BSONSymbol` which is a deprecated BSON type + - Existing BSON symbols in your database will be deserialized to a BSONSymbol instance; however, users should use plain strings instead of BSONSymbol +- Removed `connect` export, use `MongoClient` construction + +--- + +_And that's a wrap, thanks for upgrading! You've been a great audience!_ diff --git a/docs/FEATURES_4.0.0.md b/docs/FEATURES_4.0.0.md new file mode 100644 index 00000000000..74daaaca62d --- /dev/null +++ b/docs/FEATURES_4.0.0.md @@ -0,0 +1,87 @@ +# Feature Highlights + +## Versioned API + +Versioned API is a new feature in MongoDB 5.0 that allows user-selectable API versions, subsets of MongoDB server semantics, to be declared on a client. +During communication with a server, clients with a declared API version will force the server to behave in a manner compatible with the API version. +Declaring an API version on a client can be used to ensure consistent responses from a server, providing long term API stability for an application. The declared API version is applied to all commands run through the client, including those sent through the generic RunCommand helper. +Specifying versioned API options in the command document AND declaring an API version on the client is not supported and will lead to undefined behavior. + +### Declare an API version on a client + +```javascript +// Declare API version "1" for the client +client = new MongoClient(uri, { serverApi: { version: '1' } }); + +cursor = client.db('database').collection('coll').find(...); +``` + +### Strict mode + +Declaring a `strict` API version will cause the MongoDB server to reject all commands that are not part of the declared API version. This includes command options and aggregation pipeline stages. For example, the following `find` call would fail because the `tailable` option is not part of version 1: + +```javascript +// Declare API version "1" for the client, with strict on +client = new MongoClient(uri, { serverApi: { version: '1', strict: true } }); + +// Fails with an error +cursor = client.db('database').collection('coll').find({ ... }, { tailable: true }); +``` + +### Deprecation Errors + +The `deprecationErrors` option can be used to enable command failures when using functionality that is deprecated from version 1. Note that at the time of this writing, no deprecations in version 1 exist. + +```javascript +// Declare API version "1" for the client, with deprecationErrors on +client = new MongoClient(uri, { serverApi: { version: '1', deprecationErrors: true } }); + +// Note: since API version "1" is the initial version, there are no deprecated commands to provide as an example yet. +``` + +## Features List + +* [`NODE-3392`](https://jira.mongodb.org/browse/NODE-3392): enable snapshot reads on secondaries ([#2897](https://github.com/mongodb/node-mongodb-native/pull/2897)) ([523e05c](https://github.com/mongodb/node-mongodb-native/commit/523e05c3684dcf98c8bbfa4f0631092debd8a85c)) +* [`NODE-2751`](https://jira.mongodb.org/browse/NODE-2751): add arrayFilters builder to bulk FindOperators ([#2820](https://github.com/mongodb/node-mongodb-native/issues/2820)) ([d099622](https://github.com/mongodb/node-mongodb-native/commit/d099622cdd1ba60d108b1b6a1b323dff847f99b5)) +* [`NODE-3274`](https://jira.mongodb.org/browse/NODE-3274): add type hinting for UpdateFilter ([#2842](https://github.com/mongodb/node-mongodb-native/issues/2842)) ([05035eb](https://github.com/mongodb/node-mongodb-native/commit/05035eb2d7bdb0820181de5f86f0004cc77c1c00)) +* [`NODE-3325`](https://jira.mongodb.org/browse/NODE-3325): support 'let' option for aggregate command ([#2828](https://github.com/mongodb/node-mongodb-native/issues/2828)) ([e38838e](https://github.com/mongodb/node-mongodb-native/commit/e38838e28d075126c8702de18247230d05965e11)) +* [`NODE-3331`](https://jira.mongodb.org/browse/NODE-3331): offer downleveled types for legacy typescript versions ([#2859](https://github.com/mongodb/node-mongodb-native/issues/2859)) ([27cf1d2](https://github.com/mongodb/node-mongodb-native/commit/27cf1d241549c06fb69aee313176d87dcd13514a)) +* [`NODE-3333`](https://jira.mongodb.org/browse/NODE-3333): support 'let' option for CRUD commands ([#2829](https://github.com/mongodb/node-mongodb-native/issues/2829)) ([0d91da1](https://github.com/mongodb/node-mongodb-native/commit/0d91da1b1388e6946ec991fee82f92647a199ece)) +* [`NODE-3115`](https://jira.mongodb.org/browse/NODE-3115): add generic parameterization ([#2767](https://github.com/mongodb/node-mongodb-native/issues/2767)) ([4d12491](https://github.com/mongodb/node-mongodb-native/commit/4d12491a7ef12488bc9b4f0c5b8428d29d687132)) +* [`NODE-3132`](https://jira.mongodb.org/browse/NODE-3132): add TypedEventEmitter ([#2785](https://github.com/mongodb/node-mongodb-native/issues/2785)) ([f4d40a4](https://github.com/mongodb/node-mongodb-native/commit/f4d40a4c2bf1ace188e624f5c7d5852d5395e00a)) +* [`NODE-3106`](https://jira.mongodb.com/browse/NODE-3106): add fermium to evergreen test runs ([#2762](https://github.com/mongodb/node-mongodb-native/issues/2762)) ([2303b41](https://github.com/mongodb/node-mongodb-native/commit/2303b418b461b3c965f0c48f160d812153eba11e)) +* [`NODE-2950`](https://jira.mongodb.com/browse/NODE-2950): versioned api ([#2736](https://github.com/mongodb/node-mongodb-native/issues/2736)) ([93f3ea5](https://github.com/mongodb/node-mongodb-native/commit/93f3ea5815bbd85b90745716f35849a59e8f8746)) +* [`NODE-2806`](https://jira.mongodb.com/browse/NODE-2806): add `withReadConcern` builder to AbstractCursor ([#2645](https://github.com/mongodb/node-mongodb-native/issues/2645)) ([0cca729](https://github.com/mongodb/node-mongodb-native/commit/0cca729eb94ee942b775e14d57c44d57beda3fce)) +* [`NODE-2917`](https://jira.mongodb.com/browse/NODE-2917): add an internal `tryNext` method ([#2638](https://github.com/mongodb/node-mongodb-native/issues/2638)) ([43c94b6](https://github.com/mongodb/node-mongodb-native/commit/43c94b6d40824c6cfa531d6ee9ac6b307e4cbcc6)) +* [`NODE-2569`](https://jira.mongodb.com/browse/NODE-2569): add commitQuorum option to createIndexes command ([#2345](https://github.com/mongodb/node-mongodb-native/pull/2345)) ([168a952](https://github.com/mongodb/node-mongodb-native/commit/168a952f60787f325b202c539a664b9e14451b65)) +* [`NODE-2853`](https://jira.mongodb.com/browse/NODE-2853): add explain support for cursor commands ([#2622](https://github.com/mongodb/node-mongodb-native/issues/2622)) ([bb1e081](https://github.com/mongodb/node-mongodb-native/commit/bb1e081e366612e0872d3c5ec0fadbb61e202ad6)) +* [`NODE-2852`](https://jira.mongodb.com/browse/NODE-2852): add explain support for non-cursor commands ([#2599](https://github.com/mongodb/node-mongodb-native/issues/2599)) ([4472308](https://github.com/mongodb/node-mongodb-native/commit/447230826cd764e2b766d3178d4fa369f8a4ebc4)) +* [`NODE-2288`](https://jira.mongodb.com/browse/NODE-2288): add MONGODB-AWS as a supported auth mechanism ([7f3cfba](https://github.com/mongodb/node-mongodb-native/commit/7f3cfbac15f537aa2ca9da145063f10c61390406)) +* [`NODE-2699`](https://jira.mongodb.com/browse/NODE-2699): add MongoOption builder logic ([#2623](https://github.com/mongodb/node-mongodb-native/issues/2623)) ([cb9ee9e](https://github.com/mongodb/node-mongodb-native/commit/cb9ee9e6175a6654c3c300801884e4a3c3a653ac)) +* [`NODE-2871`](https://jira.mongodb.com/browse/NODE-2871): implement post-assignment operations (tls, dns, aliases) ([#2623](https://github.com/mongodb/node-mongodb-native/issues/2623)) ([cb9ee9e](https://github.com/mongodb/node-mongodb-native/commit/cb9ee9e6175a6654c3c300801884e4a3c3a653ac)) +* [`NODE-2698`](https://jira.mongodb.com/browse/NODE-2698): add MongoOptions interface ([#2616](https://github.com/mongodb/node-mongodb-native/issues/2616)) ([54c456b](https://github.com/mongodb/node-mongodb-native/commit/54c456b4a4ff51c4f6734cff550d8aa53a47db15)) +* [`NODE-2932`](https://jira.mongodb.com/browse/NODE-2932): add types for the result of bulk initialize methods ([#2654](https://github.com/mongodb/node-mongodb-native/issues/2654)) ([3e5ff57](https://github.com/mongodb/node-mongodb-native/commit/3e5ff57d6438add80c1bad932114f3d086f1cc29)) +* [`NODE-2591`](https://jira.mongodb.com/browse/NODE-2591): adds "hidden" option when creating indexes ([#2548](https://github.com/mongodb/node-mongodb-native/pull/2548)) ([ee8ca1a](https://github.com/mongodb/node-mongodb-native/commit/ee8ca1aaddd1da33689a49c99dcc1c6f42b6f9dd)) +* [`NODE-2590`](https://jira.mongodb.com/browse/NODE-2590): adds async iterator for custom promises ([#2578](https://github.com/mongodb/node-mongodb-native/pull/2578)) ([16d6572](https://github.com/mongodb/node-mongodb-native/commit/16d65722a5b2318eee014511c94385e9d4f60ed7)) +* [`NODE-2477`](https://jira.mongodb.com/browse/NODE-2477): allow hinting the delete command ([#2302](https://github.com/mongodb/node-mongodb-native/pull/2302)) ([95fedf4](https://github.com/mongodb/node-mongodb-native/commit/95fedf4ecf2da73802a4146ab0c7df6a0850103c)) +* [`NODE-2150`](https://jira.mongodb.com/browse/NODE-2150): bump wire protocol version for 4.4 ([6d3f313](https://github.com/mongodb/node-mongodb-native/commit/6d3f313a9defd12489b621896439b3f9ec8cb1ae)) +* [`NODE-1452`](https://jira.mongodb.com/browse/NODE-1452): convert the entire codebase to TypeScript ([272bc18](https://github.com/mongodb/node-mongodb-native/commit/272bc18f51351a9f18d6d1bc68413c1a0c1f649f)) +* [`NODE-2452`](https://jira.mongodb.com/browse/NODE-2452): directConnection adds unify behavior for replica set discovery ([#2349](https://github.com/mongodb/node-mongodb-native/issues/2349)) ([34c9195](https://github.com/mongodb/node-mongodb-native/commit/34c9195251adeeb1c9e8bc4234c8afb076d1d60e)) +* [`NODE-2379`](https://jira.mongodb.com/browse/NODE-2379): expand use of error labels for retryable writes ([c775a4a](https://github.com/mongodb/node-mongodb-native/commit/c775a4a1c53b8476eff6c9759b5647c9cbfa4e04)) +* [`NODE-2579`](https://jira.mongodb.com/browse/NODE-2579): implements promise provider ([#2348](https://github.com/mongodb/node-mongodb-native/pull/2348)) ([e5b762c](https://github.com/mongodb/node-mongodb-native/commit/e5b762c6d53afa967f24c26a1d1b6c921757c9c9)) +* [`NODE-2704`](https://jira.mongodb.com/browse/NODE-2704): integrate MongoOptions parser into driver ([#2680](https://github.com/mongodb/node-mongodb-native/issues/2680)) ([b1bdb06](https://github.com/mongodb/node-mongodb-native/commit/b1bdb06cbe95fd320afff00ccb8fea666c79b444)) +* [`NODE-2809`](https://jira.mongodb.com/browse/NODE-2809): introduce AbstractCursor and its concrete subclasses ([#2619](https://github.com/mongodb/node-mongodb-native/issues/2619)) ([a2d78b2](https://github.com/mongodb/node-mongodb-native/commit/a2d78b22b28ae649fa2c4e28294a3a03c446373e)) +* [`NODE-2930`](https://jira.mongodb.com/browse/NODE-2930): introduce BufferPool to replace BufferList ([#2669](https://github.com/mongodb/node-mongodb-native/issues/2669)) ([3c56efc](https://github.com/mongodb/node-mongodb-native/commit/3c56efcf25a9ca8085a37f2ebac8cb3bff6d6d6c)) +* [`NODE-2811`](https://jira.mongodb.com/browse/NODE-2811): reintroduce clone and rewind for cursors ([#2647](https://github.com/mongodb/node-mongodb-native/issues/2647)) ([a5154fb](https://github.com/mongodb/node-mongodb-native/commit/a5154fb5977dddd88e57f9d20965e95fa7ddb80b)) +* [`NODE-2289`](https://jira.mongodb.com/browse/NODE-2289): support `allowDiskUse` for find commands ([dbc0b37](https://github.com/mongodb/node-mongodb-native/commit/dbc0b3722516a128c253bf85366a3432756ff92a)) +* [`NODE-2295`](https://jira.mongodb.com/browse/NODE-2295): support creating collections and indexes in transactions ([917f2b0](https://github.com/mongodb/node-mongodb-native/commit/917f2b088f22f4c6ed803f0349859d057389ac1e)) +* [`NODE-2757`](https://jira.mongodb.com/browse/NODE-2757): add collation to FindOperators ([#2679](https://github.com/mongodb/node-mongodb-native/issues/2679)) ([a41d503](https://github.com/mongodb/node-mongodb-native/commit/a41d503ebd061977e712ac26dc7c757ab03cab14)) +* [`NODE-2510`](https://jira.mongodb.com/browse/NODE-2510): support hedged reads ([#2350](https://github.com/mongodb/node-mongodb-native/pull/2350)) ([2b7b936](https://github.com/mongodb/node-mongodb-native/commit/2b7b936b532c1461dba59a4840978beea7b934fb)) +* [`NODE-2290`](https://jira.mongodb.com/browse/NODE-2290): support passing a hint to findOneAndReplace/findOneAndUpdate ([faee15b](https://github.com/mongodb/node-mongodb-native/commit/faee15b686b895b84fd0b52c1e69e0caec769732)) +* [`NODE-2301`](https://jira.mongodb.com/browse/NODE-2301): support shorter SCRAM conversations ([6b9ff05](https://github.com/mongodb/node-mongodb-native/commit/6b9ff0561d14818bf07f4946ade04fc54683d0b9)) +* [`NODE-2955`](https://jira.mongodb.com/browse/NODE-2955): fluent builder for allowDiskUse option ([#2678](https://github.com/mongodb/node-mongodb-native/issues/2678)) ([d442aac](https://github.com/mongodb/node-mongodb-native/commit/d442aac66e7a236decdfbeb5be0cc8a163486534)) +* [`NODE-2487`](https://jira.mongodb.com/browse/NODE-2487): support speculative authentication in scram-sha and x509 ([#2353](https://github.com/mongodb/node-mongodb-native/pull/2353)) ([f71f09b](https://github.com/mongodb/node-mongodb-native/commit/f71f09bd466f0630bbe6859d8ed074ecd5f4a51f)) +* [`NODE-2379`](https://jira.mongodb.com/browse/NODE-2379): use error labels for retryable writes in legacy topologies ([fefc165](https://github.com/mongodb/node-mongodb-native/commit/fefc1651a885ec28758271c9e3c36104b05bdb75)) +* `NO TICKET`: options object precedence over URI options ([#2691](https://github.com/mongodb/node-mongodb-native/issues/2691)) ([85d8d09](https://github.com/mongodb/node-mongodb-native/commit/85d8d09713e2a80442dfbb38ecc887204306ba17)) +* `NO TICKET`: introduce an interruptable async interval timer ([21cbabd](https://github.com/mongodb/node-mongodb-native/commit/21cbabdb1cf9ebee887bda547aa9116781cf03ae)) +* `NO TICKET`: support the streaming protocol for topology updates ([7e9c5bc](https://github.com/mongodb/node-mongodb-native/commit/7e9c5bc5e8b10ae146d80535a44221ddb9ded069))