Node.js MongoDB Driver API

Source: lib/mongo_client.js

  1. 'use strict';
  3. const ChangeStream = require('./change_stream');
  4. const Db = require('./db');
  5. const EventEmitter = require('events').EventEmitter;
  6. const inherits = require('util').inherits;
  7. const MongoError = require('./core').MongoError;
  8. const deprecate = require('util').deprecate;
  9. const WriteConcern = require('./write_concern');
  10. const MongoDBNamespace = require('./utils').MongoDBNamespace;
  11. const ReadPreference = require('./core/topologies/read_preference');
  12. const maybePromise = require('./utils').maybePromise;
  13. const NativeTopology = require('./topologies/native_topology');
  14. const connect = require('./operations/connect').connect;
  15. const validOptions = require('./operations/connect').validOptions;
  17. /**
  18.  * @fileOverview The **MongoClient** class is a class that allows for making Connections to MongoDB.
  19.  *
  20.  * @example
  21.  * // Connect using a MongoClient instance
  22.  * const MongoClient = require('mongodb').MongoClient;
  23.  * const test = require('assert');
  24.  * // Connection url
  25.  * const url = 'mongodb://localhost:27017';
  26.  * // Database Name
  27.  * const dbName = 'test';
  28.  * // Connect using MongoClient
  29.  * const mongoClient = new MongoClient(url);
  30.  * mongoClient.connect(function(err, client) {
  31.  *   const db = client.db(dbName);
  32.  *   client.close();
  33.  * });
  34.  *
  35.  * @example
  36.  * // Connect using the MongoClient.connect static method
  37.  * const MongoClient = require('mongodb').MongoClient;
  38.  * const test = require('assert');
  39.  * // Connection url
  40.  * const url = 'mongodb://localhost:27017';
  41.  * // Database Name
  42.  * const dbName = 'test';
  43.  * // Connect using MongoClient
  44.  * MongoClient.connect(url, function(err, client) {
  45.  *   const db = client.db(dbName);
  46.  *   client.close();
  47.  * });
  48.  */
  50. /**
  51.  * A string specifying the level of a ReadConcern
  52.  * @typedef {'local'|'available'|'majority'|'linearizable'|'snapshot'} ReadConcernLevel
  53.  * @see https://www.mongodb.com/docs/manual/reference/read-concern/index.html#read-concern-levels
  54.  */
  56. /**
  57.  * Configuration options for drivers wrapping the node driver.
  58.  *
  59.  * @typedef {Object} DriverInfoOptions
  60.  * @property {string} [name] The name of the driver
  61.  * @property {string} [version] The version of the driver
  62.  * @property {string} [platform] Optional platform information
  63.  */
  65. /**
  66.  * Configuration options for drivers wrapping the node driver.
  67.  *
  68.  * @typedef {Object} DriverInfoOptions
  69.  * @property {string} [name] The name of the driver
  70.  * @property {string} [version] The version of the driver
  71.  * @property {string} [platform] Optional platform information
  72.  */
  74. /**
  75.  * Creates a new MongoClient instance
  76.  * @class
  77.  * @param {string} url The connection URI string
  78.  * @param {object} [options] Optional settings
  79.  * @param {number} [options.poolSize=5] The maximum size of the individual server pool
  80.  * @param {boolean} [options.ssl=false] Enable SSL connection. *deprecated* use `tls` variants
  81.  * @param {boolean} [options.sslValidate=false] Validate mongod server certificate against Certificate Authority
  82.  * @param {buffer} [options.sslCA=undefined] SSL Certificate store binary buffer *deprecated* use `tls` variants
  83.  * @param {buffer} [options.sslCert=undefined] SSL Certificate binary buffer *deprecated* use `tls` variants
  84.  * @param {buffer} [options.sslKey=undefined] SSL Key file binary buffer *deprecated* use `tls` variants
  85.  * @param {string} [options.sslPass=undefined] SSL Certificate pass phrase *deprecated* use `tls` variants
  86.  * @param {buffer} [options.sslCRL=undefined] SSL Certificate revocation list binary buffer *deprecated* use `tls` variants
  87.  * @param {boolean|function} [options.checkServerIdentity=true] Ensure we check server identify during SSL, set to false to disable checking. Only works for Node 0.12.x or higher. You can pass in a boolean or your own checkServerIdentity override function. *deprecated* use `tls` variants
  88.  * @param {boolean} [options.tls=false] Enable TLS connections
  89.  * @param {boolean} [options.tlsInsecure=false] Relax TLS constraints, disabling validation
  90.  * @param {string} [options.tlsCAFile] A path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection
  91.  * @param {string} [options.tlsCertificateKeyFile] A path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated
  92.  * @param {string} [options.tlsCertificateKeyFilePassword] The password to decrypt the client private key to be used for TLS connections
  93.  * @param {boolean} [options.tlsAllowInvalidCertificates] Specifies whether or not the driver should error when the server’s TLS certificate is invalid
  94.  * @param {boolean} [options.tlsAllowInvalidHostnames] Specifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate
  95.  * @param {boolean} [options.autoReconnect=true] Enable autoReconnect for single server instances
  96.  * @param {boolean} [options.noDelay=true] TCP Connection no delay
  97.  * @param {boolean} [options.keepAlive=true] TCP Connection keep alive enabled
  98.  * @param {number} [options.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  99.  * @param {number} [options.connectTimeoutMS=10000] How long to wait for a connection to be established before timing out
  100.  * @param {number} [options.socketTimeoutMS=360000] How long a send or receive on a socket can take before timing out
  101.  * @param {number} [options.family] Version of IP stack. Can be 4, 6 or null (default).
  102.  * If null, will attempt to connect with IPv6, and will fall back to IPv4 on failure
  103.  * @param {number} [options.reconnectTries=30] Server attempt to reconnect #times
  104.  * @param {number} [options.reconnectInterval=1000] Server will wait # milliseconds between retries
  105.  * @param {boolean} [options.ha=true] Control if high availability monitoring runs for Replicaset or Mongos proxies
  106.  * @param {number} [options.haInterval=10000] The High availability period for replicaset inquiry
  107.  * @param {string} [options.replicaSet=undefined] The Replicaset set name
  108.  * @param {number} [options.secondaryAcceptableLatencyMS=15] Cutoff latency point in MS for Replicaset member selection
  109.  * @param {number} [options.acceptableLatencyMS=15] Cutoff latency point in MS for Mongos proxies selection
  110.  * @param {boolean} [options.connectWithNoPrimary=false] Sets if the driver should connect even if no primary is available
  111.  * @param {string} [options.authSource=undefined] Define the database to authenticate against
  112.  * @param {(number|string)} [options.w] The write concern
  113.  * @param {number} [options.wtimeout] The write concern timeout
  114.  * @param {boolean} [options.j=false] Specify a journal write concern
  115.  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver
  116.  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object
  117.  * @param {Boolean} [options.ignoreUndefined=false] Specify if the BSON serializer should ignore undefined fields
  118.  * @param {boolean} [options.raw=false] Return document results as raw BSON buffers
  119.  * @param {number} [options.bufferMaxEntries=-1] Sets a cap on how many operations the driver will buffer up before giving up on getting a working connection, default is -1 which is unlimited
  120.  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST)
  121.  * @param {object} [options.pkFactory] A primary key factory object for generation of custom _id keys
  122.  * @param {object} [options.promiseLibrary] A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
  123.  * @param {object} [options.readConcern] Specify a read concern for the collection (only MongoDB 3.2 or higher supported)
  124.  * @param {ReadConcernLevel} [options.readConcern.level='local'] Specify a read concern level for the collection operations (only MongoDB 3.2 or higher supported)
  125.  * @param {number} [options.maxStalenessSeconds=undefined] The max staleness to secondary reads (values under 10 seconds cannot be guaranteed)
  126.  * @param {string} [options.loggerLevel=undefined] The logging level (error/warn/info/debug)
  127.  * @param {object} [options.logger=undefined] Custom logger object
  128.  * @param {boolean} [options.promoteValues=true] Promotes BSON values to native types where possible, set to false to only receive wrapper types
  129.  * @param {boolean} [options.promoteBuffers=false] Promotes Binary BSON values to native Node Buffers
  130.  * @param {boolean} [options.promoteLongs=true] Promotes long values to number if they fit inside the 53 bits resolution
  131.  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit
  132.  * @param {object} [options.validateOptions=false] Validate MongoClient passed in options for correctness
  133.  * @param {string} [options.appname=undefined] The name of the application that created this MongoClient instance. MongoDB 3.4 and newer will print this value in the server log upon establishing each connection. It is also recorded in the slow query log and profile collections
  134.  * @param {string} [options.auth.user=undefined] The username for auth
  135.  * @param {string} [options.auth.password=undefined] The password for auth
  136.  * @param {string} [options.authMechanism=undefined] Mechanism for authentication: MDEFAULT, GSSAPI, PLAIN, MONGODB-X509, or SCRAM-SHA-1
  137.  * @param {object} [options.compression] Type of compression to use: snappy or zlib
  138.  * @param {boolean} [options.fsync=false] Specify a file sync write concern
  139.  * @param {array} [options.readPreferenceTags] Read preference tags
  140.  * @param {number} [options.numberOfRetries=5] The number of retries for a tailable cursor
  141.  * @param {boolean} [options.auto_reconnect=true] Enable auto reconnecting for single server instances
  142.  * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this client
  143.  * @param {number} [options.minSize] If present, the connection pool will be initialized with minSize connections, and will never dip below minSize connections
  144.  * @param {boolean} [options.useNewUrlParser=true] Determines whether or not to use the new url parser. Enables the new, spec-compliant, url parser shipped in the core driver. This url parser fixes a number of problems with the original parser, and aims to outright replace that parser in the near future. Defaults to true, and must be explicitly set to false to use the legacy url parser.
  145.  * @param {boolean} [options.useUnifiedTopology] Enables the new unified topology layer
  146.  * @param {Number} [options.localThresholdMS=15] **Only applies to the unified topology** The size of the latency window for selecting among multiple suitable servers
  147.  * @param {Number} [options.serverSelectionTimeoutMS=30000] **Only applies to the unified topology** How long to block for server selection before throwing an error
  148.  * @param {Number} [options.heartbeatFrequencyMS=10000] **Only applies to the unified topology** The frequency with which topology updates are scheduled
  149.  * @param {number} [options.maxPoolSize=10] **Only applies to the unified topology** The maximum number of connections that may be associated with a pool at a given time. This includes in use and available connections.
  150.  * @param {number} [options.minPoolSize=0] **Only applies to the unified topology** The minimum number of connections that MUST exist at any moment in a single connection pool.
  151.  * @param {number} [options.maxIdleTimeMS] **Only applies to the unified topology** The maximum amount of time a connection should remain idle in the connection pool before being marked idle. The default is infinity.
  152.  * @param {number} [options.waitQueueTimeoutMS=0] **Only applies to the unified topology** The maximum amount of time operation execution should wait for a connection to become available. The default is 0 which means there is no limit.
  153.  * @param {AutoEncrypter~AutoEncryptionOptions} [options.autoEncryption] Optionally enable client side auto encryption
  154.  * @param {DriverInfoOptions} [options.driverInfo] Allows a wrapping driver to amend the client metadata generated by the driver to include information about the wrapping driver
  155.  * @param {MongoClient~connectCallback} [callback] The command result callback
  156.  * @return {MongoClient} a MongoClient instance
  157.  */
  158. function MongoClient(url, options) {
  159.   if (!(this instanceof MongoClient)) return new MongoClient(url, options);
  160.   // Set up event emitter
  161.   EventEmitter.call(this);
  163.   // The internal state
  164.   this.s = {
  165.     url: url,
  166.     options: options || {},
  167.     promiseLibrary: (options && options.promiseLibrary) || Promise,
  168.     dbCache: new Map(),
  169.     sessions: new Set(),
  170.     writeConcern: WriteConcern.fromOptions(options),
  171.     namespace: new MongoDBNamespace('admin')
  172.   };
  173. }
  175. /**
  176.  * @ignore
  177.  */
  178. inherits(MongoClient, EventEmitter);
  180. Object.defineProperty(MongoClient.prototype, 'writeConcern', {
  181.   enumerable: true,
  182.   get: function() {
  183.     return this.s.writeConcern;
  184.   }
  185. });
  187. Object.defineProperty(MongoClient.prototype, 'readPreference', {
  188.   enumerable: true,
  189.   get: function() {
  190.     return ReadPreference.primary;
  191.   }
  192. });
  194. /**
  195.  * The callback format for results
  196.  * @callback MongoClient~connectCallback
  197.  * @param {MongoError} error An error instance representing the error during the execution.
  198.  * @param {MongoClient} client The connected client.
  199.  */
  201. /**
  202.  * Connect to MongoDB using a url as documented at
  203.  *
  204.  *  docs.mongodb.org/manual/reference/connection-string/
  205.  *
  206.  * Note that for replicasets the replicaSet query parameter is required in the 2.0 driver
  207.  *
  208.  * @method
  209.  * @param {MongoClient~connectCallback} [callback] The command result callback
  210.  * @return {Promise<MongoClient>} returns Promise if no callback passed
  211.  */
  212. MongoClient.prototype.connect = function(callback) {
  213.   if (typeof callback === 'string') {
  214.     throw new TypeError('`connect` only accepts a callback');
  215.   }
  217.   const client = this;
  218.   return maybePromise(this, callback, cb => {
  219.     const err = validOptions(client.s.options);
  220.     if (err) return cb(err);
  222.     connect(client, client.s.url, client.s.options, err => {
  223.       if (err) return cb(err);
  224.       cb(null, client);
  225.     });
  226.   });
  227. };
  229. MongoClient.prototype.logout = deprecate(function(options, callback) {
  230.   if (typeof options === 'function') (callback = options), (options = {});
  231.   if (typeof callback === 'function') callback(null, true);
  232. }, 'Multiple authentication is prohibited on a connected client, please only authenticate once per MongoClient');
  234. /**
  235.  * Close the db and its underlying connections
  236.  * @method
  237.  * @param {boolean} [force=false] Force close, emitting no events
  238.  * @param {Db~noResultCallback} [callback] The result callback
  239.  * @return {Promise} returns Promise if no callback passed
  240.  */
  241. MongoClient.prototype.close = function(force, callback) {
  242.   if (typeof force === 'function') {
  243.     callback = force;
  244.     force = false;
  245.   }
  247.   const client = this;
  248.   return maybePromise(this, callback, cb => {
  249.     const completeClose = err => {
  250.       client.emit('close', client);
  252.       if (!(client.topology instanceof NativeTopology)) {
  253.         for (const item of client.s.dbCache) {
  254.           item[1].emit('close', client);
  255.         }
  256.       }
  258.       client.removeAllListeners('close');
  259.       cb(err);
  260.     };
  262.     if (client.topology == null) {
  263.       completeClose();
  264.       return;
  265.     }
  267.     client.topology.close(force, err => {
  268.       const autoEncrypter = client.topology.s.options.autoEncrypter;
  269.       if (!autoEncrypter) {
  270.         completeClose(err);
  271.         return;
  272.       }
  274.       autoEncrypter.teardown(force, err2 => completeClose(err || err2));
  275.     });
  276.   });
  277. };
  279. /**
  280.  * Create a new Db instance sharing the current socket connections. Be aware that the new db instances are
  281.  * related in a parent-child relationship to the original instance so that events are correctly emitted on child
  282.  * db instances. Child db instances are cached so performing db('db1') twice will return the same instance.
  283.  * You can control these behaviors with the options noListener and returnNonCachedInstance.
  284.  *
  285.  * @method
  286.  * @param {string} [dbName] The name of the database we want to use. If not provided, use database name from connection string.
  287.  * @param {object} [options] Optional settings.
  288.  * @param {boolean} [options.noListener=false] Do not make the db an event listener to the original connection.
  289.  * @param {boolean} [options.returnNonCachedInstance=false] Control if you want to return a cached instance or have a new one created
  290.  * @return {Db}
  291.  */
  292. MongoClient.prototype.db = function(dbName, options) {
  293.   options = options || {};
  295.   // Default to db from connection string if not provided
  296.   if (!dbName) {
  297.     dbName = this.s.options.dbName;
  298.   }
  300.   // Copy the options and add out internal override of the not shared flag
  301.   const finalOptions = Object.assign({}, this.s.options, options);
  303.   // Do we have the db in the cache already
  304.   if (this.s.dbCache.has(dbName) && finalOptions.returnNonCachedInstance !== true) {
  305.     return this.s.dbCache.get(dbName);
  306.   }
  308.   // Add promiseLibrary
  309.   finalOptions.promiseLibrary = this.s.promiseLibrary;
  311.   // If no topology throw an error message
  312.   if (!this.topology) {
  313.     throw new MongoError('MongoClient must be connected before calling MongoClient.prototype.db');
  314.   }
  316.   // Return the db object
  317.   const db = new Db(dbName, this.topology, finalOptions);
  319.   // Add the db to the cache
  320.   this.s.dbCache.set(dbName, db);
  321.   // Return the database
  322.   return db;
  323. };
  325. /**
  326.  * Check if MongoClient is connected
  327.  *
  328.  * @method
  329.  * @param {object} [options] Optional settings.
  330.  * @param {boolean} [options.noListener=false] Do not make the db an event listener to the original connection.
  331.  * @param {boolean} [options.returnNonCachedInstance=false] Control if you want to return a cached instance or have a new one created
  332.  * @return {boolean}
  333.  */
  334. MongoClient.prototype.isConnected = function(options) {
  335.   options = options || {};
  337.   if (!this.topology) return false;
  338.   return this.topology.isConnected(options);
  339. };
  341. /**
  342.  * Connect to MongoDB using a url as documented at
  343.  *
  344.  *  docs.mongodb.org/manual/reference/connection-string/
  345.  *
  346.  * Note that for replicasets the replicaSet query parameter is required in the 2.0 driver
  347.  *
  348.  * @method
  349.  * @static
  350.  * @param {string} url The connection URI string
  351.  * @param {object} [options] Optional settings
  352.  * @param {number} [options.poolSize=5] The maximum size of the individual server pool
  353.  * @param {boolean} [options.ssl=false] Enable SSL connection. *deprecated* use `tls` variants
  354.  * @param {boolean} [options.sslValidate=false] Validate mongod server certificate against Certificate Authority
  355.  * @param {buffer} [options.sslCA=undefined] SSL Certificate store binary buffer *deprecated* use `tls` variants
  356.  * @param {buffer} [options.sslCert=undefined] SSL Certificate binary buffer *deprecated* use `tls` variants
  357.  * @param {buffer} [options.sslKey=undefined] SSL Key file binary buffer *deprecated* use `tls` variants
  358.  * @param {string} [options.sslPass=undefined] SSL Certificate pass phrase *deprecated* use `tls` variants
  359.  * @param {buffer} [options.sslCRL=undefined] SSL Certificate revocation list binary buffer *deprecated* use `tls` variants
  360.  * @param {boolean|function} [options.checkServerIdentity=true] Ensure we check server identify during SSL, set to false to disable checking. Only works for Node 0.12.x or higher. You can pass in a boolean or your own checkServerIdentity override function. *deprecated* use `tls` variants
  361.  * @param {boolean} [options.tls=false] Enable TLS connections
  362.  * @param {boolean} [options.tlsInsecure=false] Relax TLS constraints, disabling validation
  363.  * @param {string} [options.tlsCAFile] A path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection
  364.  * @param {string} [options.tlsCertificateKeyFile] A path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated
  365.  * @param {string} [options.tlsCertificateKeyFilePassword] The password to decrypt the client private key to be used for TLS connections
  366.  * @param {boolean} [options.tlsAllowInvalidCertificates] Specifies whether or not the driver should error when the server’s TLS certificate is invalid
  367.  * @param {boolean} [options.tlsAllowInvalidHostnames] Specifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate
  368.  * @param {boolean} [options.autoReconnect=true] Enable autoReconnect for single server instances
  369.  * @param {boolean} [options.noDelay=true] TCP Connection no delay
  370.  * @param {boolean} [options.keepAlive=true] TCP Connection keep alive enabled
  371.  * @param {number} [options.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  372.  * @param {number} [options.connectTimeoutMS=10000] How long to wait for a connection to be established before timing out
  373.  * @param {number} [options.socketTimeoutMS=360000] How long a send or receive on a socket can take before timing out
  374.  * @param {number} [options.family] Version of IP stack. Can be 4, 6 or null (default).
  375.  * If null, will attempt to connect with IPv6, and will fall back to IPv4 on failure
  376.  * @param {number} [options.reconnectTries=30] Server attempt to reconnect #times
  377.  * @param {number} [options.reconnectInterval=1000] Server will wait # milliseconds between retries
  378.  * @param {boolean} [options.ha=true] Control if high availability monitoring runs for Replicaset or Mongos proxies
  379.  * @param {number} [options.haInterval=10000] The High availability period for replicaset inquiry
  380.  * @param {string} [options.replicaSet=undefined] The Replicaset set name
  381.  * @param {number} [options.secondaryAcceptableLatencyMS=15] Cutoff latency point in MS for Replicaset member selection
  382.  * @param {number} [options.acceptableLatencyMS=15] Cutoff latency point in MS for Mongos proxies selection
  383.  * @param {boolean} [options.connectWithNoPrimary=false] Sets if the driver should connect even if no primary is available
  384.  * @param {string} [options.authSource=undefined] Define the database to authenticate against
  385.  * @param {(number|string)} [options.w] The write concern
  386.  * @param {number} [options.wtimeout] The write concern timeout
  387.  * @param {boolean} [options.j=false] Specify a journal write concern
  388.  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver
  389.  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object
  390.  * @param {Boolean} [options.ignoreUndefined=false] Specify if the BSON serializer should ignore undefined fields
  391.  * @param {boolean} [options.raw=false] Return document results as raw BSON buffers
  392.  * @param {number} [options.bufferMaxEntries=-1] Sets a cap on how many operations the driver will buffer up before giving up on getting a working connection, default is -1 which is unlimited
  393.  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST)
  394.  * @param {object} [options.pkFactory] A primary key factory object for generation of custom _id keys
  395.  * @param {object} [options.promiseLibrary] A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
  396.  * @param {object} [options.readConcern] Specify a read concern for the collection (only MongoDB 3.2 or higher supported)
  397.  * @param {ReadConcernLevel} [options.readConcern.level='local'] Specify a read concern level for the collection operations (only MongoDB 3.2 or higher supported)
  398.  * @param {number} [options.maxStalenessSeconds=undefined] The max staleness to secondary reads (values under 10 seconds cannot be guaranteed)
  399.  * @param {string} [options.loggerLevel=undefined] The logging level (error/warn/info/debug)
  400.  * @param {object} [options.logger=undefined] Custom logger object
  401.  * @param {boolean} [options.promoteValues=true] Promotes BSON values to native types where possible, set to false to only receive wrapper types
  402.  * @param {boolean} [options.promoteBuffers=false] Promotes Binary BSON values to native Node Buffers
  403.  * @param {boolean} [options.promoteLongs=true] Promotes long values to number if they fit inside the 53 bits resolution
  404.  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit
  405.  * @param {object} [options.validateOptions=false] Validate MongoClient passed in options for correctness
  406.  * @param {string} [options.appname=undefined] The name of the application that created this MongoClient instance. MongoDB 3.4 and newer will print this value in the server log upon establishing each connection. It is also recorded in the slow query log and profile collections
  407.  * @param {string} [options.auth.user=undefined] The username for auth
  408.  * @param {string} [options.auth.password=undefined] The password for auth
  409.  * @param {string} [options.authMechanism=undefined] Mechanism for authentication: MDEFAULT, GSSAPI, PLAIN, MONGODB-X509, or SCRAM-SHA-1
  410.  * @param {object} [options.compression] Type of compression to use: snappy or zlib
  411.  * @param {boolean} [options.fsync=false] Specify a file sync write concern
  412.  * @param {array} [options.readPreferenceTags] Read preference tags
  413.  * @param {number} [options.numberOfRetries=5] The number of retries for a tailable cursor
  414.  * @param {boolean} [options.auto_reconnect=true] Enable auto reconnecting for single server instances
  415.  * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this client
  416.  * @param {number} [options.minSize] If present, the connection pool will be initialized with minSize connections, and will never dip below minSize connections
  417.  * @param {boolean} [options.useNewUrlParser=true] Determines whether or not to use the new url parser. Enables the new, spec-compliant, url parser shipped in the core driver. This url parser fixes a number of problems with the original parser, and aims to outright replace that parser in the near future. Defaults to true, and must be explicitly set to false to use the legacy url parser.
  418.  * @param {boolean} [options.useUnifiedTopology] Enables the new unified topology layer
  419.  * @param {Number} [options.localThresholdMS=15] **Only applies to the unified topology** The size of the latency window for selecting among multiple suitable servers
  420.  * @param {Number} [options.serverSelectionTimeoutMS=30000] **Only applies to the unified topology** How long to block for server selection before throwing an error
  421.  * @param {Number} [options.heartbeatFrequencyMS=10000] **Only applies to the unified topology** The frequency with which topology updates are scheduled
  422.  * @param {number} [options.maxPoolSize=10] **Only applies to the unified topology** The maximum number of connections that may be associated with a pool at a given time. This includes in use and available connections.
  423.  * @param {number} [options.minPoolSize=0] **Only applies to the unified topology** The minimum number of connections that MUST exist at any moment in a single connection pool.
  424.  * @param {number} [options.maxIdleTimeMS] **Only applies to the unified topology** The maximum amount of time a connection should remain idle in the connection pool before being marked idle. The default is infinity.
  425.  * @param {number} [options.waitQueueTimeoutMS=0] **Only applies to the unified topology** The maximum amount of time operation execution should wait for a connection to become available. The default is 0 which means there is no limit.
  426.  * @param {AutoEncrypter~AutoEncryptionOptions} [options.autoEncryption] Optionally enable client side auto encryption
  427.  * @param {DriverInfoOptions} [options.driverInfo] Allows a wrapping driver to amend the client metadata generated by the driver to include information about the wrapping driver
  428.  * @param {MongoClient~connectCallback} [callback] The command result callback
  429.  * @return {Promise<MongoClient>} returns Promise if no callback passed
  430.  */
  431. MongoClient.connect = function(url, options, callback) {
  432.   const args = Array.prototype.slice.call(arguments, 1);
  433.   callback = typeof args[args.length - 1] === 'function' ? args.pop() : undefined;
  434.   options = args.length ? args.shift() : null;
  435.   options = options || {};
  437.   // Create client
  438.   const mongoClient = new MongoClient(url, options);
  439.   // Execute the connect method
  440.   return mongoClient.connect(callback);
  441. };
  443. /**
  444.  * Starts a new session on the server
  445.  *
  446.  * @param {SessionOptions} [options] optional settings for a driver session
  447.  * @return {ClientSession} the newly established session
  448.  */
  449. MongoClient.prototype.startSession = function(options) {
  450.   options = Object.assign({ explicit: true }, options);
  451.   if (!this.topology) {
  452.     throw new MongoError('Must connect to a server before calling this method');
  453.   }
  455.   if (!this.topology.hasSessionSupport()) {
  456.     throw new MongoError('Current topology does not support sessions');
  457.   }
  459.   return this.topology.startSession(options, this.s.options);
  460. };
  462. /**
  463.  * Runs a given operation with an implicitly created session. The lifetime of the session
  464.  * will be handled without the need for user interaction.
  465.  *
  466.  * NOTE: presently the operation MUST return a Promise (either explicit or implicity as an async function)
  467.  *
  468.  * @param {Object} [options] Optional settings to be appled to implicitly created session
  469.  * @param {Function} operation An operation to execute with an implicitly created session. The signature of this MUST be `(session) => {}`
  470.  * @return {Promise}
  471.  */
  472. MongoClient.prototype.withSession = function(options, operation) {
  473.   if (typeof options === 'function') (operation = options), (options = undefined);
  474.   const session = this.startSession(options);
  476.   let cleanupHandler = (err, result, opts) => {
  477.     // prevent multiple calls to cleanupHandler
  478.     cleanupHandler = () => {
  479.       throw new ReferenceError('cleanupHandler was called too many times');
  480.     };
  482.     opts = Object.assign({ throw: true }, opts);
  483.     session.endSession();
  485.     if (err) {
  486.       if (opts.throw) throw err;
  487.       return Promise.reject(err);
  488.     }
  489.   };
  491.   try {
  492.     const result = operation(session);
  493.     return Promise.resolve(result)
  494.       .then(result => cleanupHandler(null, result))
  495.       .catch(err => cleanupHandler(err, null, { throw: true }));
  496.   } catch (err) {
  497.     return cleanupHandler(err, null, { throw: false });
  498.   }
  499. };
  500. /**
  501.  * Create a new Change Stream, watching for new changes (insertions, updates, replacements, deletions, and invalidations) in this cluster. Will ignore all changes to system collections, as well as the local, admin,
  502.  * and config databases.
  503.  * @method
  504.  * @since 3.1.0
  505.  * @param {Array} [pipeline] An array of {@link https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/|aggregation pipeline stages} through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
  506.  * @param {object} [options] Optional settings
  507.  * @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.
  508.  * @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.
  509.  * @param {number} [options.maxAwaitTimeMS] The maximum amount of time for the server to wait on new documents to satisfy a change stream query
  510.  * @param {number} [options.batchSize=1000] The number of documents to return per batch. See {@link https://www.mongodb.com/docs/manual/reference/command/aggregate|aggregation documentation}.
  511.  * @param {object} [options.collation] Specify collation settings for operation. See {@link https://www.mongodb.com/docs/manual/reference/command/aggregate|aggregation documentation}.
  512.  * @param {ReadPreference} [options.readPreference] The read preference. See {@link https://www.mongodb.com/docs/manual/reference/read-preference|read preference documentation}.
  513.  * @param {Timestamp} [options.startAtOperationTime] receive change events that occur after the specified timestamp
  514.  * @param {ClientSession} [options.session] optional session to use for this operation
  515.  * @return {ChangeStream} a ChangeStream instance.
  516.  */
  517. MongoClient.prototype.watch = function(pipeline, options) {
  518.   pipeline = pipeline || [];
  519.   options = options || {};
  521.   // Allow optionally not specifying a pipeline
  522.   if (!Array.isArray(pipeline)) {
  523.     options = pipeline;
  524.     pipeline = [];
  525.   }
  527.   return new ChangeStream(this, pipeline, options);
  528. };
  530. /**
  531.  * Return the mongo client logger
  532.  * @method
  533.  * @return {Logger} return the mongo client logger
  534.  * @ignore
  535.  */
  536. MongoClient.prototype.getLogger = function() {
  537.   return this.s.options.logger;
  538. };
  540. module.exports = MongoClient;