mongodb 3.3.2 → 3.3.3

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.
  */
 
 /**
@@ -729,7 +729,7 @@ Collection.prototype.updateOne = function(filter, update, options, callback) {
  * @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 {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 = {});
@@ -759,7 +759,7 @@ Collection.prototype.replaceOne = function(filter, doc, options, callback) {
  * @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 {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 = {});
@@ -985,7 +985,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 +1119,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 +1138,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 +1172,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 +1302,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 +1401,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.
@@ -1510,7 +1561,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 +1767,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 +1843,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 +1876,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/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);

package/lib/core/connection/pool.js

@@ -3,7 +3,7 @@
 const inherits = require('util').inherits;
 const EventEmitter = require('events').EventEmitter;
 const MongoError = require('../error').MongoError;
-const MongoNetworkError = require('../error').MongoNetworkError;
+const MongoTimeoutError = require('../error').MongoTimeoutError;
 const MongoWriteConcernError = require('../error').MongoWriteConcernError;
 const Logger = require('./logger');
 const f = require('util').format;
@@ -60,7 +60,7 @@ var _id = 0;
  * @param {Buffer} [options.crl] SSL Certificate revocation store binary buffer
  * @param {Buffer} [options.cert] SSL Certificate binary buffer
  * @param {Buffer} [options.key] SSL Key file binary buffer
- * @param {string} [options.passPhrase] SSL Certificate pass phrase
+ * @param {string} [options.passphrase] SSL Certificate pass phrase
  * @param {boolean} [options.rejectUnauthorized=false] Reject unauthorized server certificates
  * @param {boolean} [options.promoteLongs=true] Convert Long values from the db into Numbers if they fit into 53 bits
  * @param {boolean} [options.promoteValues=true] Promotes BSON values to native types where possible, set to false to only receive wrapper types.
@@ -103,7 +103,7 @@ var Pool = function(topology, options) {
       crl: null,
       cert: null,
       key: null,
-      passPhrase: null,
+      passphrase: null,
       rejectUnauthorized: false,
       promoteLongs: true,
       promoteValues: true,
@@ -113,7 +113,9 @@ var Pool = function(topology, options) {
       reconnectInterval: 1000,
       reconnectTries: 30,
       // Enable domains
-      domainsEnabled: false
+      domainsEnabled: false,
+      // feature flag for determining if we are running with the unified topology or not
+      legacyCompatMode: true
     },
     options
   );
@@ -123,6 +125,7 @@ var Pool = function(topology, options) {
   // Current reconnect retries
   this.retriesLeft = this.options.reconnectTries;
   this.reconnectId = null;
+  this.reconnectError = null;
   // No bson parser passed in
   if (
     !options.bson ||
@@ -146,9 +149,6 @@ var Pool = function(topology, options) {
   // Operation work queue
   this.queue = [];
 
-  // Contains the reconnect connection
-  this.reconnectConnection = null;
-
   // Number of consecutive timeouts caught
   this.numberOfConsecutiveTimeouts = 0;
   // Current pool Index
@@ -214,7 +214,6 @@ function resetPoolState(pool) {
   pool.availableConnections = [];
   pool.connectingConnections = 0;
   pool.executing = false;
-  pool.reconnectConnection = null;
   pool.numberOfConsecutiveTimeouts = 0;
   pool.connectionIndex = 0;
   pool.retriesLeft = pool.options.reconnectTries;
@@ -293,73 +292,62 @@ function connectionFailureHandler(pool, event, err, conn) {
 
   // Start reconnection attempts
   if (!pool.reconnectId && pool.options.reconnect) {
+    pool.reconnectError = err;
     pool.reconnectId = setTimeout(attemptReconnect(pool), pool.options.reconnectInterval);
   }
 
   // Do we need to do anything to maintain the minimum pool size
   const totalConnections = totalConnectionCount(pool);
   if (totalConnections < pool.minSize) {
-    _createConnection(pool);
+    createConnection(pool);
   }
 }
 
-function attemptReconnect(self) {
+function attemptReconnect(pool, callback) {
   return function() {
-    self.emit('attemptReconnect', self);
-    if (self.state === DESTROYED || self.state === DESTROYING) return;
+    pool.emit('attemptReconnect', pool);
+
+    if (pool.state === DESTROYED || pool.state === DESTROYING) {
+      if (typeof callback === 'function') {
+        callback(new MongoError('Cannot create connection when pool is destroyed'));
+      }
 
-    // We are connected do not try again
-    if (self.isConnected()) {
-      self.reconnectId = null;
       return;
     }
 
-    self.connectingConnections++;
-    connect(self.options, (err, connection) => {
-      self.connectingConnections--;
+    pool.retriesLeft = pool.retriesLeft - 1;
+    if (pool.retriesLeft <= 0) {
+      pool.destroy();
 
-      if (err) {
-        if (self.logger.isDebug()) {
-          self.logger.debug(`connection attempt failed with error [${JSON.stringify(err)}]`);
-        }
-
-        self.retriesLeft = self.retriesLeft - 1;
-        if (self.retriesLeft <= 0) {
-          self.destroy();
-          self.emit(
-            'reconnectFailed',
-            new MongoNetworkError(
-              f(
-                'failed to reconnect after %s attempts with interval %s ms',
-                self.options.reconnectTries,
-                self.options.reconnectInterval
-              )
-            )
-          );
-        } else {
-          self.reconnectId = setTimeout(attemptReconnect(self), self.options.reconnectInterval);
-        }
+      const error = new MongoTimeoutError(
+        `failed to reconnect after ${pool.options.reconnectTries} attempts with interval ${
+          pool.options.reconnectInterval
+        } ms`,
+        pool.reconnectError
+      );
 
-        return;
+      pool.emit('reconnectFailed', error);
+      if (typeof callback === 'function') {
+        callback(error);
       }
 
-      if (self.state === DESTROYED || self.state === DESTROYING) {
-        return connection.destroy();
+      return;
+    }
+
+    // clear the reconnect id on retry
+    pool.reconnectId = null;
+
+    // now retry creating a connection
+    createConnection(pool, (err, conn) => {
+      if (err == null) {
+        pool.reconnectId = null;
+        pool.retriesLeft = pool.options.reconnectTries;
+        pool.emit('reconnect', pool);
       }
 
-      self.reconnectId = null;
-      handlers.forEach(event => connection.removeAllListeners(event));
-      connection.on('error', self._connectionErrorHandler);
-      connection.on('close', self._connectionCloseHandler);
-      connection.on('timeout', self._connectionTimeoutHandler);
-      connection.on('parseError', self._connectionParseErrorHandler);
-      connection.on('message', self._messageHandler);
-
-      self.retriesLeft = self.options.reconnectTries;
-      self.availableConnections.push(connection);
-      self.reconnectConnection = null;
-      self.emit('reconnect', self);
-      _execute(self)();
+      if (typeof callback === 'function') {
+        callback(err, conn);
+      }
     });
   };
 }
@@ -564,64 +552,26 @@ Pool.prototype.connect = function() {
     throw new MongoError('connection in unlawful state ' + this.state);
   }
 
-  const self = this;
   stateTransition(this, CONNECTING);
-
-  self.connectingConnections++;
-  connect(self.options, (err, connection) => {
-    self.connectingConnections--;
-
+  createConnection(this, (err, conn) => {
     if (err) {
-      if (self.logger.isDebug()) {
-        self.logger.debug(`connection attempt failed with error [${JSON.stringify(err)}]`);
-      }
-
-      if (self.state === CONNECTING) {
-        self.emit('error', err);
+      if (this.state === CONNECTING) {
+        this.emit('error', err);
       }
 
+      this.destroy();
       return;
     }
 
-    if (self.state === DESTROYED || self.state === DESTROYING) {
-      return self.destroy();
-    }
-
-    // attach event handlers
-    connection.on('error', self._connectionErrorHandler);
-    connection.on('close', self._connectionCloseHandler);
-    connection.on('timeout', self._connectionTimeoutHandler);
-    connection.on('parseError', self._connectionParseErrorHandler);
-    connection.on('message', self._messageHandler);
-
-    // If we are in a topology, delegate the auth to it
-    // This is to avoid issues where we would auth against an
-    // arbiter
-    if (self.options.inTopology) {
-      stateTransition(self, CONNECTED);
-      self.availableConnections.push(connection);
-      return self.emit('connect', self, connection);
-    }
-
-    if (self.state === DESTROYED || self.state === DESTROYING) {
-      return self.destroy();
-    }
-
-    if (err) {
-      self.destroy();
-      return self.emit('error', err);
-    }
+    stateTransition(this, CONNECTED);
+    this.emit('connect', this, conn);
 
-    stateTransition(self, CONNECTED);
-    self.availableConnections.push(connection);
-
-    if (self.minSize) {
-      for (let i = 0; i < self.minSize; i++) {
-        _createConnection(self);
+    // create min connections
+    if (this.minSize) {
+      for (let i = 0; i < this.minSize; i++) {
+        createConnection(this);
       }
     }
-
-    self.emit('connect', self, connection);
   });
 };
 
@@ -718,12 +668,6 @@ Pool.prototype.destroy = function(force, callback) {
     clearTimeout(this.reconnectId);
   }
 
-  // If we have a reconnect connection running, close
-  // immediately
-  if (this.reconnectConnection) {
-    this.reconnectConnection.destroy();
-  }
-
   // Wait for the operations to drain before we close the pool
   function checkStatus() {
     flushMonitoringOperations(self.queue);
@@ -782,7 +726,7 @@ Pool.prototype.reset = function(callback) {
       resetPoolState(this);
 
       // create an initial connection, and kick off execution again
-      _createConnection(this);
+      createConnection(this);
 
       if (typeof callback === 'function') {
         callback(null, null);
@@ -996,55 +940,82 @@ function removeConnection(self, connection) {
   if (remove(connection, self.inUseConnections)) return;
 }
 
-const handlers = ['close', 'message', 'error', 'timeout', 'parseError', 'connect'];
-function _createConnection(self) {
-  if (self.state === DESTROYED || self.state === DESTROYING) {
+function createConnection(pool, callback) {
+  if (pool.state === DESTROYED || pool.state === DESTROYING) {
+    if (typeof callback === 'function') {
+      callback(new MongoError('Cannot create connection when pool is destroyed'));
+    }
+
     return;
   }
 
-  self.connectingConnections++;
-  connect(self.options, (err, connection) => {
-    self.connectingConnections--;
+  pool.connectingConnections++;
+  connect(pool.options, (err, connection) => {
+    pool.connectingConnections--;
 
     if (err) {
-      if (self.logger.isDebug()) {
-        self.logger.debug(`connection attempt failed with error [${JSON.stringify(err)}]`);
+      if (pool.logger.isDebug()) {
+        pool.logger.debug(`connection attempt failed with error [${JSON.stringify(err)}]`);
       }
 
-      if (!self.reconnectId && self.options.reconnect) {
-        self.reconnectId = setTimeout(attemptReconnect(self), self.options.reconnectInterval);
+      if (pool.options.legacyCompatMode === false) {
+        // The unified topology uses the reported `error` from a pool to track what error
+        // reason is returned to the user during selection timeout. We only want to emit
+        // this if the pool is active because the listeners are removed on destruction.
+        if (pool.state !== DESTROYED && pool.state !== DESTROYING) {
+          pool.emit('error', err);
+        }
       }
 
-      return;
-    }
+      // check if reconnect is enabled, and attempt retry if so
+      if (!pool.reconnectId && pool.options.reconnect) {
+        if (pool.state === CONNECTING && pool.options.legacyCompatMode) {
+          callback(err);
+          return;
+        }
 
-    if (self.state === DESTROYED || self.state === DESTROYING) {
-      removeConnection(self, connection);
-      return connection.destroy();
+        pool.reconnectError = err;
+        pool.reconnectId = setTimeout(
+          attemptReconnect(pool, callback),
+          pool.options.reconnectInterval
+        );
+
+        return;
+      }
+
+      if (typeof callback === 'function') {
+        callback(err);
+      }
+
+      return;
     }
 
-    connection.on('error', self._connectionErrorHandler);
-    connection.on('close', self._connectionCloseHandler);
-    connection.on('timeout', self._connectionTimeoutHandler);
-    connection.on('parseError', self._connectionParseErrorHandler);
-    connection.on('message', self._messageHandler);
+    // the pool might have been closed since we started creating the connection
+    if (pool.state === DESTROYED || pool.state === DESTROYING) {
+      if (typeof callback === 'function') {
+        callback(new MongoError('Pool was destroyed after connection creation'));
+      }
 
-    if (self.state === DESTROYED || self.state === DESTROYING) {
-      return connection.destroy();
+      connection.destroy();
+      return;
     }
 
-    // Remove the connection from the connectingConnections list
-    removeConnection(self, connection);
+    // otherwise, connect relevant event handlers and add it to our available connections
+    connection.on('error', pool._connectionErrorHandler);
+    connection.on('close', pool._connectionCloseHandler);
+    connection.on('timeout', pool._connectionTimeoutHandler);
+    connection.on('parseError', pool._connectionParseErrorHandler);
+    connection.on('message', pool._messageHandler);
 
-    // Handle error
-    if (err) {
-      return connection.destroy();
+    pool.availableConnections.push(connection);
+
+    // if a callback was provided, return the connection
+    if (typeof callback === 'function') {
+      callback(null, connection);
     }
 
-    // Push to available
-    self.availableConnections.push(connection);
-    // Execute any work waiting
-    _execute(self)();
+    // immediately execute any waiting work
+    _execute(pool)();
   });
 }
 
@@ -1146,7 +1117,7 @@ function _execute(self) {
           // Attempt to grow the pool if it's not yet maxsize
           if (totalConnections < self.options.size && self.queue.length > 0) {
             // Create a new connection
-            _createConnection(self);
+            createConnection(self);
           }
 
           // Re-execute the operation
@@ -1166,7 +1137,7 @@ function _execute(self) {
           // Lets put the workItem back on the list
           self.queue.unshift(workItem);
           // Create a new connection
-          _createConnection(self);
+          createConnection(self);
           // Break from the loop
           break;
         }

package/lib/core/cursor.js

@@ -68,7 +68,7 @@ class CoreCursor extends Readable {
    * @param {string} ns The MongoDB fully qualified namespace (ex: db1.collection1)
    * @param {{object}|Long} cmd The selector (can be a command or a cursorId)
    * @param {object} [options=null] Optional settings.
-   * @param {object} [options.batchSize=1000] Batchsize for the operation
+   * @param {object} [options.batchSize=1000] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/find/| find command documentation} and {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
    * @param {array} [options.documents=[]] Initial documents list for cursor
    * @param {object} [options.transforms=null] Transform methods for the cursor results
    * @param {function} [options.transforms.query] Transform the value returned from the initial query