mongodb 3.3.2 → 3.3.3

package/HISTORY.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+<a name="3.3.3"></a>
+## [3.3.3](https://github.com/mongodb/node-mongodb-native/compare/v3.3.2...v3.3.3) (2019-10-16)
+
+
+### Bug Fixes
+
+* **change_stream:** emit 'close' event if reconnecting failed ([f24c084](https://github.com/mongodb/node-mongodb-native/commit/f24c084))
+* **ChangeStream:** remove startAtOperationTime once we have resumeToken ([362afd8](https://github.com/mongodb/node-mongodb-native/commit/362afd8))
+* **connect:** Switch new Buffer(size) -> Buffer.alloc(size) ([da90c3a](https://github.com/mongodb/node-mongodb-native/commit/da90c3a))
+* **MongoClient:** only check own properties for valid options ([9cde4b9](https://github.com/mongodb/node-mongodb-native/commit/9cde4b9))
+* **mongos:** disconnect proxies which are not mongos instances ([ee53983](https://github.com/mongodb/node-mongodb-native/commit/ee53983))
+* **mongos:** force close servers during reconnect flow ([186263f](https://github.com/mongodb/node-mongodb-native/commit/186263f))
+* **monitoring:** correct spelling mistake for heartbeat event ([21aa117](https://github.com/mongodb/node-mongodb-native/commit/21aa117))
+* **replset:** correct server leak on initial connect ([da39d1e](https://github.com/mongodb/node-mongodb-native/commit/da39d1e))
+* **replset:** destroy primary before removing from replsetstate ([45ac09a](https://github.com/mongodb/node-mongodb-native/commit/45ac09a))
+* **replset:** destroy servers that are removed during SDAM flow ([9ea0190](https://github.com/mongodb/node-mongodb-native/commit/9ea0190))
+* **saslprep:** add in missing saslprep dependency ([41f1165](https://github.com/mongodb/node-mongodb-native/commit/41f1165))
+* **topology:** don't early abort server selection on network errors ([2b6a359](https://github.com/mongodb/node-mongodb-native/commit/2b6a359))
+* **topology:** don't emit server closed event on network error ([194dcf0](https://github.com/mongodb/node-mongodb-native/commit/194dcf0))
+* **topology:** include all BSON types in ctor for bson-ext support ([aa4c832](https://github.com/mongodb/node-mongodb-native/commit/aa4c832))
+* **topology:** respect the `force` parameter for topology close ([d6e8936](https://github.com/mongodb/node-mongodb-native/commit/d6e8936))
+
+### Features
+
+* **Update:** add the ability to specify a pipeline to an update command ([#2017](https://github.com/mongodb/node-mongodb-native/issues/2017)) ([44a4110](https://github.com/mongodb/node-mongodb-native/commit/44a4110))
+* **urlParser:** default useNewUrlParser to true ([52d76e3](https://github.com/mongodb/node-mongodb-native/commit/52d76e3))
+
+<a name="3.2.7"></a>
+## [3.2.7](https://github.com/mongodb/node-mongodb-native/compare/v3.2.6...v3.2.7) (2019-06-04)
+
+
+### Bug Fixes
+
+* **core:** updating core to version 3.2.7 ([2f91466](https://github.com/mongodb/node-mongodb-native/commit/2f91466))
+* **findOneAndReplace:** throw error if atomic operators provided for findOneAndReplace ([6a860a3](https://github.com/mongodb/node-mongodb-native/commit/6a860a3))
+
+
+
 <a name="3.3.2"></a>
 ## [3.3.2](https://github.com/mongodb/node-mongodb-native/compare/v3.3.1...v3.3.2) (2019-08-28)
 

package/lib/aggregation_cursor.js

@@ -61,7 +61,7 @@ class AggregationCursor extends Cursor {
   /**
    * Set the batch size for the cursor.
    * @method
-   * @param {number} value The batchSize for the cursor.
+   * @param {number} value The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
    * @throws {MongoError}
    * @return {AggregationCursor}
    */

package/lib/bulk/common.js

@@ -55,60 +55,69 @@ class Batch {
 }
 
 /**
- * Create a new BulkWriteResult instance (INTERNAL TYPE, do not instantiate directly)
- *
- * @class
- * @return {BulkWriteResult} a BulkWriteResult instance
+ * @classdesc
+ * The result of a bulk write.
  */
 class BulkWriteResult {
+  /**
+   * Create a new BulkWriteResult instance
+   *
+   * **NOTE:** Internal Type, do not instantiate directly
+   */
   constructor(bulkResult) {
     this.result = bulkResult;
   }
 
   /**
-   * @return {boolean} ok Did bulk operation correctly execute
+   * Evaluates to true if the bulk operation correctly executes
+   * @type {boolean}
    */
   get ok() {
     return this.result.ok;
   }
 
   /**
-   * @return {number} nInserted number of inserted documents
+   * The number of inserted documents
+   * @type {number}
    */
   get nInserted() {
     return this.result.nInserted;
   }
 
   /**
-   * @return {number} nUpserted Number of upserted documents
+   * Number of upserted documents
+   * @type {number}
    */
   get nUpserted() {
     return this.result.nUpserted;
   }
 
   /**
-   * @return {number} nMatched Number of matched documents
+   * Number of matched documents
+   * @type {number}
    */
   get nMatched() {
     return this.result.nMatched;
   }
 
   /**
-   * @return {number} nModified Number of documents updated physically on disk
+   * Number of documents updated physically on disk
+   * @type {number}
    */
   get nModified() {
     return this.result.nModified;
   }
 
   /**
-   * @return {number} nRemoved Number of removed documents
+   * Number of removed documents
+   * @type {number}
    */
   get nRemoved() {
     return this.result.nRemoved;
   }
 
   /**
-   * Return an array of inserted ids
+   * Returns an array of all inserted ids
    *
    * @return {object[]}
    */
@@ -117,7 +126,7 @@ class BulkWriteResult {
   }
 
   /**
-   * Return an array of upserted ids
+   * Returns an array of all upserted ids
    *
    * @return {object[]}
    */
@@ -126,7 +135,7 @@ class BulkWriteResult {
   }
 
   /**
-   * Return the upserted id at position x
+   * Returns the upserted id at the given index
    *
    * @param {number} index the number of the upserted id to return, returns undefined if no result for passed in index
    * @return {object}
@@ -136,7 +145,7 @@ class BulkWriteResult {
   }
 
   /**
-   * Return raw internal result
+   * Returns raw internal result
    *
    * @return {object}
    */
@@ -178,7 +187,7 @@ class BulkWriteResult {
   /**
    * Retrieve all write errors
    *
-   * @return {object[]}
+   * @return {WriteError[]}
    */
   getWriteErrors() {
     return this.result.writeErrors;
@@ -220,7 +229,7 @@ class BulkWriteResult {
   }
 
   /**
-   * @return {BulkWriteResult} a BulkWriteResult instance
+   * @return {object}
    */
   toJSON() {
     return this.result;
@@ -242,25 +251,29 @@ class BulkWriteResult {
 }
 
 /**
- * Create a new WriteConcernError instance (INTERNAL TYPE, do not instantiate directly)
- *
- * @class
- * @return {WriteConcernError} a WriteConcernError instance
+ * @classdesc An error representing a failure by the server to apply the requested write concern to the bulk operation.
  */
 class WriteConcernError {
+  /**
+   * Create a new WriteConcernError instance
+   *
+   * **NOTE:** Internal Type, do not instantiate directly
+   */
   constructor(err) {
     this.err = err;
   }
 
   /**
-   * @return {number} code Write concern error code.
+   * Write concern error code.
+   * @type {number}
    */
   get code() {
     return this.err.code;
   }
 
   /**
-   * @return {string} errmsg Write concern error message.
+   * Write concern error message.
+   * @type {string}
    */
   get errmsg() {
     return this.err.errmsg;
@@ -282,39 +295,44 @@ class WriteConcernError {
 }
 
 /**
- * Create a new WriteError instance (INTERNAL TYPE, do not instantiate directly)
- *
- * @class
- * @return {WriteConcernError} a WriteConcernError instance
+ * @classdesc An error that occurred during a BulkWrite on the server.
  */
 class WriteError {
+  /**
+   * Create a new WriteError instance
+   *
+   * **NOTE:** Internal Type, do not instantiate directly
+   */
   constructor(err) {
     this.err = err;
   }
 
   /**
-   * @return {number} code Write concern error code.
+   * WriteError code.
+   * @type {number}
    */
   get code() {
     return this.err.code;
   }
 
   /**
-   * @return {number} index Write concern error original bulk operation index.
+   * WriteError original bulk operation index.
+   * @type {number}
    */
   get index() {
     return this.err.index;
   }
 
   /**
-   * @return {string} errmsg Write concern error message.
+   * WriteError message.
+   * @type {string}
    */
   get errmsg() {
     return this.err.errmsg;
   }
 
   /**
-   * Define access methods
+   * Returns the underlying operation that caused the error
    * @return {object}
    */
   getOperation() {
@@ -510,6 +528,7 @@ function executeCommands(bulkOperation, options, callback) {
 /**
  * handles write concern error
  *
+ * @ignore
  * @param {object} batch
  * @param {object} bulkResult
  * @param {boolean} ordered
@@ -531,15 +550,16 @@ function handleMongoWriteConcernError(batch, bulkResult, err, callback) {
 }
 
 /**
- * Creates a new BulkWriteError
- *
- * @class
- * @param {Error|string|object} message The error message
- * @param {BulkWriteResult} result The result of the bulk write operation
- * @return {BulkWriteError} A BulkWriteError instance
- * @extends {MongoError}
+ * @classdesc An error indicating an unsuccessful Bulk Write
  */
 class BulkWriteError extends MongoError {
+  /**
+   * Creates a new BulkWriteError
+   *
+   * @param {Error|string|object} message The error message
+   * @param {BulkWriteResult} result The result of the bulk write operation
+   * @extends {MongoError}
+   */
   constructor(error, result) {
     const message = error.err || error.errmsg || error.errMessage || error;
     super(message);
@@ -552,11 +572,14 @@ class BulkWriteError extends MongoError {
 }
 
 /**
- * Handles the find operators for the bulk operations
- * @class
+ * @classdesc A builder object that is returned from {@link BulkOperationBase#find}.
+ * Is used to build a write operation that involves a query filter.
  */
 class FindOperators {
   /**
+   * Creates a new FindOperators object.
+   *
+   * **NOTE:** Internal Type, do not instantiate directly
    * @param {OrderedBulkOperation|UnorderedBulkOperation} bulkOperation
    */
   constructor(bulkOperation) {
@@ -564,12 +587,12 @@ class FindOperators {
   }
 
   /**
-   * Add a single update document to the bulk operation
+   * Add a multiple update operation to the bulk operation
    *
    * @method
-   * @param {object} updateDocument update operations
-   * @throws {MongoError}
-   * @return {OrderedBulkOperation|UnordedBulkOperation}
+   * @param {object} updateDocument An update field for an update operation. See {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-u u documentation}
+   * @throws {MongoError} If operation cannot be added to bulk write
+   * @return {OrderedBulkOperation|UnorderedBulkOperation} A reference to the parent BulkOperation
    */
   update(updateDocument) {
     // Perform upsert
@@ -589,12 +612,12 @@ class FindOperators {
   }
 
   /**
-   * Add a single update one document to the bulk operation
+   * Add a single update operation to the bulk operation
    *
    * @method
-   * @param {object} updateDocument update operations
-   * @throws {MongoError}
-   * @return {OrderedBulkOperation|UnordedBulkOperation}
+   * @param {object} updateDocument An update field for an update operation. See {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-u u documentation}
+   * @throws {MongoError} If operation cannot be added to bulk write
+   * @return {OrderedBulkOperation|UnorderedBulkOperation} A reference to the parent BulkOperation
    */
   updateOne(updateDocument) {
     // Perform upsert
@@ -618,19 +641,19 @@ class FindOperators {
    *
    * @method
    * @param {object} updateDocument the new document to replace the existing one with
-   * @throws {MongoError}
-   * @return {OrderedBulkOperation|UnorderedBulkOperation}
+   * @throws {MongoError} If operation cannot be added to bulk write
+   * @return {OrderedBulkOperation|UnorderedBulkOperation} A reference to the parent BulkOperation
    */
   replaceOne(updateDocument) {
     this.updateOne(updateDocument);
   }
 
   /**
-   * Upsert modifier for update bulk operation
+   * Upsert modifier for update bulk operation, noting that this operation is an upsert.
    *
    * @method
-   * @throws {MongoError}
-   * @return {FindOperators}
+   * @throws {MongoError} If operation cannot be added to bulk write
+   * @return {FindOperators} reference to self
    */
   upsert() {
     this.s.currentOp.upsert = true;
@@ -641,8 +664,8 @@ class FindOperators {
    * Add a delete one operation to the bulk operation
    *
    * @method
-   * @throws {MongoError}
-   * @return {OrderedBulkOperation|UnordedBulkOperation}
+   * @throws {MongoError} If operation cannot be added to bulk write
+   * @return {OrderedBulkOperation|UnorderedBulkOperation} A reference to the parent BulkOperation
    */
   deleteOne() {
     // Establish the update command
@@ -657,11 +680,11 @@ class FindOperators {
   }
 
   /**
-   * Add a delete operation to the bulk operation
+   * Add a delete many operation to the bulk operation
    *
    * @method
-   * @throws {MongoError}
-   * @return {OrderedBulkOperation|UnordedBulkOperation}
+   * @throws {MongoError} If operation cannot be added to bulk write
+   * @return {OrderedBulkOperation|UnorderedBulkOperation} A reference to the parent BulkOperation
    */
   delete() {
     // Establish the update command
@@ -691,15 +714,14 @@ class FindOperators {
 }
 
 /**
- * Parent class to OrderedBulkOperation and UnorderedBulkOperation
- * @class
+ * @classdesc Parent class to OrderedBulkOperation and UnorderedBulkOperation
+ *
+ * **NOTE:** Internal Type, do not instantiate directly
  */
 class BulkOperationBase {
   /**
-   * Create a new OrderedBulkOperation or UnorderedBulkOperation instance (INTERNAL TYPE, do not instantiate directly)
-   * @class
+   * Create a new OrderedBulkOperation or UnorderedBulkOperation instance
    * @property {number} length Get the number of operations in the bulk.
-   * @return {OrderedBulkOperation|UnordedBulkOperation}
    */
   constructor(topology, collection, options, isOrdered) {
     // determine whether bulkOperation is ordered or unordered
@@ -809,7 +831,16 @@ class BulkOperationBase {
    *
    * @param {object} document the document to insert
    * @throws {MongoError}
-   * @return {OrderedBulkOperation|UnorderedBulkOperation}
+   * @return {BulkOperationBase} A reference to self
+   *
+   * @example
+   * const bulkOp = collection.initializeOrderedBulkOp();
+   * // Adds three inserts to the bulkOp.
+   * bulkOp
+   *   .insert({ a: 1 })
+   *   .insert({ b: 2 })
+   *   .insert({ c: 3 });
+   * await bulkOp.execute();
    */
   insert(document) {
     if (this.s.collection.s.db.options.forceServerObjectId !== true && document._id == null)
@@ -818,11 +849,42 @@ class BulkOperationBase {
   }
 
   /**
-   * Initiate a find operation for an update/updateOne/remove/removeOne/replaceOne
+   * Builds a find operation for an update/updateOne/delete/deleteOne/replaceOne.
+   * Returns a builder object used to complete the definition of the operation.
    *
    * @method
-   * @param {object} selector The selector for the bulk operation.
-   * @throws {MongoError}
+   * @param {object} selector The selector for the bulk operation. See {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-q q documentation}
+   * @throws {MongoError} if a selector is not specified
+   * @return {FindOperators} A helper object with which the write operation can be defined.
+   *
+   * @example
+   * const bulkOp = collection.initializeOrderedBulkOp();
+   *
+   * // Add an updateOne to the bulkOp
+   * bulkOp.find({ a: 1 }).updateOne({ $set: { b: 2 } });
+   *
+   * // Add an updateMany to the bulkOp
+   * bulkOp.find({ c: 3 }).update({ $set: { d: 4 } });
+   *
+   * // Add an upsert
+   * bulkOp.find({ e: 5 }).upsert().updateOne({ $set: { f: 6 } });
+   *
+   * // Add a deletion
+   * bulkOp.find({ g: 7 }).deleteOne();
+   *
+   * // Add a multi deletion
+   * bulkOp.find({ h: 8 }).delete();
+   *
+   * // Add a replaceOne
+   * bulkOp.find({ i: 9 }).replaceOne({ j: 10 });
+   *
+   * // Update using a pipeline (requires Mongodb 4.2 or higher)
+   * bulk.find({ k: 11, y: { $exists: true }, z: { $exists: true } }).updateOne([
+   *   { $set: { total: { $sum: [ '$y', '$z' ] } } }
+   * ]);
+   *
+   * // All of the ops will now be executed
+   * await bulkOp.execute();
    */
   find(selector) {
     if (!selector) {
@@ -838,11 +900,11 @@ class BulkOperationBase {
   }
 
   /**
-   * Raw performs the bulk operation
+   * Specifies a raw operation to perform in the bulk write.
    *
    * @method
-   * @param {object} op operation
-   * @return {OrderedBulkOperation|UnorderedBulkOperation}
+   * @param {object} op The raw operation to perform.
+   * @return {BulkOperationBase} A reference to self
    */
   raw(op) {
     const key = Object.keys(op)[0];
@@ -929,6 +991,12 @@ class BulkOperationBase {
     );
   }
 
+  /**
+   * helper function to assist with promiseOrCallback behavior
+   * @ignore
+   * @param {*} err
+   * @param {*} callback
+   */
   _handleEarlyError(err, callback) {
     if (typeof callback === 'function') {
       callback(err, null);
@@ -939,8 +1007,9 @@ class BulkOperationBase {
   }
 
   /**
-   * Execute next write command in a chain
+   * An internal helper method. Do not invoke directly. Will be going away in the future
    *
+   * @ignore
    * @method
    * @param {class} bulk either OrderedBulkOperation or UnorderdBulkOperation
    * @param {object} writeConcern
@@ -984,19 +1053,21 @@ class BulkOperationBase {
    * @param {MongoError} error An error instance representing the error during the execution.
    * @param {BulkWriteResult} result The bulk write result.
    */
+
   /**
-   * Execute the ordered bulk operation
+   * Execute the bulk operation
    *
    * @method
+   * @param {WriteConcern} [_writeConcern] Optional write concern. Can also be specified through options.
    * @param {object} [options] Optional settings.
    * @param {(number|string)} [options.w] The write concern.
    * @param {number} [options.wtimeout] The write concern timeout.
    * @param {boolean} [options.j=false] Specify a journal write concern.
    * @param {boolean} [options.fsync=false] Specify a file sync write concern.
-   * @param {BulkOperationBase~resultCallback} [callback] The result callback
+   * @param {BulkOperationBase~resultCallback} [callback] A callback that will be invoked when bulkWrite finishes/errors
    * @throws {MongoError} Throws error if the bulk object has already been executed
    * @throws {MongoError} Throws error if the bulk object does not have any operations
-   * @return {Promise} returns Promise if no callback passed
+   * @return {Promise|void} returns Promise if no callback passed
    */
   execute(_writeConcern, options, callback) {
     const ret = this.bulkExecute(_writeConcern, options, callback);
@@ -1013,6 +1084,9 @@ class BulkOperationBase {
   /**
    * Handles final options before executing command
    *
+   * An internal method. Do not invoke. Will not be accessible in the future
+   *
+   * @ignore
    * @param {object} config
    * @param {object} config.options
    * @param {number} config.batch
@@ -1100,6 +1174,9 @@ class BulkOperationBase {
   /**
    * Handles the write error before executing commands
    *
+   * An internal helper method. Do not invoke directly. Will be going away in the future
+   *
+   * @ignore
    * @param {function} callback
    * @param {BulkWriteResult} writeResult
    * @param {class} self either OrderedBulkOperation or UnorderdBulkOperation

package/lib/bulk/ordered.js

@@ -10,6 +10,7 @@ const toError = utils.toError;
 /**
  * Add to internal list of Operations
  *
+ * @ignore
  * @param {OrderedBulkOperation} bulkOperation
  * @param {number} docType number indicating the document type
  * @param {object} document
@@ -82,7 +83,6 @@ function addToOperationsList(bulkOperation, docType, document) {
  * @property {number} length Get the number of operations in the bulk.
  * @return {OrderedBulkOperation} a OrderedBulkOperation instance.
  */
-
 class OrderedBulkOperation extends BulkOperationBase {
   constructor(topology, collection, options) {
     options = options || {};

package/lib/bulk/unordered.js

@@ -10,6 +10,7 @@ const toError = utils.toError;
 /**
  * Add to internal list of Operations
  *
+ * @ignore
  * @param {UnorderedBulkOperation} bulkOperation
  * @param {number} docType number indicating the document type
  * @param {object} document

package/lib/change_stream.js

@@ -39,7 +39,7 @@ const CHANGE_DOMAIN_TYPES = {
  * @property {ResumeToken} [resumeAfter] Allows you to start a changeStream after a specified event. See {@link https://docs.mongodb.com/master/changeStreams/#resumeafter-for-change-streams|ChangeStream documentation}.
  * @property {ResumeToken} [startAfter] Similar to resumeAfter, but will allow you to start after an invalidated event. See {@link https://docs.mongodb.com/master/changeStreams/#startafter-for-change-streams|ChangeStream documentation}.
  * @property {OperationTime} [startAtOperationTime] Will start the changeStream after the specified operationTime.
- * @property {number} [batchSize] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
+ * @property {number} [batchSize=1000] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @property {object} [collation] Specify collation settings for operation. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @property {ReadPreference} [readPreference] The read preference. Defaults to the read preference of the database or collection. See {@link https://docs.mongodb.com/manual/reference/read-preference|read preference documentation}.
  */