mongoose 9.2.4 → 9.3.0

package/lib/aggregate.js

@@ -46,7 +46,7 @@ const validRedactStringValues = new Set(['$$DESCEND', '$$PRUNE', '$$KEEP']);
  *     new Aggregate([{ $match: { _id: new mongoose.Types.ObjectId('00000000000000000000000a') } }]);
  *
  * @see MongoDB https://www.mongodb.com/docs/manual/applications/aggregation/
- * @see driver https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#aggregate
+ * @see driver https://mongodb.github.io/node-mongodb-native/7.0/classes/Collection.html#aggregate
  * @param {Array} [pipeline] aggregation pipeline as an array of objects
  * @param {Model|Connection} [modelOrConn] the model or connection to use with this aggregate.
  * @api public
@@ -933,7 +933,7 @@ Aggregate.prototype.option = function(value) {
  * @param {boolean} [options.useMongooseAggCursor] use experimental mongoose-specific aggregation cursor (for `eachAsync()` and other query cursor semantics)
  * @return {AggregationCursor} cursor representing this aggregation
  * @api public
- * @see mongodb https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html
+ * @see mongodb https://mongodb.github.io/node-mongodb-native/7.0/classes/AggregationCursor.html
  */
 
 Aggregate.prototype.cursor = function(options) {
@@ -952,7 +952,7 @@ Aggregate.prototype.cursor = function(options) {
  * @param {object} collation options
  * @return {Aggregate} this
  * @api public
- * @see mongodb https://mongodb.github.io/node-mongodb-native/4.9/interfaces/CollationOptions.html
+ * @see mongodb https://mongodb.github.io/node-mongodb-native/7.0/interfaces/CollationOptions.html
  */
 
 Aggregate.prototype.collation = function(collation) {
@@ -1015,7 +1015,7 @@ Aggregate.prototype.search = function(options) {
  *
  *     MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }]
  *
- * @return {Array} The current pipeline similar to the operation that will be executed
+ * @return {PipelineStage[]} The current pipeline similar to the operation that will be executed
  * @api public
  */
 
@@ -1023,6 +1023,29 @@ Aggregate.prototype.pipeline = function() {
   return this._pipeline;
 };
 
+/**
+ * Returns the current pipeline as a `$unionWith`-safe pipeline.
+ * Throws if this pipeline contains `$out` or `$merge`.
+ *
+ * #### Example:
+ *
+ *     const base = MyModel.aggregate().match({ test: 1 });
+ *     base.pipelineForUnionWith(); // [{ $match: { test: 1 } }]
+ *
+ * @return {Array} The current pipeline with `$unionWith` stage restrictions
+ * @api public
+ */
+
+Aggregate.prototype.pipelineForUnionWith = function pipelineForUnionWith() {
+  for (const stage of this._pipeline) {
+    if (stage?.$out != null || stage?.$merge != null) {
+      throw new MongooseError('Aggregate pipeline for $unionWith cannot include `$out` or `$merge` stages');
+    }
+  }
+
+  return this._pipeline;
+};
+
 /**
  * Executes the aggregate pipeline on the currently bound Model.
  *

package/lib/connection.js

@@ -410,11 +410,11 @@ Connection.prototype.config;
  * with specified options. Used to create [capped collections](https://www.mongodb.com/docs/manual/core/capped-collections/)
  * and [views](https://www.mongodb.com/docs/manual/core/views/) from mongoose.
  *
- * Options are passed down without modification to the [MongoDB driver's `createCollection()` function](https://mongodb.github.io/node-mongodb-native/4.9/classes/Db.html#createCollection)
+ * Options are passed down without modification to the [MongoDB driver's `createCollection()` function](https://mongodb.github.io/node-mongodb-native/7.0/classes/Db.html#createCollection)
  *
  * @method createCollection
  * @param {string} collection The collection to create
- * @param {object} [options] see [MongoDB driver docs](https://mongodb.github.io/node-mongodb-native/4.9/classes/Db.html#createCollection)
+ * @param {object} [options] see [MongoDB driver docs](https://mongodb.github.io/node-mongodb-native/7.0/classes/Db.html#createCollection)
  * @return {Promise}
  * @api public
  */
@@ -678,7 +678,7 @@ Connection.prototype.withSession = async function withSession(executor) {
  *
  *
  * @method startSession
- * @param {object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/4.9/classes/MongoClient.html#startSession)
+ * @param {object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/7.0/classes/MongoClient.html#startSession)
  * @param {boolean} [options.causalConsistency=true] set to false to disable causal consistency
  * @return {Promise<ClientSession>} promise that resolves to a MongoDB driver `ClientSession`
  * @api public
@@ -701,7 +701,7 @@ Connection.prototype.startSession = async function startSession(options) {
  * async function executes successfully and attempt to retry if
  * there was a retriable error.
  *
- * Calls the MongoDB driver's [`session.withTransaction()`](https://mongodb.github.io/node-mongodb-native/4.9/classes/ClientSession.html#withTransaction),
+ * Calls the MongoDB driver's [`session.withTransaction()`](https://mongodb.github.io/node-mongodb-native/7.0/classes/ClientSession.html#withTransaction),
  * but also handles resetting Mongoose document state as shown below.
  *
  * #### Example:
@@ -1025,7 +1025,7 @@ Connection.prototype.onOpen = function() {
  * Opens the connection with a URI using `MongoClient.connect()`.
  *
  * @param {string} uri The URI to connect with.
- * @param {object} [options] Passed on to [`MongoClient.connect`](https://mongodb.github.io/node-mongodb-native/4.9/classes/MongoClient.html#connect-1)
+ * @param {object} [options] Passed on to [`MongoClient.connect`](https://mongodb.github.io/node-mongodb-native/7.0/classes/MongoClient.html#connect)
  * @param {boolean} [options.bufferCommands=true] Mongoose specific option. Set to false to [disable buffering](https://mongoosejs.com/docs/faq.html#callback_never_executes) on all models associated with this connection.
  * @param {number} [options.bufferTimeoutMS=10000] Mongoose specific option. If `bufferCommands` is true, Mongoose will throw an error after `bufferTimeoutMS` if the operation is still buffered.
  * @param {string} [options.dbName] The name of the database we want to use. If not provided, use database name from connection string.
@@ -1036,7 +1036,6 @@ Connection.prototype.onOpen = function() {
  * @param {number} [options.serverSelectionTimeoutMS] If `useUnifiedTopology = true`, the MongoDB driver will try to find a server to send any given operation to, and keep retrying for `serverSelectionTimeoutMS` milliseconds before erroring out. If not set, the MongoDB driver defaults to using `30000` (30 seconds).
  * @param {number} [options.heartbeatFrequencyMS] If `useUnifiedTopology = true`, the MongoDB driver sends a heartbeat every `heartbeatFrequencyMS` to check on the status of the connection. A heartbeat is subject to `serverSelectionTimeoutMS`, so the MongoDB driver will retry failed heartbeats for up to 30 seconds by default. Mongoose only emits a `'disconnected'` event after a heartbeat has failed, so you may want to decrease this setting to reduce the time between when your server goes down and when Mongoose emits `'disconnected'`. We recommend you do **not** set this setting below 1000, too many heartbeats can lead to performance degradation.
  * @param {boolean} [options.autoIndex=true] Mongoose-specific option. Set to false to disable automatic index creation for all models associated with this connection.
- * @param {Class} [options.promiseLibrary] Sets the [underlying driver's promise library](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/MongoClientOptions.html#promiseLibrary).
  * @param {number} [options.socketTimeoutMS=0] How long the MongoDB driver will wait before killing a socket due to inactivity _after initial connection_. A socket may be inactive because of either no activity or a long-running operation. `socketTimeoutMS` defaults to 0, which means Node.js will not time out the socket due to inactivity. This option is passed to [Node.js `socket#setTimeout()` function](https://nodejs.org/api/net.html#net_socket_settimeout_timeout_callback) after the MongoDB driver successfully completes.
  * @param {number} [options.family=0] Passed transparently to [Node.js' `dns.lookup()`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) function. May be either `0, `4`, or `6`. `4` means use IPv4 only, `6` means use IPv6 only, `0` means try both.
  * @param {boolean} [options.autoCreate=false] Set to `true` to make Mongoose automatically call `createCollection()` on every model created on this connection.
@@ -1599,27 +1598,14 @@ Connection.prototype.deleteModel = function deleteModel(name) {
  *
  * @api public
  * @param {Array} [pipeline]
- * @param {object} [options] passed without changes to [the MongoDB driver's `Db#watch()` function](https://mongodb.github.io/node-mongodb-native/4.9/classes/Db.html#watch)
+ * @param {object} [options] passed without changes to [the MongoDB driver's `Db#watch()` function](https://mongodb.github.io/node-mongodb-native/7.0/classes/Db.html#watch)
  * @return {ChangeStream} mongoose-specific change stream wrapper, inherits from EventEmitter
  */
 
 Connection.prototype.watch = function watch(pipeline, options) {
-  const changeStreamThunk = cb => {
-    immediate(() => {
-      if (this.readyState === STATES.connecting) {
-        this.once('open', function() {
-          const driverChangeStream = this.db.watch(pipeline, options);
-          cb(null, driverChangeStream);
-        });
-      } else {
-        const driverChangeStream = this.db.watch(pipeline, options);
-        cb(null, driverChangeStream);
-      }
-    });
-  };
+  const changeStreamPromise = this._waitForConnect().then(() => this.db.watch(pipeline, options));
 
-  const changeStream = new ChangeStream(changeStreamThunk, pipeline, options);
-  return changeStream;
+  return new ChangeStream(changeStreamPromise, pipeline, options);
 };
 
 /**
@@ -1702,7 +1688,7 @@ Connection.prototype.optionsProvideAuthenticationData = function optionsProvideA
 };
 
 /**
- * Returns the [MongoDB driver `MongoClient`](https://mongodb.github.io/node-mongodb-native/4.9/classes/MongoClient.html) instance
+ * Returns the [MongoDB driver `MongoClient`](https://mongodb.github.io/node-mongodb-native/7.0/classes/MongoClient.html) instance
  * that this connection uses to talk to MongoDB.
  *
  * #### Example:
@@ -1721,7 +1707,7 @@ Connection.prototype.getClient = function getClient() {
 };
 
 /**
- * Set the [MongoDB driver `MongoClient`](https://mongodb.github.io/node-mongodb-native/4.9/classes/MongoClient.html) instance
+ * Set the [MongoDB driver `MongoClient`](https://mongodb.github.io/node-mongodb-native/7.0/classes/MongoClient.html) instance
  * that this connection uses to talk to MongoDB. This is useful if you already have a MongoClient instance, and want to
  * reuse it.
  *

package/lib/cursor/aggregationCursor.js

@@ -217,7 +217,7 @@ AggregationCursor.prototype._markError = function(error) {
  * @api public
  * @method close
  * @emits "close"
- * @see AggregationCursor.close https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html#close
+ * @see AggregationCursor.close https://mongodb.github.io/node-mongodb-native/7.0/classes/AggregationCursor.html#close
  */
 
 AggregationCursor.prototype.close = async function close() {
@@ -386,7 +386,7 @@ function _transformForAsyncIterator(doc) {
 }
 
 /**
- * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html#addCursorFlag).
+ * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/7.0/classes/AggregationCursor.html#addCursorFlag).
  * Useful for setting the `noCursorTimeout` and `tailable` flags.
  *
  * @param {'tailable'|'oplogReplay'|'noCursorTimeout'|'awaitData'|'partial'} flag

package/lib/cursor/changeStream.js

@@ -18,7 +18,7 @@ const driverChangeStreamEvents = ['close', 'change', 'end', 'error', 'resumeToke
  */
 
 class ChangeStream extends EventEmitter {
-  constructor(changeStreamThunk, pipeline, options) {
+  constructor(changeStreamPromise, pipeline, options) {
     super();
 
     this.driverChangeStream = null;
@@ -35,36 +35,22 @@ class ChangeStream extends EventEmitter {
       );
     }
 
-    let syncError = null;
-    this.$driverChangeStreamPromise = new Promise((resolve, reject) => {
-      // This wrapper is necessary because of buffering.
-      try {
-        changeStreamThunk((err, driverChangeStream) => {
-          if (err != null) {
-            this.errored = true;
-            this.emit('error', err);
-            return reject(err);
-          }
-
-          this.driverChangeStream = driverChangeStream;
-          this.emit('ready');
-          resolve();
-        });
-      } catch (err) {
-        syncError = err;
+    this.$driverChangeStreamPromise = changeStreamPromise.then(
+      driverChangeStream => {
+        this.driverChangeStream = driverChangeStream;
+        // Use setImmediate so the stream pump (_read) has a chance to run and
+        // the driver cursor initializes before 'ready' resolves. Without this,
+        // changes emitted immediately after 'ready' can be missed because the
+        // underlying cursor hasn't sent its initial aggregate to MongoDB yet.
+        setImmediate(() => this.emit('ready'));
+        return this;
+      },
+      err => {
         this.errored = true;
         this.emit('error', err);
-        reject(err);
+        throw err;
       }
-    });
-
-    // Because a ChangeStream is an event emitter, there's no way to register an 'error' handler
-    // that catches errors which occur in the constructor, unless we force sync errors into async
-    // errors with setImmediate(). For cleaner stack trace, we just immediately throw any synchronous
-    // errors that occurred with changeStreamThunk().
-    if (syncError != null) {
-      throw syncError;
-    }
+    );
   }
 
   _bindEvents() {
@@ -114,7 +100,20 @@ class ChangeStream extends EventEmitter {
     if (this.errored) {
       throw new MongooseError('Cannot call hasNext() on errored ChangeStream');
     }
-    return this.driverChangeStream.hasNext(cb);
+
+    if (this.driverChangeStream != null) {
+      return this.driverChangeStream.hasNext(cb);
+    }
+
+    return this.$driverChangeStreamPromise.then(
+      () => this.driverChangeStream.hasNext(cb),
+      err => {
+        if (cb != null) {
+          return cb(err);
+        }
+        throw err;
+      }
+    );
   }
 
   next(cb) {
@@ -135,7 +134,20 @@ class ChangeStream extends EventEmitter {
         };
       }
 
-      let maybePromise = this.driverChangeStream.next(cb);
+      let maybePromise;
+      if (this.driverChangeStream != null) {
+        maybePromise = this.driverChangeStream.next(cb);
+      } else {
+        maybePromise = this.$driverChangeStreamPromise.then(
+          () => this.driverChangeStream.next(cb),
+          err => {
+            if (cb != null) {
+              return cb(err);
+            }
+            throw err;
+          }
+        );
+      }
       if (typeof maybePromise?.then === 'function') {
         maybePromise = maybePromise.then(data => {
           if (data.fullDocument != null) {
@@ -147,7 +159,19 @@ class ChangeStream extends EventEmitter {
       return maybePromise;
     }
 
-    return this.driverChangeStream.next(cb);
+    if (this.driverChangeStream != null) {
+      return this.driverChangeStream.next(cb);
+    }
+
+    return this.$driverChangeStreamPromise.then(
+      () => this.driverChangeStream.next(cb),
+      err => {
+        if (cb != null) {
+          return cb(err);
+        }
+        throw err;
+      }
+    );
   }
 
   addListener(event, handler) {
@@ -174,10 +198,6 @@ class ChangeStream extends EventEmitter {
     return super.once(event, handler);
   }
 
-  _queue(cb) {
-    this.once('ready', () => cb());
-  }
-
   close() {
     this.closed = true;
     if (this.driverChangeStream) {

package/lib/cursor/queryCursor.js

@@ -227,7 +227,7 @@ QueryCursor.prototype._markError = function(error) {
  * @api public
  * @method close
  * @emits close
- * @see AggregationCursor.close https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html#close
+ * @see AggregationCursor.close https://mongodb.github.io/node-mongodb-native/7.0/classes/AggregationCursor.html#close
  */
 
 QueryCursor.prototype.close = async function close() {
@@ -368,7 +368,7 @@ QueryCursor.prototype.eachAsync = function(fn, opts) {
 QueryCursor.prototype.options;
 
 /**
- * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/4.9/classes/FindCursor.html#addCursorFlag).
+ * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/7.0/classes/FindCursor.html#addCursorFlag).
  * Useful for setting the `noCursorTimeout` and `tailable` flags.
  *
  * @param {'tailable'|'oplogReplay'|'noCursorTimeout'|'awaitData'|'partial'} flag