mongoose 9.2.3 → 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
@@ -159,7 +159,7 @@ Aggregate.prototype.model = function(model) {
  *     const pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
  *     aggregate.append(pipeline);
  *
- * @param {...Object|Object[]} ops operator(s) to append. Can either be a spread of objects or a single parameter of a object array.
+ * @param {...object|object[]} ops operator(s) to append. Can either be a spread of objects or a single parameter of a object array.
  * @return {Aggregate}
  * @api public
  */
@@ -196,7 +196,7 @@ Aggregate.prototype.append = function() {
  *     // etc
  *     aggregate.addFields({ salary_k: { $divide: [ "$salary", 1000 ] } });
  *
- * @param {Object} arg field specification
+ * @param {object} arg field specification
  * @see $addFields https://www.mongodb.com/docs/manual/reference/operator/aggregation/addFields/
  * @return {Aggregate}
  * @api public
@@ -234,7 +234,7 @@ Aggregate.prototype.addFields = function(arg) {
  *     // etc
  *     aggregate.project({ salary_k: { $divide: [ "$salary", 1000 ] } });
  *
- * @param {Object|String} arg field specification
+ * @param {object|string} arg field specification
  * @see projection https://www.mongodb.com/docs/manual/reference/aggregation/project/
  * @return {Aggregate}
  * @api public
@@ -276,7 +276,7 @@ Aggregate.prototype.project = function(arg) {
  * @method group
  * @memberOf Aggregate
  * @instance
- * @param {Object} arg $group operator contents
+ * @param {object} arg $group operator contents
  * @return {Aggregate}
  * @api public
  */
@@ -292,7 +292,7 @@ Aggregate.prototype.project = function(arg) {
  * @method match
  * @memberOf Aggregate
  * @instance
- * @param {Object} arg $match operator contents
+ * @param {object} arg $match operator contents
  * @return {Aggregate}
  * @api public
  */
@@ -308,7 +308,7 @@ Aggregate.prototype.project = function(arg) {
  * @method skip
  * @memberOf Aggregate
  * @instance
- * @param {Number} num number of records to skip before next stage
+ * @param {number} num number of records to skip before next stage
  * @return {Aggregate}
  * @api public
  */
@@ -324,7 +324,7 @@ Aggregate.prototype.project = function(arg) {
  * @method limit
  * @memberOf Aggregate
  * @instance
- * @param {Number} num maximum number of records to pass to the next stage
+ * @param {number} num maximum number of records to pass to the next stage
  * @return {Aggregate}
  * @api public
  */
@@ -348,7 +348,7 @@ Aggregate.prototype.project = function(arg) {
  * @method densify
  * @memberOf Aggregate
  * @instance
- * @param {Object} arg $densify operator contents
+ * @param {object} arg $densify operator contents
  * @return {Aggregate}
  * @api public
  */
@@ -370,7 +370,7 @@ Aggregate.prototype.project = function(arg) {
  * @method fill
  * @memberOf Aggregate
  * @instance
- * @param {Object} arg $fill operator contents
+ * @param {object} arg $fill operator contents
  * @return {Aggregate}
  * @api public
  */
@@ -397,8 +397,8 @@ Aggregate.prototype.project = function(arg) {
  * @method near
  * @memberOf Aggregate
  * @instance
- * @param {Object} arg
- * @param {Object|Array<Number>} arg.near GeoJSON point or coordinates array
+ * @param {object} arg
+ * @param {object|number[]} arg.near GeoJSON point or coordinates array
  * @return {Aggregate}
  * @api public
  */
@@ -445,7 +445,7 @@ Aggregate.prototype.near = function(arg) {
  *     aggregate.unwind({ path: '$tags', preserveNullAndEmptyArrays: true });
  *
  * @see $unwind https://www.mongodb.com/docs/manual/reference/aggregation/unwind/
- * @param {String|Object|String[]|Object[]} fields the field(s) to unwind, either as field names or as [objects with options](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#document-operand-with-options). If passing a string, prefixing the field name with '$' is optional. If passing an object, `path` must start with '$'.
+ * @param {string|object|string[]|object[]} fields the field(s) to unwind, either as field names or as [objects with options](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#document-operand-with-options). If passing a string, prefixing the field name with '$' is optional. If passing an object, `path` must start with '$'.
  * @return {Aggregate}
  * @api public
  */
@@ -484,7 +484,7 @@ Aggregate.prototype.unwind = function() {
  *     aggregate.replaceRoot({ x: { $concat: ['$this', '$that'] } });
  *
  * @see $replaceRoot https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot
- * @param {String|Object} newRoot the field or document which will become the new root document
+ * @param {string|object} newRoot the field or document which will become the new root document
  * @return {Aggregate}
  * @api public
  */
@@ -513,7 +513,7 @@ Aggregate.prototype.replaceRoot = function(newRoot) {
  *     aggregate.count("userCount");
  *
  * @see $count https://www.mongodb.com/docs/manual/reference/operator/aggregation/count
- * @param {String} fieldName The name of the output field which has the count as its value. It must be a non-empty string, must not start with $ and must not contain the . character.
+ * @param {string} fieldName The name of the output field which has the count as its value. It must be a non-empty string, must not start with $ and must not contain the . character.
  * @return {Aggregate}
  * @api public
  */
@@ -535,7 +535,7 @@ Aggregate.prototype.count = function(fieldName) {
  *     aggregate.sortByCount({ $mergeObjects: [ "$employee", "$business" ] })
  *
  * @see $sortByCount https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/
- * @param {Object|String} arg
+ * @param {object|string} arg
  * @return {Aggregate} this
  * @api public
  */
@@ -561,7 +561,7 @@ Aggregate.prototype.sortByCount = function(arg) {
  *     aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });
  *
  * @see $lookup https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#pipe._S_lookup
- * @param {Object} options to $lookup as described in the above link
+ * @param {object} options to $lookup as described in the above link
  * @return {Aggregate}
  * @api public
  */
@@ -581,7 +581,7 @@ Aggregate.prototype.lookup = function(options) {
  *      aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites
  *
  * @see $graphLookup https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/#pipe._S_graphLookup
- * @param {Object} options to $graphLookup as described in the above link
+ * @param {object} options to $graphLookup as described in the above link
  * @return {Aggregate}
  * @api public
  */
@@ -614,7 +614,7 @@ Aggregate.prototype.graphLookup = function(options) {
  *     aggregate.sample(3); // Add a pipeline that picks 3 random documents
  *
  * @see $sample https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/#pipe._S_sample
- * @param {Number} size number of random documents to pick
+ * @param {number} size number of random documents to pick
  * @return {Aggregate}
  * @api public
  */
@@ -637,7 +637,7 @@ Aggregate.prototype.sample = function(size) {
  *     aggregate.sort('field -test');
  *
  * @see $sort https://www.mongodb.com/docs/manual/reference/aggregation/sort/
- * @param {Object|String} arg
+ * @param {object|string} arg
  * @return {Aggregate} this
  * @api public
  */
@@ -683,7 +683,7 @@ Aggregate.prototype.sort = function(arg) {
  *     aggregate.unionWith({ coll: 'users', pipeline: [ { $match: { _id: 1 } } ] });
  *
  * @see $unionWith https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith
- * @param {Object} options to $unionWith query as described in the above link
+ * @param {object} options to $unionWith query as described in the above link
  * @return {Aggregate}
  * @api public
  */
@@ -700,7 +700,7 @@ Aggregate.prototype.unionWith = function(options) {
  *
  *     await Model.aggregate(pipeline).read('primaryPreferred');
  *
- * @param {String|ReadPreference} pref one of the listed preference options or their aliases
+ * @param {string|ReadPreference} pref one of the listed preference options or their aliases
  * @param {Array} [tags] optional tags for this query.
  * @return {Aggregate} this
  * @api public
@@ -749,9 +749,9 @@ Aggregate.prototype.readConcern = function(level) {
  *     // $redact often comes with $cond operator, you can also use the following syntax provided by mongoose
  *     await Model.aggregate(pipeline).redact({ $eq: [ '$level', 5 ] }, '$$PRUNE', '$$DESCEND');
  *
- * @param {Object} expression redact options or conditional expression
- * @param {String|Object} [thenExpr] true case for the condition
- * @param {String|Object} [elseExpr] false case for the condition
+ * @param {object} expression redact options or conditional expression
+ * @param {string|object} [thenExpr] true case for the condition
+ * @param {string|object} [elseExpr] false case for the condition
  * @return {Aggregate} this
  * @see $redact https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/
  * @api public
@@ -839,7 +839,7 @@ Aggregate.prototype.explain = async function explain(verbosity) {
  *
  *     await Model.aggregate([{ $match: { foo: 'bar' } }]).allowDiskUse(true);
  *
- * @param {Boolean} value Should tell server it can use hard drive to store data during aggregation.
+ * @param {boolean} value Should tell server it can use hard drive to store data during aggregation.
  * @return {Aggregate} this
  * @see mongodb https://www.mongodb.com/docs/manual/reference/command/aggregate/
  */
@@ -856,7 +856,7 @@ Aggregate.prototype.allowDiskUse = function(value) {
  *
  *     Model.aggregate(..).hint({ qty: 1, category: 1 }).exec();
  *
- * @param {Object|String} value a hint object or the index name
+ * @param {object|string} value a hint object or the index name
  * @return {Aggregate} this
  * @see mongodb https://www.mongodb.com/docs/manual/reference/command/aggregate/
  */
@@ -896,14 +896,14 @@ Aggregate.prototype.session = function(session) {
  *     const agg = Model.aggregate(..).option({ allowDiskUse: true }); // Set the `allowDiskUse` option
  *     agg.options; // `{ allowDiskUse: true }`
  *
- * @param {Object} options keys to merge into current options
- * @param {Number} [options.maxTimeMS] number limits the time this aggregation will run, see [MongoDB docs on `maxTimeMS`](https://www.mongodb.com/docs/manual/reference/operator/meta/maxTimeMS/)
- * @param {Boolean} [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation
- * @param {Object} [options.collation] object see [`Aggregate.prototype.collation()`](https://mongoosejs.com/docs/api/aggregate.html#Aggregate.prototype.collation())
+ * @param {object} options keys to merge into current options
+ * @param {number} [options.maxTimeMS] number limits the time this aggregation will run, see [MongoDB docs on `maxTimeMS`](https://www.mongodb.com/docs/manual/reference/operator/meta/maxTimeMS/)
+ * @param {boolean} [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation
+ * @param {object} [options.collation] object see [`Aggregate.prototype.collation()`](https://mongoosejs.com/docs/api/aggregate.html#Aggregate.prototype.collation())
  * @param {ClientSession} [options.session] ClientSession see [`Aggregate.prototype.session()`](https://mongoosejs.com/docs/api/aggregate.html#Aggregate.prototype.session())
- * @param {Boolean|Object} [options.middleware=true] set to `false` to skip all user-defined middleware
- * @param {Boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
- * @param {Boolean} [options.middleware.post=true] set to `false` to skip only post hooks
+ * @param {boolean|object} [options.middleware=true] set to `false` to skip all user-defined middleware
+ * @param {boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
+ * @param {boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @see mongodb https://www.mongodb.com/docs/manual/reference/command/aggregate/
  * @return {Aggregate} this
  * @api public
@@ -928,12 +928,12 @@ Aggregate.prototype.option = function(value) {
  *       // use doc
  *     });
  *
- * @param {Object} options
- * @param {Number} [options.batchSize] set the cursor batch size
- * @param {Boolean} [options.useMongooseAggCursor] use experimental mongoose-specific aggregation cursor (for `eachAsync()` and other query cursor semantics)
+ * @param {object} options
+ * @param {number} [options.batchSize] set the cursor batch size
+ * @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) {
@@ -949,10 +949,10 @@ Aggregate.prototype.cursor = function(options) {
  *
  *     const res = await Model.aggregate(pipeline).collation({ locale: 'en_US', strength: 1 });
  *
- * @param {Object} collation 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) {
@@ -972,7 +972,7 @@ Aggregate.prototype.collation = function(collation) {
  *
  *     // Output: { books: [...], price: [{...}, {...}] }
  *
- * @param {Object} facet options
+ * @param {object} facet options
  * @return {Aggregate} this
  * @see $facet https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/
  * @api public
@@ -998,7 +998,7 @@ Aggregate.prototype.facet = function(options) {
  *
  *     // Output: [{ plot: '...', title: '...' }]
  *
- * @param {Object} $search options
+ * @param {object} $search options
  * @return {Aggregate} this
  * @see $search https://www.mongodb.com/docs/atlas/atlas-search/tutorial/
  * @api public
@@ -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.
  *
@@ -1170,8 +1193,8 @@ Aggregate.prototype[Symbol.asyncIterator] = function() {
 /**
  * Checks whether an object is likely a pipeline operator
  *
- * @param {Object} obj object to check
- * @return {Boolean}
+ * @param {object} obj object to check
+ * @return {boolean}
  * @api private
  */
 

package/lib/cast/bigint.js

@@ -6,8 +6,8 @@ const { Long } = require('mongodb/lib/bson');
  * Given a value, cast it to a BigInt, or throw an `Error` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *
- * @param {Any} value
- * @return {Number}
+ * @param {any} value
+ * @return {bigint|null|undefined}
  * @throws {Error} if `value` is not one of the allowed values
  * @api private
  */

package/lib/cast/boolean.js

@@ -6,9 +6,9 @@ const CastError = require('../error/cast');
  * Given a value, cast it to a boolean, or throw a `CastError` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *
- * @param {Any} value
- * @param {String} [path] optional the path to set on the CastError
- * @return {Boolean|null|undefined}
+ * @param {any} value
+ * @param {string} [path] optional the path to set on the CastError
+ * @return {boolean|null|undefined}
  * @throws {CastError} if `value` is not one of the allowed values
  * @api private
  */

package/lib/cast/double.js

@@ -8,8 +8,8 @@ const isBsonType = require('../helpers/isBsonType');
  * Given a value, cast it to a IEEE 754-2008 floating point, or throw an `Error` if the value
  * cannot be casted. `null`, `undefined`, and `NaN` are considered valid inputs.
  *
- * @param {Any} value
- * @return {Number}
+ * @param {any} value
+ * @return {number}
  * @throws {Error} if `value` does not represent a IEEE 754-2008 floating point. If casting from a string, see [BSON Double.fromString API documentation](https://mongodb.github.io/node-mongodb-native/Next/classes/BSON.Double.html#fromString)
  * @api private
  */

package/lib/cast/int32.js

@@ -7,8 +7,8 @@ const assert = require('assert');
  * Given a value, cast it to a Int32, or throw an `Error` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *
- * @param {Any} value
- * @return {Number}
+ * @param {any} value
+ * @return {number}
  * @throws {Error} if `value` does not represent an integer, or is outside the bounds of an 32-bit integer.
  * @api private
  */

package/lib/cast/number.js

@@ -6,8 +6,8 @@ const assert = require('assert');
  * Given a value, cast it to a number, or throw an `Error` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *
- * @param {Any} value
- * @return {Number}
+ * @param {any} value
+ * @return {number}
  * @throws {Error} if `value` is not one of the allowed values
  * @api private
  */

package/lib/cast/string.js

@@ -6,8 +6,8 @@ const CastError = require('../error/cast');
  * Given a value, cast it to a string, or throw a `CastError` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
  *
- * @param {Any} value
- * @param {String} [path] optional the path to set on the CastError
+ * @param {any} value
+ * @param {string} [path] optional the path to set on the CastError
  * @return {string|null|undefined}
  * @throws {CastError}
  * @api private

package/lib/cast.js

@@ -24,12 +24,12 @@ const ALLOWED_GEOWITHIN_GEOJSON_TYPES = ['Polygon', 'MultiPolygon'];
  * Handles internal casting for query filters.
  *
  * @param {Schema} schema
- * @param {Object} obj Object to cast
- * @param {Object} [options] the query options
- * @param {Boolean|"throw"} [options.strict] Wheter to enable all strict options
- * @param {Boolean|"throw"} [options.strictQuery] Enable strict Queries
- * @param {Boolean} [options.sanitizeFilter] avoid adding implict query selectors ($in)
- * @param {Boolean} [options.upsert]
+ * @param {object} obj Object to cast
+ * @param {object} [options] the query options
+ * @param {boolean|"throw"} [options.strict] Whether to enable all strict options
+ * @param {boolean|"throw"} [options.strictQuery] Enable strict Queries
+ * @param {boolean} [options.sanitizeFilter] avoid adding implicit query selectors ($in)
+ * @param {boolean} [options.upsert]
  * @param {Query} [context] passed to setters
  * @api private
  */

package/lib/collection.js

@@ -13,9 +13,9 @@ const immediate = require('./helpers/immediate');
  *
  * This is the base class that drivers inherit from and implement.
  *
- * @param {String} name name of the collection
+ * @param {string} name name of the collection
  * @param {Connection} conn A MongooseConnection instance
- * @param {Object} [opts] optional collection options
+ * @param {object} [opts] optional collection options
  * @api public
  */
 
@@ -87,7 +87,7 @@ Collection.prototype.onClose = function() {};
  * Queues a method for later execution when its
  * database connection opens.
  *
- * @param {String} name name of the method to queue
+ * @param {string} name name of the method to queue
  * @param {Array} args arguments to pass to the method when executed
  * @api private
  */
@@ -100,7 +100,7 @@ Collection.prototype.addQueue = function(name, args) {
 /**
  * Removes a queued method
  *
- * @param {String} name name of the method to queue
+ * @param {string} name name of the method to queue
  * @param {Array} args arguments to pass to the method when executed
  * @api private
  */