mongoose 8.9.6 → 8.10.0

package/lib/aggregate.js

@@ -13,6 +13,7 @@ const getConstructorName = require('./helpers/getConstructorName');
 const prepareDiscriminatorPipeline = require('./helpers/aggregate/prepareDiscriminatorPipeline');
 const stringifyFunctionOperators = require('./helpers/aggregate/stringifyFunctionOperators');
 const utils = require('./utils');
+const { modelSymbol } = require('./helpers/symbols');
 const read = Query.prototype.read;
 const readConcern = Query.prototype.readConcern;
 
@@ -46,13 +47,17 @@ const validRedactStringValues = new Set(['$$DESCEND', '$$PRUNE', '$$KEEP']);
  * @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
  * @param {Array} [pipeline] aggregation pipeline as an array of objects
- * @param {Model} [model] the model to use with this aggregate.
+ * @param {Model|Connection} [modelOrConn] the model or connection to use with this aggregate.
  * @api public
  */
 
-function Aggregate(pipeline, model) {
+function Aggregate(pipeline, modelOrConn) {
   this._pipeline = [];
-  this._model = model;
+  if (modelOrConn == null || modelOrConn[modelSymbol]) {
+    this._model = modelOrConn;
+  } else {
+    this._connection = modelOrConn;
+  }
   this.options = {};
 
   if (arguments.length === 1 && Array.isArray(pipeline)) {
@@ -1041,12 +1046,24 @@ Aggregate.prototype.pipeline = function() {
  */
 
 Aggregate.prototype.exec = async function exec() {
-  if (!this._model) {
+  if (!this._model && !this._connection) {
     throw new Error('Aggregate not bound to any Model');
   }
   if (typeof arguments[0] === 'function') {
     throw new MongooseError('Aggregate.prototype.exec() no longer accepts a callback');
   }
+
+  if (this._connection) {
+    if (!this._pipeline.length) {
+      throw new MongooseError('Aggregate has empty pipeline');
+    }
+
+    this._optionsForExec();
+
+    const cursor = await this._connection.client.db().aggregate(this._pipeline, this.options);
+    return await cursor.toArray();
+  }
+
   const model = this._model;
   const collection = this._model.collection;
 

package/lib/collection.js

@@ -29,7 +29,7 @@ function Collection(name, conn, opts) {
   this.collectionName = name;
   this.conn = conn;
   this.queue = [];
-  this.buffer = true;
+  this.buffer = !conn?._hasOpened;
   this.emitter = new EventEmitter();
 
   if (STATES.connected === this.conn.readyState) {
@@ -311,13 +311,7 @@ Collection.prototype._getBufferTimeoutMS = function _getBufferTimeoutMS() {
   if (opts && opts.schemaUserProvidedOptions != null && opts.schemaUserProvidedOptions.bufferTimeoutMS != null) {
     return opts.schemaUserProvidedOptions.bufferTimeoutMS;
   }
-  if (conn.config.bufferTimeoutMS != null) {
-    return conn.config.bufferTimeoutMS;
-  }
-  if (conn.base != null && conn.base.get('bufferTimeoutMS') != null) {
-    return conn.base.get('bufferTimeoutMS');
-  }
-  return 10000;
+  return conn._getBufferTimeoutMS();
 };
 
 /*!

package/lib/connection.js

@@ -824,12 +824,56 @@ Connection.prototype.dropCollection = async function dropCollection(collection)
 
 Connection.prototype._waitForConnect = async function _waitForConnect() {
   if ((this.readyState === STATES.connecting || this.readyState === STATES.disconnected) && this._shouldBufferCommands()) {
-    await new Promise(resolve => {
-      this._queue.push({ fn: resolve });
-    });
+    const bufferTimeoutMS = this._getBufferTimeoutMS();
+    let timeout = null;
+    let timedOut = false;
+    // The element that this function pushes onto `_queue`, stored to make it easy to remove later
+    const queueElement = {};
+    await Promise.race([
+      new Promise(resolve => {
+        queueElement.fn = resolve;
+        this._queue.push(queueElement);
+      }),
+      new Promise(resolve => {
+        timeout = setTimeout(
+          () => {
+            timedOut = true;
+            resolve();
+          },
+          bufferTimeoutMS
+        );
+      })
+    ]);
+
+    if (timedOut) {
+      const index = this._queue.indexOf(queueElement);
+      if (index !== -1) {
+        this._queue.splice(index, 1);
+      }
+      const message = 'Connection operation buffering timed out after ' + bufferTimeoutMS + 'ms';
+      throw new MongooseError(message);
+    } else if (timeout != null) {
+      // Not strictly necessary, but avoid the extra overhead of creating a new MongooseError
+      // in case of success
+      clearTimeout(timeout);
+    }
   }
 };
 
+/*!
+ * Get the default buffer timeout for this connection
+ */
+
+Connection.prototype._getBufferTimeoutMS = function _getBufferTimeoutMS() {
+  if (this.config.bufferTimeoutMS != null) {
+    return this.config.bufferTimeoutMS;
+  }
+  if (this.base != null && this.base.get('bufferTimeoutMS') != null) {
+    return this.base.get('bufferTimeoutMS');
+  }
+  return 10000;
+};
+
 /**
  * Helper for MongoDB Node driver's `listCollections()`.
  * Returns an array of collection objects.
@@ -1156,6 +1200,10 @@ Connection.prototype.close = async function close(force) {
     this.$wasForceClosed = !!force;
   }
 
+  if (this._lastHeartbeatAt != null) {
+    this._lastHeartbeatAt = null;
+  }
+
   for (const model of Object.values(this.models)) {
     // If manually disconnecting, make sure to clear each model's `$init`
     // promise, so Mongoose knows to re-run `init()` in case the
@@ -1742,6 +1790,18 @@ Connection.prototype.syncIndexes = async function syncIndexes(options = {}) {
  * @api public
  */
 
+/**
+ * Runs a [db-level aggregate()](https://www.mongodb.com/docs/manual/reference/method/db.aggregate/) on this connection's underlying `db`
+ *
+ * @method aggregate
+ * @memberOf Connection
+ * @param {Array} pipeline
+ * @param {Object} [options]
+ * @param {Boolean} [options.cursor=false] If true, make the Aggregate resolve to a Mongoose AggregationCursor rather than an array
+ * @return {Aggregate} Aggregation wrapper
+ * @api public
+ */
+
 /**
  * Removes the database connection with the given name created with with `useDb()`.
  *

package/lib/cursor/aggregationCursor.js

@@ -41,11 +41,17 @@ function AggregationCursor(agg) {
   this.cursor = null;
   this.agg = agg;
   this._transforms = [];
+  const connection = agg._connection;
   const model = agg._model;
   delete agg.options.cursor.useMongooseAggCursor;
   this._mongooseOptions = {};
 
-  _init(model, this, agg);
+  if (connection) {
+    this.cursor = connection.db.aggregate(agg._pipeline, agg.options || {});
+    setImmediate(() => this.emit('cursor', this.cursor));
+  } else {
+    _init(model, this, agg);
+  }
 }
 
 util.inherits(AggregationCursor, Readable);

package/lib/document.js

@@ -807,8 +807,8 @@ function init(self, obj, doc, opts, prefix) {
               reason: e
             }));
           }
-        } else if (opts.hydratedPopulatedDocs) {
-          doc[i] = schemaType.cast(value, self, true);
+        } else if (schemaType && opts.hydratedPopulatedDocs) {
+          doc[i] = schemaType.cast(value, self, true, undefined, { hydratedPopulatedDocs: true });
 
           if (doc[i] && doc[i].$__ && doc[i].$__.wasPopulated) {
             self.$populated(path, doc[i].$__.wasPopulated.value, doc[i].$__.wasPopulated.options);
@@ -4069,7 +4069,7 @@ Document.prototype.$__toObjectShallow = function $__toObjectShallow() {
  * @param {Boolean} [options.flattenMaps=false] if true, convert Maps to POJOs. Useful if you want to `JSON.stringify()` the result of `toObject()`.
  * @param {Boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
  * @param {Boolean} [options.useProjection=false] - If true, omits fields that are excluded in this document's projection. Unless you specified a projection, this will omit any field that has `select: false` in the schema.
- * @return {Object} js object (not a POJO)
+ * @return {Object} document as a plain old JavaScript object (POJO). This object may contain ObjectIds, Maps, Dates, mongodb.Binary, Buffers, and other non-POJO values.
  * @see mongodb.Binary https://mongodb.github.io/node-mongodb-native/4.9/classes/Binary.html
  * @api public
  * @memberOf Document
@@ -4256,24 +4256,25 @@ function applySchemaTypeTransforms(self, json) {
 
   for (const path of paths) {
     const schematype = schema.paths[path];
-    if (typeof schematype.options.transform === 'function') {
+    const topLevelTransformFunction = schematype.options.transform ?? schematype.constructor?.defaultOptions?.transform;
+    const embeddedSchemaTypeTransformFunction = schematype.$embeddedSchemaType?.options?.transform
+      ?? schematype.$embeddedSchemaType?.constructor?.defaultOptions?.transform;
+    if (typeof topLevelTransformFunction === 'function') {
       const val = self.$get(path);
       if (val === undefined) {
         continue;
       }
-      const transformedValue = schematype.options.transform.call(self, val);
+      const transformedValue = topLevelTransformFunction.call(self, val);
       throwErrorIfPromise(path, transformedValue);
       utils.setValue(path, transformedValue, json);
-    } else if (schematype.$embeddedSchemaType != null &&
-        typeof schematype.$embeddedSchemaType.options.transform === 'function') {
+    } else if (typeof embeddedSchemaTypeTransformFunction === 'function') {
       const val = self.$get(path);
       if (val === undefined) {
         continue;
       }
       const vals = [].concat(val);
-      const transform = schematype.$embeddedSchemaType.options.transform;
       for (let i = 0; i < vals.length; ++i) {
-        const transformedValue = transform.call(self, vals[i]);
+        const transformedValue = embeddedSchemaTypeTransformFunction.call(self, vals[i]);
         vals[i] = transformedValue;
         throwErrorIfPromise(path, transformedValue);
       }

package/lib/drivers/node-mongodb-native/connection.js

@@ -132,6 +132,17 @@ NativeConnection.prototype.useDb = function(name, options) {
   return newConn;
 };
 
+/**
+ * Runs a [db-level aggregate()](https://www.mongodb.com/docs/manual/reference/method/db.aggregate/) on this connection's underlying `db`
+ *
+ * @param {Array} pipeline
+ * @param {Object} [options]
+ */
+
+NativeConnection.prototype.aggregate = function aggregate(pipeline, options) {
+  return new this.base.Aggregate(null, this).append(pipeline).option(options ?? {});
+};
+
 /**
  * Removes the database connection with the given name created with `useDb()`.
  *
@@ -270,6 +281,11 @@ NativeConnection.prototype.createClient = async function createClient(uri, optio
       delete options.autoSearchIndex;
     }
 
+    if ('bufferTimeoutMS' in options) {
+      this.config.bufferTimeoutMS = options.bufferTimeoutMS;
+      delete options.bufferTimeoutMS;
+    }
+
     // Backwards compat
     if (options.user || options.pass) {
       options.auth = options.auth || {};
@@ -415,6 +431,9 @@ function _setClient(conn, client, options, dbName) {
       }
     });
   }
+
+  conn._lastHeartbeatAt = null;
+
   client.on('serverHeartbeatSucceeded', () => {
     conn._lastHeartbeatAt = Date.now();
   });

package/lib/helpers/createJSONSchemaTypeDefinition.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Handles creating `{ type: 'object' }` vs `{ bsonType: 'object' }` vs `{ bsonType: ['object', 'null'] }`
+ *
+ * @param {String} type
+ * @param {String} bsonType
+ * @param {Boolean} useBsonType
+ * @param {Boolean} isRequired
+ */
+
+module.exports = function createJSONSchemaTypeArray(type, bsonType, useBsonType, isRequired) {
+  if (useBsonType) {
+    if (isRequired) {
+      return { bsonType };
+    }
+    return { bsonType: [bsonType, 'null'] };
+  } else {
+    if (isRequired) {
+      return { type };
+    }
+    return { type: [type, 'null'] };
+  }
+};

package/lib/helpers/document/applyDefaults.js

@@ -19,6 +19,9 @@ module.exports = function applyDefaults(doc, fields, exclude, hasIncludedChildre
     const type = doc.$__schema.paths[p];
     const path = type.splitPath();
     const len = path.length;
+    if (path[len - 1] === '$*') {
+      continue;
+    }
     let included = false;
     let doc_ = doc._doc;
     for (let j = 0; j < len; ++j) {

package/lib/model.js

@@ -64,7 +64,6 @@ const prepareDiscriminatorPipeline = require('./helpers/aggregate/prepareDiscrim
 const pushNestedArrayPaths = require('./helpers/model/pushNestedArrayPaths');
 const removeDeselectedForeignField = require('./helpers/populate/removeDeselectedForeignField');
 const setDottedPath = require('./helpers/path/setDottedPath');
-const STATES = require('./connectionState');
 const util = require('util');
 const utils = require('./utils');
 const minimize = require('./helpers/minimize');
@@ -151,6 +150,62 @@ Model.prototype.$isMongooseModelPrototype = true;
 
 Model.prototype.db;
 
+/**
+ * Changes the Connection instance this model uses to make requests to MongoDB.
+ * This function is most useful for changing the Connection that a Model defined using `mongoose.model()` uses
+ * after initialization.
+ *
+ * #### Example:
+ *
+ *     await mongoose.connect('mongodb://127.0.0.1:27017/db1');
+ *     const UserModel = mongoose.model('User', mongoose.Schema({ name: String }));
+ *     UserModel.connection === mongoose.connection; // true
+ *
+ *     const conn2 = await mongoose.createConnection('mongodb://127.0.0.1:27017/db2').asPromise();
+ *     UserModel.useConnection(conn2); // `UserModel` now stores documents in `db2`, not `db1`
+ *
+ *     UserModel.connection === mongoose.connection; // false
+ *     UserModel.connection === conn2; // true
+ *
+ *     conn2.model('User') === UserModel; // true
+ *     mongoose.model('User'); // Throws 'MissingSchemaError'
+ *
+ * Note: `useConnection()` does **not** apply any [connection-level plugins](https://mongoosejs.com/docs/api/connection.html#Connection.prototype.plugin()) from the new connection.
+ * If you use `useConnection()` to switch a model's connection, the model will still have the old connection's plugins.
+ *
+ * @function useConnection
+ * @param [Connection] connection The new connection to use
+ * @return [Model] this
+ * @api public
+ */
+
+Model.useConnection = function useConnection(connection) {
+  if (!connection) {
+    throw new Error('Please provide a connection.');
+  }
+  if (this.db) {
+    delete this.db.models[this.modelName];
+    delete this.prototype.db;
+    delete this.prototype[modelDbSymbol];
+    delete this.prototype.collection;
+    delete this.prototype.$collection;
+    delete this.prototype[modelCollectionSymbol];
+  }
+
+  this.db = connection;
+  const collection = connection.collection(this.modelName, connection.options);
+  this.prototype.collection = collection;
+  this.prototype.$collection = collection;
+  this.prototype[modelCollectionSymbol] = collection;
+  this.prototype.db = connection;
+  this.prototype[modelDbSymbol] = connection;
+  this.collection = collection;
+  this.$__collection = collection;
+  connection.models[this.modelName] = this;
+
+  return this;
+};
+
 /**
  * The collection instance this model uses.
  * A Mongoose collection is a thin wrapper around a [MongoDB Node.js driver collection]([MongoDB Node.js driver collection](https://mongodb.github.io/node-mongodb-native/Next/classes/Collection.html)).
@@ -1048,11 +1103,7 @@ Model.init = function init() {
     return results;
   };
   const _createCollection = async() => {
-    if ((conn.readyState === STATES.connecting || conn.readyState === STATES.disconnected) && conn._shouldBufferCommands()) {
-      await new Promise(resolve => {
-        conn._queue.push({ fn: resolve });
-      });
-    }
+    await conn._waitForConnect();
     const autoCreate = utils.getOption(
       'autoCreate',
       this.schema.options,
@@ -1246,19 +1297,21 @@ Model.syncIndexes = async function syncIndexes(options) {
     throw new MongooseError('Model.syncIndexes() no longer accepts a callback');
   }
 
-  const model = this;
+  const autoCreate = options?.autoCreate ?? this.schema.options?.autoCreate ?? this.db.config.autoCreate ?? true;
 
-  try {
-    await model.createCollection();
-  } catch (err) {
-    if (err != null && (err.name !== 'MongoServerError' || err.code !== 48)) {
-      throw err;
+  if (autoCreate) {
+    try {
+      await this.createCollection();
+    } catch (err) {
+      if (err != null && (err.name !== 'MongoServerError' || err.code !== 48)) {
+        throw err;
+      }
     }
   }
 
-  const diffIndexesResult = await model.diffIndexes();
-  const dropped = await model.cleanIndexes({ ...options, toDrop: diffIndexesResult.toDrop });
-  await model.createIndexes({ ...options, toCreate: diffIndexesResult.toCreate });
+  const diffIndexesResult = await this.diffIndexes({ indexOptionsToCreate: true });
+  const dropped = await this.cleanIndexes({ ...options, toDrop: diffIndexesResult.toDrop });
+  await this.createIndexes({ ...options, toCreate: diffIndexesResult.toCreate });
 
   return dropped;
 };
@@ -1361,13 +1414,14 @@ Model.listSearchIndexes = async function listSearchIndexes(options) {
  *
  *     const { toDrop, toCreate } = await Model.diffIndexes();
  *     toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
- *     toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create
+ *     toCreate; // Array of index specs containing the keys of indexes that `syncIndexes()` will create
  *
  * @param {Object} [options]
+ * @param {Boolean} [options.indexOptionsToCreate=false] If true, `toCreate` will include both the index spec and the index options, not just the index spec
  * @return {Promise<Object>} contains the indexes that would be dropped in MongoDB and indexes that would be created in MongoDB as `{ toDrop: string[], toCreate: string[] }`.
  */
 
-Model.diffIndexes = async function diffIndexes() {
+Model.diffIndexes = async function diffIndexes(options) {
   if (typeof arguments[0] === 'function' || typeof arguments[1] === 'function') {
     throw new MongooseError('Model.syncIndexes() no longer accepts a callback');
   }
@@ -1389,13 +1443,14 @@ Model.diffIndexes = async function diffIndexes() {
   const schemaIndexes = getRelatedSchemaIndexes(model, schema.indexes());
 
   const toDrop = getIndexesToDrop(schema, schemaIndexes, dbIndexes);
-  const toCreate = getIndexesToCreate(schema, schemaIndexes, dbIndexes, toDrop);
+  const toCreate = getIndexesToCreate(schema, schemaIndexes, dbIndexes, toDrop, options);
 
   return { toDrop, toCreate };
 };
 
-function getIndexesToCreate(schema, schemaIndexes, dbIndexes, toDrop) {
+function getIndexesToCreate(schema, schemaIndexes, dbIndexes, toDrop, options) {
   const toCreate = [];
+  const indexOptionsToCreate = options?.indexOptionsToCreate ?? false;
 
   for (const [schemaIndexKeysObject, schemaIndexOptions] of schemaIndexes) {
     let found = false;
@@ -1416,7 +1471,11 @@ function getIndexesToCreate(schema, schemaIndexes, dbIndexes, toDrop) {
     }
 
     if (!found) {
-      toCreate.push(schemaIndexKeysObject);
+      if (indexOptionsToCreate) {
+        toCreate.push([schemaIndexKeysObject, schemaIndexOptions]);
+      } else {
+        toCreate.push(schemaIndexKeysObject);
+      }
     }
   }
 
@@ -1465,7 +1524,7 @@ function getIndexesToDrop(schema, schemaIndexes, dbIndexes) {
  * @param {Object} [options]
  * @param {Array<String>} [options.toDrop] if specified, contains a list of index names to drop
  * @param {Boolean} [options.hideIndexes=false] set to `true` to hide indexes instead of dropping. Requires MongoDB server 4.4 or higher
- * @return {Promise<String>} list of dropped or hidden index names
+ * @return {Promise<Array<String>>} list of dropped or hidden index names
  * @api public
  */
 
@@ -1597,7 +1656,7 @@ Model.createIndexes = async function createIndexes(options) {
  */
 
 function _ensureIndexes(model, options, callback) {
-  const indexes = model.schema.indexes();
+  const indexes = Array.isArray(options?.toCreate) ? options.toCreate : model.schema.indexes();
   let indexError;
 
   options = options || {};
@@ -1681,12 +1740,6 @@ function _ensureIndexes(model, options, callback) {
       indexOptions.background = options.background;
     }
 
-    if ('toCreate' in options) {
-      if (options.toCreate.length === 0) {
-        return done();
-      }
-    }
-
     // Just in case `createIndex()` throws a sync error
     let promise = null;
     try {
@@ -2115,9 +2168,8 @@ Model.estimatedDocumentCount = function estimatedDocumentCount(options) {
  *
  * #### Example:
  *
- *     Adventure.countDocuments({ type: 'jungle' }, function (err, count) {
- *       console.log('there are %d jungle adventures', count);
- *     });
+ *     const count = await Adventure.countDocuments({ type: 'jungle' });
+ *     console.log('there are %d jungle adventures', count);
  *
  * If you want to count all documents in a large collection,
  * use the [`estimatedDocumentCount()` function](https://mongoosejs.com/docs/api/model.html#Model.estimatedDocumentCount())
@@ -2627,6 +2679,10 @@ Model.create = async function create(doc, options) {
 
   delete options.aggregateErrors; // dont pass on the option to "$save"
 
+  if (options.session && !options.ordered && args.length > 1) {
+    throw new MongooseError('Cannot call `create()` with a session and multiple documents unless `ordered: true` is set');
+  }
+
   if (options.ordered) {
     for (let i = 0; i < args.length; i++) {
       try {
@@ -2713,6 +2769,49 @@ Model.create = async function create(doc, options) {
   return res;
 };
 
+/**
+ * Shortcut for saving one document to the database.
+ * `MyModel.insertOne(obj, options)` is almost equivalent to `new MyModel(obj).save(options)`.
+ * The difference is that `insertOne()` checks if `obj` is already a document, and checks for discriminators.
+ *
+ * This function triggers the following middleware.
+ *
+ * - `save()`
+ *
+ * #### Example:
+ *
+ *     // Insert one new `Character` document
+ *     const character = await Character.insertOne({ name: 'Jean-Luc Picard' });
+ *     character.name; // 'Jean-Luc Picard'
+ *
+ *     // Create a new character within a transaction.
+ *     await Character.insertOne({ name: 'Jean-Luc Picard' }, { session });
+ *
+ * @param {Object|Document} doc Document to insert, as a POJO or Mongoose document
+ * @param {Object} [options] Options passed down to `save()`.
+ * @return {Promise<Document>} resolves to the saved document
+ * @api public
+ */
+
+Model.insertOne = async function insertOne(doc, options) {
+  _checkContext(this, 'insertOne');
+
+  const discriminatorKey = this.schema.options.discriminatorKey;
+  const Model = this.discriminators && doc[discriminatorKey] != null ?
+    this.discriminators[doc[discriminatorKey]] || getDiscriminatorByValue(this.discriminators, doc[discriminatorKey]) :
+    this;
+  if (Model == null) {
+    throw new MongooseError(
+      `Discriminator "${doc[discriminatorKey]}" not found for model "${this.modelName}"`
+    );
+  }
+  if (!(doc instanceof Model)) {
+    doc = new Model(doc);
+  }
+
+  return await doc.$save(options);
+};
+
 /**
  * _Requires a replica set running MongoDB >= 3.6.0._ Watches the
  * underlying collection for changes using
@@ -3878,6 +3977,10 @@ Model.hydrate = function(obj, projection, options) {
  *     res.upsertedId; // null or an id containing a document that had to be upserted.
  *     res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.
  *
+ *     // Other supported syntaxes
+ *     await Person.find({ name: /Stark$/ }).updateMany({ isDeleted: true }); // Using chaining syntax
+ *     await Person.find().updateMany({ isDeleted: true }); // Set `isDeleted` on _all_ Person documents
+ *
  * This function triggers the following middleware.
  *
  * - `updateMany()`
@@ -3898,10 +4001,14 @@ Model.hydrate = function(obj, projection, options) {
  * @api public
  */
 
-Model.updateMany = function updateMany(conditions, doc, options) {
+Model.updateMany = function updateMany(conditions, update, options) {
   _checkContext(this, 'updateMany');
 
-  return _update(this, 'updateMany', conditions, doc, options);
+  if (update == null) {
+    throw new MongooseError('updateMany `update` parameter cannot be nullish');
+  }
+
+  return _update(this, 'updateMany', conditions, update, options);
 };
 
 /**
@@ -3918,6 +4025,10 @@ Model.updateMany = function updateMany(conditions, doc, options) {
  *     res.upsertedId; // null or an id containing a document that had to be upserted.
  *     res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.
  *
+ *     // Other supported syntaxes
+ *     await Person.findOne({ name: 'Jean-Luc Picard' }).updateOne({ ship: 'USS Enterprise' }); // Using chaining syntax
+ *     await Person.updateOne({ ship: 'USS Enterprise' }); // Updates first doc's `ship` property
+ *
  * This function triggers the following middleware.
  *
  * - `updateOne()`

package/lib/query.js

@@ -3992,6 +3992,10 @@ Query.prototype._replaceOne = async function _replaceOne() {
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
  *
+ *     // Other supported syntaxes
+ *     await Person.find({ name: /Stark$/ }).updateMany({ isDeleted: true }); // Using chaining syntax
+ *     await Person.find().updateMany({ isDeleted: true }); // Set `isDeleted` on _all_ Person documents
+ *
  * This function triggers the following middleware.
  *
  * - `updateMany()`
@@ -4062,6 +4066,10 @@ Query.prototype.updateMany = function(conditions, doc, options, callback) {
  *     res.upsertedCount; // Number of documents that were upserted
  *     res.upsertedId; // Identifier of the inserted document (if an upsert took place)
  *
+ *     // Other supported syntaxes
+ *     await Person.findOne({ name: 'Jean-Luc Picard' }).updateOne({ ship: 'USS Enterprise' }); // Using chaining syntax
+ *     await Person.updateOne({ ship: 'USS Enterprise' }); // Updates first doc's `ship` property
+ *
  * This function triggers the following middleware.
  *
  * - `updateOne()`