/node_modules/mongoose/node_modules/mongodb/CHANGES_3.0.0.md

  1## Features
  2
  3The following are new features added in MongoDB 3.6 and supported in the Node.js driver.
  4
  5### Retryable Writes
  6
  7Support has been added for retryable writes through the connection string. MongoDB 3.6
  8will utilize server sessions to allow some write commands to specify a transaction ID to enforce
  9at-most-once semantics for the write operation(s) and allow for retrying the operation if the driver
 10fails to obtain a write result (e.g. network error or "not master" error after a replica set
 11failover)Full details can be found in the [Retryable Writes Specification](https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst).
 12
 13
 14### DNS Seedlist Support
 15
 16Support has been added for DNS Seedlists. Users may now configure a single domain to return a list
 17of host names. Full details can be found in the [Seedlist Discovery Specification](https://github.com/mongodb/specifications/blob/master/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.rst).
 18
 19### Change Streams
 20
 21Support has been added for creating a stream to track changes to a particular collection. This is a
 22new feature in MongoDB 3.6. Full details can be found in the [Change Stream Specification](https://github.com/mongodb/specifications/blob/master/source/change-streams.rst) as
 23well as [examples in the test directory](https://github.com/mongodb/node-mongodb-native/blob/3.0.0/test/functional/operation_changestream_example_tests.js).
 24
 25### Sessions
 26
 27Version 3.6 of the server introduces the concept of logical sessions for clients. In this driver,
 28`MongoClient` now tracks all sessions created on the client, and explicitly cleans them up upon
 29client close. More information can be found in the [Driver Sessions Specification](https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst).
 30
 31## API Changes
 32
 33We removed the following API methods.
 34
 35- `Db.prototype.authenticate`
 36- `Db.prototype.logout`
 37- `Db.prototype.open`
 38- `Db.prototype.db`
 39- `Db.prototype.close`
 40- `Admin.prototype.authenticate`
 41- `Admin.prototype.logout`
 42- `Admin.prototype.profilingLevel`
 43- `Admin.prototype.setProfilingLevel`
 44- `Admin.prototype.profilingInfo`
 45- `Cursor.prototype.nextObject`
 46
 47We've added the following API methods.
 48- `MongoClient.prototype.logout`
 49- `MongoClient.prototype.isConnected`
 50- `MongoClient.prototype.db`
 51- `MongoClient.prototype.close`
 52- `MongoClient.prototype.connect`
 53- `Db.prototype.profilingLevel`
 54- `Db.prototype.setProfilingLevel`
 55- `Db.prototype.profilingInfo`
 56
 57In core we have removed the possibility of authenticating multiple credentials against the same
 58connection pool. This is to avoid problems with MongoDB 3.6 or higher where all users will reside in
 59the admin database and thus database level authentication is no longer supported.
 60
 61The legacy construct
 62
 63```js
 64var db = var Db('test', new Server('localhost', 27017));
 65db.open((err, db) => {
 66  // Authenticate
 67  db.admin().authenticate('root', 'root', (err, success) => {
 68    ....
 69  });
 70});
 71```
 72
 73is replaced with
 74
 75```js
 76new MongoClient(new Server('localhost', 27017), {
 77    user: 'root'
 78  , password: 'root'
 79  , authSource: 'adming'}).connect((err, client) => {
 80    ....
 81  })
 82```
 83
 84`MongoClient.connect` works as expected but it returns the MongoClient instance instead of a
 85database object.
 86
 87The legacy operation
 88
 89```js
 90MongoClient.connect('mongodb://localhost:27017/test', (err, db) => {
 91  // Database returned
 92});
 93```
 94
 95is replaced with
 96
 97```js
 98MongoClient.connect('mongodb://localhost:27017/test', (err, client) => {
 99  // Client returned
100  var db = client.db('test');
101});
102```
103
104## Other Changes
105
106Below are more updates to the driver in the 3.0.0 release.
107
108### Connection String
109
110Following [changes to the MongoDB connection string specification](https://github.com/mongodb/specifications/commit/4631ccd4f825fb1a3aba204510023f9b4d193a05),
111authentication and hostname details in connection strings must now be URL-encoded. These changes
112reduce ambiguity in connection strings.
113
114For example, whereas before `mongodb://u$ername:pa$$w{}rd@/tmp/mongodb-27017.sock/test` would have
115been a valid connection string (with username `u$ername`, password `pa$$w{}rd`, host `/tmp/mongodb-27017.sock`
116and auth database `test`), the connection string for those details would now have to be provided to
117MongoClient as `mongodb://u%24ername:pa%24%24w%7B%7Drd@%2Ftmp%2Fmongodb-27017.sock/test`.
118
119Unsupported URL options in a connection string now log a warning instead of throwing an error.
120
121For more information about connection strings, read the [connection string specification](https://github.com/mongodb/specifications/blob/master/source/connection-string/connection-string-spec.rst).
122
123
124### `BulkWriteResult` & `BulkWriteError`
125
126When errors occured with bulk write operations in the past, the driver would callback or reject with
127the first write error, as well as passing the resulting `BulkWriteResult`.  For example:
128
129```js
130MongoClient.connect('mongodb://localhost', function(err, client) {
131  const collection = client.db('foo').collection('test-collection')
132
133  collection
134    .insert({ id: 1 })
135    .then(() => collection.insertMany([ { id: 1 }, { id: 1 } ]))
136    .then(result => /* deal with errors in `result */)
137    .catch(err => /* no error is thrown for bulk errors */);
138});
139```
140
141becomes:
142
143```js
144MongoClient.connect('mongodb://localhost', function(err, client) {
145  const collection = client.db('foo').collection('test-collection')
146
147  collection
148    .insert({ id: 1 })
149    .then(() => collection.insertMany([ { id: 1 }, { id: 1 } ]))
150    .then(() => /* this will not be called in the event of a bulk write error */)
151    .catch(err => /* deal with errors in `err` */);
152});
153```
154
155Where the result of the failed operation is a `BulkWriteError` which has a child value `result`
156which is the original `BulkWriteResult`.  Similarly, the callback form no longer calls back with an
157`(Error, BulkWriteResult)`, but instead just a `(BulkWriteError)`.
158
159### `mapReduce` inlined results
160
161When `Collection.prototype.mapReduce` is invoked with a callback that includes `out: 'inline'`,
162it would diverge from the `Promise`-based variant by returning additional data as positional
163arguments to  the callback (`(err, result, stats, ...)`).  This is no longer the case, both variants
164of the method will now return a single object for all results - a single value for the default case,
165and an object similar to the existing `Promise` form for cases where there is more data to pass to
166the user.
167
168### Find
169
170`find` and `findOne` no longer support the `fields` parameter. You can achieve the same results as
171the `fields` parameter by using `Cursor.prototype.project` or by passing the `projection` property
172in on the options object . Additionally, `find` does not support individual options like `skip` and
173`limit` as positional parameters. You must either pass in these parameters in the `options` object,
174or add them via `Cursor` methods like `Cursor.prototype.skip`.
175
176### `Collection.prototype.aggregate`
177
178`Collection.prototype.aggregate` no longer accepts variadic arguments. While this
179was originally added to improve compatibility with the mongo shell, it has never
180been a documented feature, and has led to more bugs and maintenance burden.
181Pipeline stages are now only accepted as an `Array` of stages as the first argument.
182
1832.x syntax:
184
185```js
186collection.prototype.aggregate(
187  {$match: {a: 1}},
188  {$project: {b: 1, _id: 0}},
189  function (err, result) {
190    ...
191  }
192);
193```
194
1953.x syntax
196
197```js
198collection.prototype.aggregate(
199  [
200    {$match: {a: 1}},
201    {$project: {b: 1, _id: 0}}
202  ],
203  function (err, cursor) {
204    ...
205  }
206);
207```
208
209`Collection.prototype.aggregate` now returns a cursor if a callback is provided. It used to return
210the resulting documents which is the same as calling `cursor.toArray()` on the cursor we now pass to
211the callback.
212
2132.x syntax
214
215```js
216collection.prototype.aggregate(
217  [
218    {$match: {a: 1}},
219    {$project: {b: 1, _id: 0}}
220  ],
221  function (err, result) {
222    console.log(result);
223  }
224);
225```
226
2273.x syntax
228
229```js
230collection.prototype.aggregate(
231  [
232    {$match: {a: 1}},
233    {$project: {b: 1, _id: 0}}
234  ],
235  function (err, cursor) {
236    cursor.toArray(function(err, result) {
237      console.log(result);
238    });
239  }
240);
241```
242
243Support added for `comment` in the aggregation command. Support also added for a `hint` field in the
244aggregation `options`.
245
246If you use aggregation and try to use the `explain` flag while you have a `readConcern` or
247`writeConcern`, your query will now fail.
248
249### `updateOne` & `updateMany`
250
251The driver now ensures that updated documents contain atomic operators. For instance, if a user
252tries to update an existing document but passes in no operations (such as `$set`, `$unset`, or
253`$rename`), the driver will now error:
254
255```js
256
257let testCollection = db.collection('test');
258testCollection.updateOne({_id: 'test'}, {});
259// An error is returned: The update operation document must contain at least one atomic operator.
260```
261
262### `keepAlive`
263
264Wherever it occurs, the option `keepAlive` has been changed. `keepAlive` is now a boolean that enables/disables `keepAlive`, while `keepAliveInitialDelay` specifies how long to wait before initiating keepAlive. This brings the API in line with [NodeJS's socket api](https://nodejs.org/dist/latest-v9.x/docs/api/all.html#net_socket_setkeepalive_enable_initialdelay)
265
266### `insertMany`
267
268Now `insertMany` returns `insertedIds` in a map of the index of the inserted document to the id of the inserted document:
269
270```js
271{
272  "0": 2,
273  "1": 3
274}
275```
276
277Previously an array of ids was returned: `[ 2, 3 ]`. This change occurs with both ordered and unordered `insertMany` calls, see the [CRUD specifications](https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst#results) for more details.
278
279### `geoNear` command helper
280
281The functionality of the geoNear command is duplicated elsewhere in the language, in the `$near`/`$nearSphere` query operators on unsharded collections, and in the `$geoNear` aggregation stage on all collections. Maintaining this command increases our test surface, and creates additional work when adding features that must be supported on all read commands. As a result, the command will be fully
282removed in the MongoDB 4.0 release, and we are choosing to remove it in this
283major release of the node driver.
284
285### Tests
286
287We have updated all of the tests to use [Mocha](https://mochajs.org) and a new test runner, [`mongodb-test-runner`](https://github.com/mongodb-js/mongodb-test-runner), which
288sets up topologies for the test scenarios.