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 executeOperation = require('./operations/execute_operation');
  7. const inherits = require('util').inherits;
  8. const MongoError = require('./core').MongoError;
  9. const deprecate = require('util').deprecate;
  10. const WriteConcern = require('./write_concern');
  11. const MongoDBNamespace = require('./utils').MongoDBNamespace;
  12. const ReadPreference = require('./core/topologies/read_preference');
  14. // Operations
  15. const ConnectOperation = require('./operations/connect');
  16. const CloseOperation = require('./operations/close');
  18. /**
  19.  * @fileOverview The **MongoClient** class is a class that allows for making Connections to MongoDB.
  20.  *
  21.  * @example
  22.  * // Connect using a MongoClient instance
  23.  * const MongoClient = require('mongodb').MongoClient;
  24.  * const test = require('assert');
  25.  * // Connection url
  26.  * const url = 'mongodb://localhost:27017';
  27.  * // Database Name
  28.  * const dbName = 'test';
  29.  * // Connect using MongoClient
  30.  * const mongoClient = new MongoClient(url);
  31.  * mongoClient.connect(function(err, client) {
  32.  *   const db = client.db(dbName);
  33.  *   client.close();
  34.  * });
  35.  *
  36.  * @example
  37.  * // Connect using the MongoClient.connect static method
  38.  * const MongoClient = require('mongodb').MongoClient;
  39.  * const test = require('assert');
  40.  * // Connection url
  41.  * const url = 'mongodb://localhost:27017';
  42.  * // Database Name
  43.  * const dbName = 'test';
  44.  * // Connect using MongoClient
  45.  * MongoClient.connect(url, function(err, client) {
  46.  *   const db = client.db(dbName);
  47.  *   client.close();
  48.  * });
  49.  */
  51. /**
  52.  * A string specifying the level of a ReadConcern
  53.  * @typedef {'local'|'available'|'majority'|'linearizable'|'snapshot'} ReadConcernLevel
  54.  * @see https://www.mongodb.com/docs/manual/reference/read-concern/index.html#read-concern-levels
  55.  */
  57. /**
  58.  * Configuration options for drivers wrapping the node driver.
  59.  *
  60.  * @typedef {Object} DriverInfoOptions
  61.  * @property {string} [name] The name of the driver
  62.  * @property {string} [version] The version of the driver
  63.  * @property {string} [platform] Optional platform information
  64.  */
  66. /**
  67.  * Configuration options for drivers wrapping the node driver.
  68.  *
  69.  * @typedef {Object} DriverInfoOptions
  70.  * @property {string} [name] The name of the driver
  71.  * @property {string} [version] The version of the driver
  72.  * @property {string} [platform] Optional platform information
  73.  */
  75. /**
  76.  * Creates a new MongoClient instance
  77.  * @class
  78.  * @param {string} url The connection URI string
  79.  * @param {object} [options] Optional settings
  80.  * @param {number} [options.poolSize=5] The maximum size of the individual server pool
  81.  * @param {boolean} [options.ssl=false] Enable SSL connection. *deprecated* use `tls` variants
  82.  * @param {boolean} [options.sslValidate=false] Validate mongod server certificate against Certificate Authority
  83.  * @param {buffer} [options.sslCA=undefined] SSL Certificate store binary buffer *deprecated* use `tls` variants
  84.  * @param {buffer} [options.sslCert=undefined] SSL Certificate binary buffer *deprecated* use `tls` variants
  85.  * @param {buffer} [options.sslKey=undefined] SSL Key file binary buffer *deprecated* use `tls` variants
  86.  * @param {string} [options.sslPass=undefined] SSL Certificate pass phrase *deprecated* use `tls` variants
  87.  * @param {buffer} [options.sslCRL=undefined] SSL Certificate revocation list binary buffer *deprecated* use `tls` variants
  88.  * @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
  89.  * @param {boolean} [options.tls=false] Enable TLS connections
  90.  * @param {boolean} [options.tlsinsecure=false] Relax TLS constraints, disabling validation
  91.  * @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
  92.  * @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
  93.  * @param {string} [options.tlsCertificateKeyFilePassword] The password to decrypt the client private key to be used for TLS connections
  94.  * @param {boolean} [options.tlsAllowInvalidCertificates] Specifies whether or not the driver should error when the server’s TLS certificate is invalid
  95.  * @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
  96.  * @param {boolean} [options.autoReconnect=true] Enable autoReconnect for single server instances
  97.  * @param {boolean} [options.noDelay=true] TCP Connection no delay
  98.  * @param {boolean} [options.keepAlive=true] TCP Connection keep alive enabled
  99.  * @param {number} [options.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  100.  * @param {number} [options.connectTimeoutMS=30000] TCP Connection timeout setting
  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.socketTimeoutMS=360000] TCP Socket timeout setting
  104.  * @param {number} [options.reconnectTries=30] Server attempt to reconnect #times
  105.  * @param {number} [options.reconnectInterval=1000] Server will wait # milliseconds between retries
  106.  * @param {boolean} [options.ha=true] Control if high availability monitoring runs for Replicaset or Mongos proxies
  107.  * @param {number} [options.haInterval=10000] The High availability period for replicaset inquiry
  108.  * @param {string} [options.replicaSet=undefined] The Replicaset set name
  109.  * @param {number} [options.secondaryAcceptableLatencyMS=15] Cutoff latency point in MS for Replicaset member selection
  110.  * @param {number} [options.acceptableLatencyMS=15] Cutoff latency point in MS for Mongos proxies selection
  111.  * @param {boolean} [options.connectWithNoPrimary=false] Sets if the driver should connect even if no primary is available
  112.  * @param {string} [options.authSource=undefined] Define the database to authenticate against
  113.  * @param {(number|string)} [options.w] The write concern
  114.  * @param {number} [options.wtimeout] The write concern timeout
  115.  * @param {boolean} [options.j=false] Specify a journal write concern
  116.  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver
  117.  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object
  118.  * @param {Boolean} [options.ignoreUndefined=false] Specify if the BSON serializer should ignore undefined fields
  119.  * @param {boolean} [options.raw=false] Return document results as raw BSON buffers
  120.  * @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
  121.  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST)
  122.  * @param {object} [options.pkFactory] A primary key factory object for generation of custom _id keys
  123.  * @param {object} [options.promiseLibrary] A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
  124.  * @param {object} [options.readConcern] Specify a read concern for the collection (only MongoDB 3.2 or higher supported)
  125.  * @param {ReadConcernLevel} [options.readConcern.level='local'] Specify a read concern level for the collection operations (only MongoDB 3.2 or higher supported)
  126.  * @param {number} [options.maxStalenessSeconds=undefined] The max staleness to secondary reads (values under 10 seconds cannot be guaranteed)
  127.  * @param {string} [options.loggerLevel=undefined] The logging level (error/warn/info/debug)
  128.  * @param {object} [options.logger=undefined] Custom logger object
  129.  * @param {boolean} [options.promoteValues=true] Promotes BSON values to native types where possible, set to false to only receive wrapper types
  130.  * @param {boolean} [options.promoteBuffers=false] Promotes Binary BSON values to native Node Buffers
  131.  * @param {boolean} [options.promoteLongs=true] Promotes long values to number if they fit inside the 53 bits resolution
  132.  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit
  133.  * @param {object} [options.validateOptions=false] Validate MongoClient passed in options for correctness
  134.  * @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
  135.  * @param {string} [options.auth.user=undefined] The username for auth
  136.  * @param {string} [options.auth.password=undefined] The password for auth
  137.  * @param {string} [options.authMechanism=undefined] Mechanism for authentication: MDEFAULT, GSSAPI, PLAIN, MONGODB-X509, or SCRAM-SHA-1
  138.  * @param {object} [options.compression] Type of compression to use: snappy or zlib
  139.  * @param {boolean} [options.fsync=false] Specify a file sync write concern
  140.  * @param {array} [options.readPreferenceTags] Read preference tags
  141.  * @param {number} [options.numberOfRetries=5] The number of retries for a tailable cursor
  142.  * @param {boolean} [options.auto_reconnect=true] Enable auto reconnecting for single server instances
  143.  * @param {boolean} [options.monitorCommands=false] Enable command monitoring for this client
  144.  * @param {number} [options.minSize] If present, the connection pool will be initialized with minSize connections, and will never dip below minSize connections
  145.  * @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.
  146.  * @param {boolean} [options.useUnifiedTopology] Enables the new unified topology layer
  147.  * @param {AutoEncrypter~AutoEncryptionOptions} [options.autoEncryption] Optionally enable client side auto encryption
  148.  * @param {DriverInfoOptions} [options.driverInfo] Allows a wrapping driver to amend the client metadata generated by the driver to include information about the wrapping driver
  149.  * @param {MongoClient~connectCallback} [callback] The command result callback
  150.  * @return {MongoClient} a MongoClient instance
  151.  */
  152. function MongoClient(url, options) {
  153.   if (!(this instanceof MongoClient)) return new MongoClient(url, options);
  154.   // Set up event emitter
  155.   EventEmitter.call(this);
  157.   // The internal state
  158.   this.s = {
  159.     url: url,
  160.     options: options || {},
  161.     promiseLibrary: null,
  162.     dbCache: new Map(),
  163.     sessions: new Set(),
  164.     writeConcern: WriteConcern.fromOptions(options),
  165.     namespace: new MongoDBNamespace('admin')
  166.   };
  168.   // Get the promiseLibrary
  169.   const promiseLibrary = this.s.options.promiseLibrary || Promise;
  171.   // Add the promise to the internal state
  172.   this.s.promiseLibrary = promiseLibrary;
  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 operation = new ConnectOperation(this);
  219.   return executeOperation(this, operation, callback);
  220. };
  222. MongoClient.prototype.logout = deprecate(function(options, callback) {
  223.   if (typeof options === 'function') (callback = options), (options = {});
  224.   if (typeof callback === 'function') callback(null, true);
  225. }, 'Multiple authentication is prohibited on a connected client, please only authenticate once per MongoClient');
  227. /**
  228.  * Close the db and its underlying connections
  229.  * @method
  230.  * @param {boolean} [force=false] Force close, emitting no events
  231.  * @param {Db~noResultCallback} [callback] The result callback
  232.  * @return {Promise} returns Promise if no callback passed
  233.  */
  234. MongoClient.prototype.close = function(force, callback) {
  235.   if (typeof force === 'function') (callback = force), (force = false);
  236.   const operation = new CloseOperation(this, force);
  237.   return executeOperation(this, operation, callback);
  238. };
  240. /**
  241.  * Create a new Db instance sharing the current socket connections. Be aware that the new db instances are
  242.  * related in a parent-child relationship to the original instance so that events are correctly emitted on child
  243.  * db instances. Child db instances are cached so performing db('db1') twice will return the same instance.
  244.  * You can control these behaviors with the options noListener and returnNonCachedInstance.
  245.  *
  246.  * @method
  247.  * @param {string} [dbName] The name of the database we want to use. If not provided, use database name from connection string.
  248.  * @param {object} [options] Optional settings.
  249.  * @param {boolean} [options.noListener=false] Do not make the db an event listener to the original connection.
  250.  * @param {boolean} [options.returnNonCachedInstance=false] Control if you want to return a cached instance or have a new one created
  251.  * @return {Db}
  252.  */
  253. MongoClient.prototype.db = function(dbName, options) {
  254.   options = options || {};
  256.   // Default to db from connection string if not provided
  257.   if (!dbName) {
  258.     dbName = this.s.options.dbName;
  259.   }
  261.   // Copy the options and add out internal override of the not shared flag
  262.   const finalOptions = Object.assign({}, this.s.options, options);
  264.   // Do we have the db in the cache already
  265.   if (this.s.dbCache.has(dbName) && finalOptions.returnNonCachedInstance !== true) {
  266.     return this.s.dbCache.get(dbName);
  267.   }
  269.   // Add promiseLibrary
  270.   finalOptions.promiseLibrary = this.s.promiseLibrary;
  272.   // If no topology throw an error message
  273.   if (!this.topology) {
  274.     throw new MongoError('MongoClient must be connected before calling MongoClient.prototype.db');
  275.   }
  277.   // Return the db object
  278.   const db = new Db(dbName, this.topology, finalOptions);
  280.   // Add the db to the cache
  281.   this.s.dbCache.set(dbName, db);
  282.   // Return the database
  283.   return db;
  284. };
  286. /**
  287.  * Check if MongoClient is connected
  288.  *
  289.  * @method
  290.  * @param {object} [options] Optional settings.
  291.  * @param {boolean} [options.noListener=false] Do not make the db an event listener to the original connection.
  292.  * @param {boolean} [options.returnNonCachedInstance=false] Control if you want to return a cached instance or have a new one created
  293.  * @return {boolean}
  294.  */
  295. MongoClient.prototype.isConnected = function(options) {
  296.   options = options || {};
  298.   if (!this.topology) return false;
  299.   return this.topology.isConnected(options);
  300. };
  302. /**
  303.  * Connect to MongoDB using a url as documented at
  304.  *
  305.  *  docs.mongodb.org/manual/reference/connection-string/
  306.  *
  307.  * Note that for replicasets the replicaSet query parameter is required in the 2.0 driver
  308.  *
  309.  * @method
  310.  * @static
  311.  * @param {string} url The connection URI string
  312.  * @param {object} [options] Optional settings
  313.  * @param {number} [options.poolSize=5] The maximum size of the individual server pool
  314.  * @param {boolean} [options.ssl=false] Enable SSL connection. *deprecated* use `tls` variants
  315.  * @param {boolean} [options.sslValidate=false] Validate mongod server certificate against Certificate Authority *deprecated* use `tls` variants
  316.  * @param {buffer} [options.sslCA=undefined] SSL Certificate store binary buffer *deprecated* use `tls` variants
  317.  * @param {buffer} [options.sslCert=undefined] SSL Certificate binary buffer *deprecated* use `tls` variants
  318.  * @param {buffer} [options.sslKey=undefined] SSL Key file binary buffer *deprecated* use `tls` variants
  319.  * @param {string} [options.sslPass=undefined] SSL Certificate pass phrase *deprecated* use `tls` variants
  320.  * @param {buffer} [options.sslCRL=undefined] SSL Certificate revocation list binary buffer *deprecated* use `tls` variants
  321.  * @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
  322.  * @param {boolean} [options.tls=false] Enable TLS connections
  323.  * @param {boolean} [options.tlsinsecure=false] Relax TLS constraints, disabling validation
  324.  * @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
  325.  * @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
  326.  * @param {string} [options.tlsCertificateKeyFilePassword] The password to decrypt the client private key to be used for TLS connections
  327.  * @param {boolean} [options.tlsAllowInvalidCertificates] Specifies whether or not the driver should error when the server’s TLS certificate is invalid
  328.  * @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
  329.  * @param {boolean} [options.autoReconnect=true] Enable autoReconnect for single server instances
  330.  * @param {boolean} [options.noDelay=true] TCP Connection no delay
  331.  * @param {boolean} [options.keepAlive=true] TCP Connection keep alive enabled
  332.  * @param {boolean} [options.keepAliveInitialDelay=30000] The number of milliseconds to wait before initiating keepAlive on the TCP socket
  333.  * @param {number} [options.connectTimeoutMS=30000] TCP Connection timeout setting
  334.  * @param {number} [options.family] Version of IP stack. Can be 4, 6 or null (default).
  335.  * If null, will attempt to connect with IPv6, and will fall back to IPv4 on failure
  336.  * @param {number} [options.socketTimeoutMS=360000] TCP Socket timeout setting
  337.  * @param {number} [options.reconnectTries=30] Server attempt to reconnect #times
  338.  * @param {number} [options.reconnectInterval=1000] Server will wait # milliseconds between retries
  339.  * @param {boolean} [options.ha=true] Control if high availability monitoring runs for Replicaset or Mongos proxies
  340.  * @param {number} [options.haInterval=10000] The High availability period for replicaset inquiry
  341.  * @param {string} [options.replicaSet=undefined] The Replicaset set name
  342.  * @param {number} [options.secondaryAcceptableLatencyMS=15] Cutoff latency point in MS for Replicaset member selection
  343.  * @param {number} [options.acceptableLatencyMS=15] Cutoff latency point in MS for Mongos proxies selection
  344.  * @param {boolean} [options.connectWithNoPrimary=false] Sets if the driver should connect even if no primary is available
  345.  * @param {string} [options.authSource=undefined] Define the database to authenticate against
  346.  * @param {(number|string)} [options.w] The write concern
  347.  * @param {number} [options.wtimeout] The write concern timeout
  348.  * @param {boolean} [options.j=false] Specify a journal write concern
  349.  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver
  350.  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object
  351.  * @param {Boolean} [options.ignoreUndefined=false] Specify if the BSON serializer should ignore undefined fields
  352.  * @param {boolean} [options.raw=false] Return document results as raw BSON buffers
  353.  * @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
  354.  * @param {(ReadPreference|string)} [options.readPreference] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST)
  355.  * @param {object} [options.pkFactory] A primary key factory object for generation of custom _id keys
  356.  * @param {object} [options.promiseLibrary] A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
  357.  * @param {object} [options.readConcern] Specify a read concern for the collection (only MongoDB 3.2 or higher supported)
  358.  * @param {ReadConcernLevel} [options.readConcern.level='local'] Specify a read concern level for the collection operations (only MongoDB 3.2 or higher supported)
  359.  * @param {number} [options.maxStalenessSeconds=undefined] The max staleness to secondary reads (values under 10 seconds cannot be guaranteed)
  360.  * @param {string} [options.loggerLevel=undefined] The logging level (error/warn/info/debug)
  361.  * @param {object} [options.logger=undefined] Custom logger object
  362.  * @param {boolean} [options.promoteValues=true] Promotes BSON values to native types where possible, set to false to only receive wrapper types
  363.  * @param {boolean} [options.promoteBuffers=false] Promotes Binary BSON values to native Node Buffers
  364.  * @param {boolean} [options.promoteLongs=true] Promotes long values to number if they fit inside the 53 bits resolution
  365.  * @param {boolean} [options.domainsEnabled=false] Enable the wrapping of the callback in the current domain, disabled by default to avoid perf hit
  366.  * @param {object} [options.validateOptions=false] Validate MongoClient passed in options for correctness
  367.  * @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
  368.  * @param {string} [options.auth.user=undefined] The username for auth
  369.  * @param {string} [options.auth.password=undefined] The password for auth
  370.  * @param {string} [options.authMechanism=undefined] Mechanism for authentication: MDEFAULT, GSSAPI, PLAIN, MONGODB-X509, or SCRAM-SHA-1
  371.  * @param {object} [options.compression] Type of compression to use: snappy or zlib
  372.  * @param {boolean} [options.fsync=false] Specify a file sync write concern
  373.  * @param {array} [options.readPreferenceTags] Read preference tags
  374.  * @param {number} [options.numberOfRetries=5] The number of retries for a tailable cursor
  375.  * @param {boolean} [options.auto_reconnect=true] Enable auto reconnecting for single server instances
  376.  * @param {number} [options.minSize] If present, the connection pool will be initialized with minSize connections, and will never dip below minSize connections
  377.  * @param {MongoClient~connectCallback} [callback] The command result callback
  378.  * @return {Promise<MongoClient>} returns Promise if no callback passed
  379.  */
  380. MongoClient.connect = function(url, options, callback) {
  381.   const args = Array.prototype.slice.call(arguments, 1);
  382.   callback = typeof args[args.length - 1] === 'function' ? args.pop() : undefined;
  383.   options = args.length ? args.shift() : null;
  384.   options = options || {};
  386.   // Create client
  387.   const mongoClient = new MongoClient(url, options);
  388.   // Execute the connect method
  389.   return mongoClient.connect(callback);
  390. };
  392. /**
  393.  * Starts a new session on the server
  394.  *
  395.  * @param {SessionOptions} [options] optional settings for a driver session
  396.  * @return {ClientSession} the newly established session
  397.  */
  398. MongoClient.prototype.startSession = function(options) {
  399.   options = Object.assign({ explicit: true }, options);
  400.   if (!this.topology) {
  401.     throw new MongoError('Must connect to a server before calling this method');
  402.   }
  404.   if (!this.topology.hasSessionSupport()) {
  405.     throw new MongoError('Current topology does not support sessions');
  406.   }
  408.   return this.topology.startSession(options, this.s.options);
  409. };
  411. /**
  412.  * Runs a given operation with an implicitly created session. The lifetime of the session
  413.  * will be handled without the need for user interaction.
  414.  *
  415.  * NOTE: presently the operation MUST return a Promise (either explicit or implicity as an async function)
  416.  *
  417.  * @param {Object} [options] Optional settings to be appled to implicitly created session
  418.  * @param {Function} operation An operation to execute with an implicitly created session. The signature of this MUST be `(session) => {}`
  419.  * @return {Promise}
  420.  */
  421. MongoClient.prototype.withSession = function(options, operation) {
  422.   if (typeof options === 'function') (operation = options), (options = undefined);
  423.   const session = this.startSession(options);
  425.   let cleanupHandler = (err, result, opts) => {
  426.     // prevent multiple calls to cleanupHandler
  427.     cleanupHandler = () => {
  428.       throw new ReferenceError('cleanupHandler was called too many times');
  429.     };
  431.     opts = Object.assign({ throw: true }, opts);
  432.     session.endSession();
  434.     if (err) {
  435.       if (opts.throw) throw err;
  436.       return Promise.reject(err);
  437.     }
  438.   };
  440.   try {
  441.     const result = operation(session);
  442.     return Promise.resolve(result)
  443.       .then(result => cleanupHandler(null, result))
  444.       .catch(err => cleanupHandler(err, null, { throw: true }));
  445.   } catch (err) {
  446.     return cleanupHandler(err, null, { throw: false });
  447.   }
  448. };
  449. /**
  450.  * 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,
  451.  * and config databases.
  452.  * @method
  453.  * @since 3.1.0
  454.  * @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.
  455.  * @param {object} [options] Optional settings
  456.  * @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.
  457.  * @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.
  458.  * @param {number} [options.maxAwaitTimeMS] The maximum amount of time for the server to wait on new documents to satisfy a change stream query
  459.  * @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}.
  460.  * @param {object} [options.collation] Specify collation settings for operation. See {@link https://www.mongodb.com/docs/manual/reference/command/aggregate|aggregation documentation}.
  461.  * @param {ReadPreference} [options.readPreference] The read preference. See {@link https://www.mongodb.com/docs/manual/reference/read-preference|read preference documentation}.
  462.  * @param {Timestamp} [options.startAtOperationTime] receive change events that occur after the specified timestamp
  463.  * @param {ClientSession} [options.session] optional session to use for this operation
  464.  * @return {ChangeStream} a ChangeStream instance.
  465.  */
  466. MongoClient.prototype.watch = function(pipeline, options) {
  467.   pipeline = pipeline || [];
  468.   options = options || {};
  470.   // Allow optionally not specifying a pipeline
  471.   if (!Array.isArray(pipeline)) {
  472.     options = pipeline;
  473.     pipeline = [];
  474.   }
  476.   return new ChangeStream(this, pipeline, options);
  477. };
  479. /**
  480.  * Return the mongo client logger
  481.  * @method
  482.  * @return {Logger} return the mongo client logger
  483.  * @ignore
  484.  */
  485. MongoClient.prototype.getLogger = function() {
  486.   return this.s.options.logger;
  487. };
  489. module.exports = MongoClient;