mongodb 3.3.1 → 3.3.4

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}.
  */
@@ -367,10 +367,9 @@ function createChangeStreamCursor(self, options) {
 
   const pipeline = [{ $changeStream: changeStreamStageOptions }].concat(self.pipeline);
   const cursorOptions = applyKnownOptions({}, options, CURSOR_OPTIONS);
-  const changeStreamOptions = Object.assign({ batchSize: 1 }, options);
   const changeStreamCursor = new ChangeStreamCursor(
     self.topology,
-    new AggregateOperation(self.parent, pipeline, changeStreamOptions),
+    new AggregateOperation(self.parent, pipeline, options),
     cursorOptions
   );
 

package/lib/collection.js

@@ -260,7 +260,7 @@ const DEPRECATED_FIND_OPTIONS = ['maxScan', 'fields', 'snapshot'];
  * @param {boolean} [options.snapshot=false] DEPRECATED: Snapshot query.
  * @param {boolean} [options.timeout=false] Specify if the cursor can timeout.
  * @param {boolean} [options.tailable=false] Specify if the cursor is tailable.
- * @param {number} [options.batchSize=0] Set the batchSize for the getMoreCommand when iterating over the query results.
+ * @param {number} [options.batchSize=1000] Set the batchSize for the getMoreCommand when iterating over the query results.
  * @param {boolean} [options.returnKey=false] Only return the index key.
  * @param {number} [options.maxScan] DEPRECATED: Limit the number of items to scan.
  * @param {number} [options.min] Set index bounds.
@@ -667,7 +667,7 @@ Collection.prototype.insert = deprecate(function(docs, options, callback) {
  * @property {Object} upsertedId The upserted id.
  * @property {ObjectId} upsertedId._id The upserted _id returned from the server.
  * @property {Object} message
- * @property {Array} ops
+ * @property {object[]} [ops] In a response to {@link Collection#replaceOne replaceOne}, contains the new value of the document on the server. This is the same document that was originally passed in, and is only here for legacy purposes.
  */
 
 /**
@@ -690,6 +690,7 @@ Collection.prototype.insert = deprecate(function(docs, options, callback) {
  * @param {boolean} [options.bypassDocumentValidation=false] Allow driver to bypass schema validation in MongoDB 3.2 or higher.
  * @param {Array} [options.arrayFilters] optional list of array filters referenced in filtered positional operators
  * @param {ClientSession} [options.session] optional session to use for this operation
+ * @param {object} [options.hint] An optional hint for query optimization. See the {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-hint|update command} reference for more information.
  * @param {Collection~updateWriteOpCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
@@ -728,8 +729,9 @@ Collection.prototype.updateOne = function(filter, update, options, callback) {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {boolean} [options.bypassDocumentValidation=false] Allow driver to bypass schema validation in MongoDB 3.2 or higher.
  * @param {ClientSession} [options.session] optional session to use for this operation
+ * @param {object} [options.hint] An optional hint for query optimization. See the {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-hint|update command} reference for more information.
  * @param {Collection~updateWriteOpCallback} [callback] The command result callback
- * @return {Promise<Collection~updatewriteOpResultObject>} returns Promise if no callback passed
+ * @return {Promise<Collection~updateWriteOpResult>} returns Promise if no callback passed
  */
 Collection.prototype.replaceOne = function(filter, doc, options, callback) {
   if (typeof options === 'function') (callback = options), (options = {});
@@ -758,8 +760,9 @@ Collection.prototype.replaceOne = function(filter, doc, options, callback) {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {Array} [options.arrayFilters] optional list of array filters referenced in filtered positional operators
  * @param {ClientSession} [options.session] optional session to use for this operation
+ * @param {object} [options.hint] An optional hint for query optimization. See the {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-hint|update command} reference for more information.
  * @param {Collection~updateWriteOpCallback} [callback] The command result callback
- * @return {Promise<Collection~updateWriteOpResultObject>} returns Promise if no callback passed
+ * @return {Promise<Collection~updateWriteOpResult>} returns Promise if no callback passed
  */
 Collection.prototype.updateMany = function(filter, update, options, callback) {
   if (typeof options === 'function') (callback = options), (options = {});
@@ -799,6 +802,7 @@ Collection.prototype.updateMany = function(filter, update, options, callback) {
  * @param {object} [options.collation] Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields).
  * @param {Array} [options.arrayFilters] optional list of array filters referenced in filtered positional operators
  * @param {ClientSession} [options.session] optional session to use for this operation
+ * @param {object} [options.hint] An optional hint for query optimization. See the {@link https://docs.mongodb.com/manual/reference/command/update/#update-command-hint|update command} reference for more information.
  * @param {Collection~writeOpCallback} [callback] The command result callback
  * @throws {MongoError}
  * @return {Promise} returns Promise if no callback passed
@@ -985,7 +989,7 @@ Collection.prototype.save = deprecate(function(doc, options, callback) {
  * @param {boolean} [options.snapshot=false] DEPRECATED: Snapshot query.
  * @param {boolean} [options.timeout=false] Specify if the cursor can timeout.
  * @param {boolean} [options.tailable=false] Specify if the cursor is tailable.
- * @param {number} [options.batchSize=0] Set the batchSize for the getMoreCommand when iterating over the query results.
+ * @param {number} [options.batchSize=1] Set the batchSize for the getMoreCommand when iterating over the query results.
  * @param {boolean} [options.returnKey=false] Only return the index key.
  * @param {number} [options.maxScan] DEPRECATED: Limit the number of items to scan.
  * @param {number} [options.min] Set index bounds.
@@ -1119,7 +1123,7 @@ Collection.prototype.isCapped = function(options, callback) {
 /**
  * Creates an index on the db and collection collection.
  * @method
- * @param {(string|object)} fieldOrSpec Defines the index.
+ * @param {(string|array|object)} fieldOrSpec Defines the index.
  * @param {object} [options] Optional settings.
  * @param {(number|string)} [options.w] The write concern.
  * @param {number} [options.wtimeout] The write concern timeout.
@@ -1138,6 +1142,25 @@ Collection.prototype.isCapped = function(options, callback) {
  * @param {ClientSession} [options.session] optional session to use for this operation
  * @param {Collection~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
+ * @example
+ * const collection = client.db('foo').collection('bar');
+ *
+ * await collection.createIndex({ a: 1, b: -1 });
+ *
+ * // Alternate syntax for { c: 1, d: -1 } that ensures order of indexes
+ * await collection.createIndex([ [c, 1], [d, -1] ]);
+ *
+ * // Equivalent to { e: 1 }
+ * await collection.createIndex('e');
+ *
+ * // Equivalent to { f: 1, g: 1 }
+ * await collection.createIndex(['f', 'g'])
+ *
+ * // Equivalent to { h: 1, i: -1 }
+ * await collection.createIndex([ { h: 1 }, { i: -1 } ]);
+ *
+ * // Equivalent to { j: 1, k: -1, l: 2d }
+ * await collection.createIndex(['j', ['k', -1], { l: '2d' }])
  */
 Collection.prototype.createIndex = function(fieldOrSpec, options, callback) {
   if (typeof options === 'function') (callback = options), (options = {});
@@ -1153,16 +1176,43 @@ Collection.prototype.createIndex = function(fieldOrSpec, options, callback) {
   return executeOperation(this.s.topology, createIndexOperation, callback);
 };
 
+/**
+ * @typedef {object} Collection~IndexDefinition
+ * @description A definition for an index. Used by the createIndex command.
+ * @see https://docs.mongodb.com/manual/reference/command/createIndexes/
+ */
+
 /**
  * Creates multiple indexes in the collection, this method is only supported for
  * MongoDB 2.6 or higher. Earlier version of MongoDB will throw a command not supported
- * error. Index specifications are defined at http://docs.mongodb.org/manual/reference/command/createIndexes/.
+ * error.
+ *
+ * **Note**: Unlike {@link Collection#createIndex createIndex}, this function takes in raw index specifications.
+ * Index specifications are defined {@link http://docs.mongodb.org/manual/reference/command/createIndexes/ here}.
+ *
  * @method
- * @param {array} indexSpecs An array of index specifications to be created
+ * @param {Collection~IndexDefinition[]} indexSpecs An array of index specifications to be created
  * @param {Object} [options] Optional settings
  * @param {ClientSession} [options.session] optional session to use for this operation
  * @param {Collection~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
+ * @example
+ * const collection = client.db('foo').collection('bar');
+ * await collection.createIndexes([
+ *   // Simple index on field fizz
+ *   {
+ *     key: { fizz: 1 },
+ *   }
+ *   // wildcard index
+ *   {
+ *     key: { '$**': 1 }
+ *   },
+ *   // named index on darmok and jalad
+ *   {
+ *     key: { darmok: 1, jalad: -1 }
+ *     name: 'tanagra'
+ *   }
+ * ]);
  */
 Collection.prototype.createIndexes = function(indexSpecs, options, callback) {
   if (typeof options === 'function') (callback = options), (options = {});
@@ -1256,7 +1306,7 @@ Collection.prototype.reIndex = function(options, callback) {
  *
  * @method
  * @param {object} [options] Optional settings.
- * @param {number} [options.batchSize] The batchSize for the returned command cursor or if pre 2.8 the systems batch collection
+ * @param {number} [options.batchSize=1000] The batchSize for the returned command cursor or if pre 2.8 the systems batch collection
  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @param {ClientSession} [options.session] optional session to use for this operation
  * @return {CommandCursor}
@@ -1355,7 +1405,12 @@ Collection.prototype.indexInformation = function(options, callback) {
  */
 
 /**
- * Count number of matching documents in the db to a query.
+ * An estimated count of matching documents in the db to a query.
+ *
+ * **NOTE:** This method has been deprecated, since it does not provide an accurate count of the documents
+ * in a collection. To obtain an accurate count of documents in the collection, use {@link Collection#countDocuments countDocuments}.
+ * To obtain an estimated count of all documents in the collection, use {@link Collection#estimatedDocumentCount estimatedDocumentCount}.
+ *
  * @method
  * @param {object} [query={}] The query for the count.
  * @param {object} [options] Optional settings.
@@ -1451,7 +1506,7 @@ Collection.prototype.countDocuments = function(query, options, callback) {
  * The distinct command returns a list of distinct values for the given key across a collection.
  * @method
  * @param {string} key Field of the document to find distinct values for.
- * @param {object} query The query for filtering the set of documents to which we apply the distinct filter.
+ * @param {object} [query] The query for filtering the set of documents to which we apply the distinct filter.
  * @param {object} [options] Optional settings.
  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @param {number} [options.maxTimeMS] Number of milliseconds to wait before aborting the query.
@@ -1510,7 +1565,7 @@ Collection.prototype.stats = function(options, callback) {
 /**
  * @typedef {Object} Collection~findAndModifyWriteOpResult
  * @property {object} value Document returned from the `findAndModify` command. If no documents were found, `value` will be `null` by default (`returnOriginal: true`), even if a document was upserted; if `returnOriginal` was false, the upserted document will be returned in that case.
- * @property {object} lastErrorObject The raw lastErrorObject returned from the command.
+ * @property {object} lastErrorObject The raw lastErrorObject returned from the command. See {@link https://docs.mongodb.com/manual/reference/command/findAndModify/index.html#lasterrorobject|findAndModify command documentation}.
  * @property {Number} ok Is 1 if the command executed correctly.
  */
 
@@ -1716,7 +1771,7 @@ Collection.prototype.findAndRemove = deprecate(function(query, sort, options, ca
  * @param {object} [options] Optional settings.
  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @param {object} [options.cursor] Return the query as cursor, on 2.6 > it returns as a real cursor on pre 2.6 it returns as an emulated cursor.
- * @param {number} [options.cursor.batchSize] The batchSize for the cursor
+ * @param {number} [options.cursor.batchSize=1000] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @param {boolean} [options.explain=false] Explain returns the aggregation execution plan (requires mongodb 2.6 >).
  * @param {boolean} [options.allowDiskUse=false] allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 >).
  * @param {number} [options.maxTimeMS] maxTimeMS specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point.
@@ -1792,7 +1847,7 @@ Collection.prototype.aggregate = function(pipeline, options, callback) {
  * @param {string} [options.fullDocument='default'] Allowed values: ‘default’, ‘updateLookup’. When set to ‘updateLookup’, the change stream will include both a delta describing the changes to the document, as well as a copy of the entire document that was changed from some time after the change occurred.
  * @param {object} [options.resumeAfter] Specifies the logical starting point for the new change stream. This should be the _id field from a previously returned change stream document.
  * @param {number} [options.maxAwaitTimeMS] The maximum amount of time for the server to wait on new documents to satisfy a change stream query
- * @param {number} [options.batchSize] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
+ * @param {number} [options.batchSize=1000] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @param {object} [options.collation] Specify collation settings for operation. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @param {ReadPreference} [options.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}.
  * @param {Timestamp} [options.startAtOperationTime] receive change events that occur after the specified timestamp
@@ -1825,7 +1880,7 @@ Collection.prototype.watch = function(pipeline, options) {
  * @method
  * @param {object} [options] Optional settings.
  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
- * @param {number} [options.batchSize] Set the batchSize for the getMoreCommand when iterating over the query results.
+ * @param {number} [options.batchSize=1000] Set the batchSize for the getMoreCommand when iterating over the query results.
  * @param {number} [options.numCursors=1] The maximum number of parallel command cursors to return (the number of returned cursors will be in the range 1:numCursors)
  * @param {boolean} [options.raw=false] Return all BSON documents as Raw Buffer documents.
  * @param {Collection~parallelCollectionScanCallback} [callback] The command result callback

package/lib/command_cursor.js

@@ -90,7 +90,7 @@ class CommandCursor 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/find/|find command documentation}.
    * @throws {MongoError}
    * @return {CommandCursor}
    */

package/lib/core/connection/connect.js

@@ -15,6 +15,7 @@ const MIN_SUPPORTED_SERVER_VERSION = WIRE_CONSTANTS.MIN_SUPPORTED_SERVER_VERSION
 let AUTH_PROVIDERS;
 
 function connect(options, callback) {
+  const ConnectionType = options && options.connectionType ? options.connectionType : Connection;
   if (AUTH_PROVIDERS == null) {
     AUTH_PROVIDERS = defaultAuthProviders(options.bson);
   }
@@ -26,7 +27,7 @@ function connect(options, callback) {
         return;
       }
 
-      performInitialHandshake(new Connection(socket, options), options, callback);
+      performInitialHandshake(new ConnectionType(socket, options), options, callback);
     });
 
     return;
@@ -40,13 +41,13 @@ function connect(options, callback) {
           return;
         }
 
-        performInitialHandshake(new Connection(ipv4Socket, options), options, callback);
+        performInitialHandshake(new ConnectionType(ipv4Socket, options), options, callback);
       });
 
       return;
     }
 
-    performInitialHandshake(new Connection(ipv6Socket, options), options, callback);
+    performInitialHandshake(new ConnectionType(ipv6Socket, options), options, callback);
   });
 }
 
@@ -314,11 +315,25 @@ function runCommand(conn, ns, command, options, callback) {
     numberToReturn: 1
   });
 
+  const noop = () => {};
+  function _callback(err, result) {
+    callback(err, result);
+    callback = noop;
+  }
+
   function errorHandler(err) {
     conn.resetSocketTimeout();
     CONNECTION_ERROR_EVENTS.forEach(eventName => conn.removeListener(eventName, errorHandler));
     conn.removeListener('message', messageHandler);
-    callback(err, null);
+
+    if (err == null) {
+      err = new MongoError(`runCommand failed for connection to '${conn.address}'`);
+    }
+
+    // ignore all future errors
+    conn.on('error', noop);
+
+    _callback(err, null);
   }
 
   function messageHandler(msg) {
@@ -331,7 +346,7 @@ function runCommand(conn, ns, command, options, callback) {
     conn.removeListener('message', messageHandler);
 
     msg.parse({ promoteValues: true });
-    callback(null, msg.documents[0]);
+    _callback(null, msg.documents[0]);
   }
 
   conn.setSocketTimeout(socketTimeout);

package/lib/core/connection/connection.js

@@ -56,10 +56,13 @@ class Connection extends EventEmitter {
   /**
    * Creates a new Connection instance
    *
+   * **NOTE**: Internal class, do not instantiate directly
+   *
    * @param {Socket} socket The socket this connection wraps
-   * @param {Object} [options] Optional settings
-   * @param {string} [options.host] The host the socket is connected to
-   * @param {number} [options.port] The port used for the socket connection
+   * @param {Object} options Various settings
+   * @param {object} options.bson An implementation of bson serialize and deserialize
+   * @param {string} [options.host='localhost'] The host the socket is connected to
+   * @param {number} [options.port=27017] The port used for the socket connection
    * @param {boolean} [options.keepAlive=true] TCP Connection keep alive enabled
    * @param {number} [options.keepAliveInitialDelay=300000] Initial delay before TCP keep alive enabled
    * @param {number} [options.connectionTimeout=30000] TCP Connection timeout setting
@@ -67,6 +70,7 @@ class Connection extends EventEmitter {
    * @param {boolean} [options.promoteLongs] Convert Long values from the db into Numbers if they fit into 53 bits
    * @param {boolean} [options.promoteValues] Promotes BSON values to native types where possible, set to false to only receive wrapper types.
    * @param {boolean} [options.promoteBuffers] Promotes Binary BSON values to native Node Buffers.
+   * @param {number} [options.maxBsonMessageSize=0x4000000] Largest possible size of a BSON message (for legacy purposes)
    */
   constructor(socket, options) {
     super();

package/lib/core/connection/msg.js

@@ -27,6 +27,7 @@
 //   [uint32     checksum;]
 // };
 
+const Buffer = require('safe-buffer').Buffer;
 const opcodes = require('../wireprotocol/shared').opcodes;
 const databaseNamespace = require('../wireprotocol/shared').databaseNamespace;
 const ReadPreference = require('../topologies/read_preference');
@@ -90,7 +91,7 @@ class Msg {
       flags |= OPTS_EXHAUST_ALLOWED;
     }
 
-    const header = new Buffer(
+    const header = Buffer.alloc(
       4 * 4 + // Header
         4 // Flags
     );
@@ -110,7 +111,7 @@ class Msg {
   }
 
   makeDocumentSegment(buffers, document) {
-    const payloadTypeBuffer = new Buffer(1);
+    const payloadTypeBuffer = Buffer.alloc(1);
     payloadTypeBuffer[0] = 0;
 
     const documentBuffer = this.serializeBson(document);