mongoose 6.5.2 → 6.5.5

package/lib/model.js

@@ -119,11 +119,12 @@ function Model(doc, fields, skipId) {
   Document.call(this, doc, fields, skipId);
 }
 
-/*!
+/**
  * Inherits from Document.
  *
  * All Model.prototype features are available on
  * top level (non-sub) documents.
+ * @api private
  */
 
 Model.prototype.__proto__ = Document.prototype;
@@ -222,7 +223,7 @@ Model.prototype.baseModelName;
 
 Model.events;
 
-/*!
+/**
  * Compiled middleware for this model. Set in `applyHooks()`.
  *
  * @api private
@@ -538,12 +539,13 @@ Model.prototype.save = function(options, fn) {
 
 Model.prototype.$save = Model.prototype.save;
 
-/*!
+/**
  * Determines whether versioning should be skipped for the given path
  *
  * @param {Document} self
  * @param {String} path
  * @return {Boolean} true if versioning should be skipped for the given path
+ * @api private
  */
 function shouldSkipVersioning(self, path) {
   const skipVersioning = self.$__schema.options.skipVersioning;
@@ -555,16 +557,17 @@ function shouldSkipVersioning(self, path) {
   return skipVersioning[path];
 }
 
-/*!
+/**
  * Apply the operation to the delta (update) clause as
  * well as track versioning for our where clause.
  *
  * @param {Document} self
- * @param {Object} where
+ * @param {Object} where Unused
  * @param {Object} delta
  * @param {Object} data
  * @param {Mixed} val
- * @param {String} [operation]
+ * @param {String} [op]
+ * @api private
  */
 
 function operand(self, where, delta, data, val, op) {
@@ -623,7 +626,7 @@ function operand(self, where, delta, data, val, op) {
   }
 }
 
-/*!
+/**
  * Compiles an update and where clause for a `val` with _atomics.
  *
  * @param {Document} self
@@ -631,6 +634,7 @@ function operand(self, where, delta, data, val, op) {
  * @param {Object} delta
  * @param {Object} data
  * @param {Array} value
+ * @api private
  */
 
 function handleAtomics(self, where, delta, data, value) {
@@ -797,14 +801,16 @@ Model.prototype.$__delta = function() {
   return [where, delta];
 };
 
-/*!
+/**
  * Determine if array was populated with some form of filter and is now
  * being updated in a manner which could overwrite data unintentionally.
  *
  * @see https://github.com/Automattic/mongoose/issues/1334
  * @param {Document} doc
  * @param {String} path
+ * @param {Any} array
  * @return {String|undefined}
+ * @api private
  */
 
 function checkDivergentArray(doc, path, array) {
@@ -990,8 +996,14 @@ Model.prototype.remove = function remove(options, fn) {
   }, this.constructor.events);
 };
 
-/*!
+/**
  * Alias for remove
+ *
+ * @method $remove
+ * @memberOf Model
+ * @instance
+ * @api public
+ * @see Model.remove #model_Model-remove
  */
 
 Model.prototype.$remove = Model.prototype.remove;
@@ -1240,8 +1252,9 @@ Model.discriminator = function(name, schema, options) {
   return d;
 };
 
-/*!
+/**
  * Make sure `this` is a model
+ * @api private
  */
 
 function _checkContext(ctx, fnName) {
@@ -1375,7 +1388,7 @@ Model.init = function init(callback) {
  *     });
  *
  * @api public
- * @param {Object} [options] see [MongoDB driver docs](https://mongodb.github.io/node-mongodb-native/3.1/api/Db.html#createCollection)
+ * @param {Object} [options] see [MongoDB driver docs](https://mongodb.github.io/node-mongodb-native/4.9/classes/Db.html#createCollection)
  * @param {Function} [callback]
  * @returns {Promise}
  */
@@ -1469,26 +1482,32 @@ Model.createCollection = function createCollection(options, callback) {
 Model.syncIndexes = function syncIndexes(options, callback) {
   _checkContext(this, 'syncIndexes');
 
-  callback = this.$handleCallbackError(callback);
-
-  return this.db.base._promiseOrCallback(callback, cb => {
-    cb = this.$wrapCallback(cb);
+  const model = this;
+  callback = model.$handleCallbackError(callback);
 
-    this.createCollection(err => {
+  return model.db.base._promiseOrCallback(callback, cb => {
+    cb = model.$wrapCallback(cb);
+    model.createCollection(err => {
       if (err != null && (err.name !== 'MongoServerError' || err.code !== 48)) {
         return cb(err);
       }
-      this.cleanIndexes((err, dropped) => {
+      model.diffIndexes(err, (err, diffIndexesResult) => {
         if (err != null) {
           return cb(err);
         }
-        this.createIndexes(options, err => {
+        model.cleanIndexes({ ...options, toDrop: diffIndexesResult.toDrop }, (err, dropped) => {
           if (err != null) {
             return cb(err);
           }
-          cb(null, dropped);
+          model.createIndexes({ ...options, toCreate: diffIndexesResult.toCreate }, err => {
+            if (err != null) {
+              return cb(err);
+            }
+            cb(null, dropped);
+          });
         });
       });
+
     });
   }, this.events);
 };
@@ -1509,63 +1528,83 @@ Model.diffIndexes = function diffIndexes(options, callback) {
     callback = options;
     options = null;
   }
-  const toDrop = [];
-  const toCreate = [];
-  callback = this.$handleCallbackError(callback);
-  return this.db.base._promiseOrCallback(callback, cb => {
-    cb = this.$wrapCallback(cb);
-    this.listIndexes((err, dbIndexes) => {
+
+  const model = this;
+
+  callback = model.$handleCallbackError(callback);
+
+  return model.db.base._promiseOrCallback(callback, cb => {
+    cb = model.$wrapCallback(cb);
+    model.listIndexes((err, dbIndexes) => {
       if (dbIndexes === undefined) {
         dbIndexes = [];
       }
-      dbIndexes = getRelatedDBIndexes(this, dbIndexes);
-      const schemaIndexes = getRelatedSchemaIndexes(this, this.schema.indexes());
+      dbIndexes = getRelatedDBIndexes(model, dbIndexes);
 
-      for (const dbIndex of dbIndexes) {
-        let found = false;
-        // Never try to drop `_id` index, MongoDB server doesn't allow it
-        if (isDefaultIdIndex(dbIndex)) {
-          continue;
-        }
-
-        for (const [schemaIndexKeysObject, schemaIndexOptions] of schemaIndexes) {
-          const options = decorateDiscriminatorIndexOptions(this.schema, utils.clone(schemaIndexOptions));
-          applySchemaCollation(schemaIndexKeysObject, options, this.schema.options);
+      const schema = model.schema;
+      const schemaIndexes = getRelatedSchemaIndexes(model, schema.indexes());
 
-          if (isIndexEqual(schemaIndexKeysObject, options, dbIndex)) {
-            found = true;
-          }
-        }
+      const toDrop = getIndexesToDrop(schema, schemaIndexes, dbIndexes);
+      const toCreate = getIndexesToCreate(schema, schemaIndexes, dbIndexes);
 
-        if (!found) {
-          toDrop.push(dbIndex.name);
-        }
-      }
-      // Iterate through the indexes created on the schema and
-      // compare against the indexes in mongodb.
-      if (!options || options.toCreate !== false) {
-        for (const schemaIndex of schemaIndexes) {
-          let found = false;
-          const key = schemaIndex[0];
-          const options = decorateDiscriminatorIndexOptions(this.schema, utils.clone(schemaIndex[1]));
-          for (const index of dbIndexes) {
-            if (isDefaultIdIndex(index)) {
-              continue;
-            }
-            if (isIndexEqual(key, options, index)) {
-              found = true;
-            }
-          }
-          if (!found) {
-            toCreate.push(key);
-          }
-        }
-      }
       cb(null, { toDrop, toCreate });
     });
   });
 };
 
+function getIndexesToCreate(schema, schemaIndexes, dbIndexes) {
+  const toCreate = [];
+
+  for (const [schemaIndexKeysObject, schemaIndexOptions] of schemaIndexes) {
+    let found = false;
+
+    const options = decorateDiscriminatorIndexOptions(schema, utils.clone(schemaIndexOptions));
+
+    for (const index of dbIndexes) {
+      if (isDefaultIdIndex(index)) {
+        continue;
+      }
+      if (isIndexEqual(schemaIndexKeysObject, options, index)) {
+        found = true;
+        break;
+      }
+    }
+
+    if (!found) {
+      toCreate.push(schemaIndexKeysObject);
+    }
+  }
+
+  return toCreate;
+}
+
+function getIndexesToDrop(schema, schemaIndexes, dbIndexes) {
+  const toDrop = [];
+
+  for (const dbIndex of dbIndexes) {
+    let found = false;
+    // Never try to drop `_id` index, MongoDB server doesn't allow it
+    if (isDefaultIdIndex(dbIndex)) {
+      continue;
+    }
+
+    for (const [schemaIndexKeysObject, schemaIndexOptions] of schemaIndexes) {
+      const options = decorateDiscriminatorIndexOptions(schema, utils.clone(schemaIndexOptions));
+      applySchemaCollation(schemaIndexKeysObject, options, schema.options);
+
+      if (isIndexEqual(schemaIndexKeysObject, options, dbIndex)) {
+        found = true;
+        break;
+      }
+    }
+
+    if (!found) {
+      toDrop.push(dbIndex.name);
+    }
+  }
+
+  return toDrop;
+}
 /**
  * Deletes all indexes that aren't defined in this model's schema. Used by
  * `syncIndexes()`.
@@ -1577,46 +1616,56 @@ Model.diffIndexes = function diffIndexes(options, callback) {
  * @api public
  */
 
-Model.cleanIndexes = function cleanIndexes(callback) {
+Model.cleanIndexes = function cleanIndexes(options, callback) {
   _checkContext(this, 'cleanIndexes');
+  const model = this;
 
-  callback = this.$handleCallbackError(callback);
+  if (typeof options === 'function') {
+    callback = options;
+    options = null;
+  }
 
-  return this.db.base._promiseOrCallback(callback, cb => {
-    const collection = this.$__collection;
+  callback = model.$handleCallbackError(callback);
 
-    this.diffIndexes({ toCreate: false }, (err, res) => {
+  return model.db.base._promiseOrCallback(callback, cb => {
+    const collection = model.$__collection;
+
+    if (Array.isArray(options && options.toDrop)) {
+      _dropIndexes(options.toDrop, collection, cb);
+      return;
+    }
+    return model.diffIndexes((err, res) => {
       if (err != null) {
         return cb(err);
       }
 
       const toDrop = res.toDrop;
-
-      if (toDrop.length === 0) {
-        return cb(null, []);
-      }
-
-      dropIndexes(toDrop, cb);
+      _dropIndexes(toDrop, collection, cb);
     });
 
-    function dropIndexes(toDrop, cb) {
-      let remaining = toDrop.length;
-      let error = false;
-      toDrop.forEach(indexName => {
-        collection.dropIndex(indexName, err => {
-          if (err != null) {
-            error = true;
-            return cb(err);
-          }
-          if (!error) {
-            --remaining || cb(null, toDrop);
-          }
-        });
-      });
-    }
   });
 };
 
+function _dropIndexes(toDrop, collection, cb) {
+  if (toDrop.length === 0) {
+    return cb(null, []);
+  }
+
+  let remaining = toDrop.length;
+  let error = false;
+  toDrop.forEach(indexName => {
+    collection.dropIndex(indexName, err => {
+      if (err != null) {
+        error = true;
+        return cb(err);
+      }
+      if (!error) {
+        --remaining || cb(null, toDrop);
+      }
+    });
+  });
+}
+
 /**
  * Lists the indexes currently defined in MongoDB. This may or may not be
  * the same as the indexes defined in your schema depending on whether you
@@ -1701,7 +1750,7 @@ Model.ensureIndexes = function ensureIndexes(options, callback) {
 };
 
 /**
- * Similar to `ensureIndexes()`, except for it uses the [`createIndex`](https://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#createIndex)
+ * Similar to `ensureIndexes()`, except for it uses the [`createIndex`](https://mongodb.github.io/node-mongodb-native/4.9/classes/Db.html#createIndex)
  * function.
  *
  * @param {Object} [options] internal options
@@ -1717,11 +1766,13 @@ Model.createIndexes = function createIndexes(options, callback) {
     callback = options;
     options = {};
   }
+  callback = this.$handleCallbackError(callback);
   options = options || {};
-  options.createIndex = true;
+
   return this.ensureIndexes(options, callback);
 };
 
+
 /*!
  * ignore
  */
@@ -1837,17 +1888,18 @@ function _ensureIndexes(model, options, callback) {
 
 Model.schema;
 
-/*!
+/**
  * Connection instance the model uses.
  *
  * @property db
+ * @static
  * @api public
  * @memberOf Model
  */
 
 Model.db;
 
-/*!
+/**
  * Collection the model uses.
  *
  * @property collection
@@ -2318,7 +2370,7 @@ Model.estimatedDocumentCount = function estimatedDocumentCount(options, callback
  * a full collection scan and **not** use any indexes.
  *
  * The `countDocuments()` function is similar to `count()`, but there are a
- * [few operators that `countDocuments()` does not support](https://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#countDocuments).
+ * [few operators that `countDocuments()` does not support](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#countDocuments).
  * Below are the operators that `count()` supports but `countDocuments()` does not,
  * and the suggested replacement:
  *
@@ -2536,7 +2588,7 @@ Model.$where = function $where() {
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
  * @param {Boolean} [options.runValidators] if true, runs [update validators](/docs/validation.html#update-validators) on this command. Update validators validate the update operation against the model's schema
  * @param {Boolean} [options.setDefaultsOnInsert=true] If `setDefaultsOnInsert` and `upsert` are true, mongoose will apply the [defaults](https://mongoosejs.com/docs/defaults.html) specified in the model's schema if a new document is created
- * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
+ * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html)
  * @param {Function} [callback]
  * @return {Query}
  * @see Tutorial /docs/tutorials/findoneandupdate.html
@@ -2583,8 +2635,9 @@ Model.findOneAndUpdate = function(conditions, update, options, callback) {
   return mq.findOneAndUpdate(conditions, update, options, callback);
 };
 
-/*!
+/**
  * Decorate the update with a version key, if necessary
+ * @api private
  */
 
 function _decorateUpdateWithVersionKey(update, options, versionKey) {
@@ -2662,7 +2715,7 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) {
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
  * @param {Boolean} [options.runValidators] if true, runs [update validators](/docs/validation.html#update-validators) on this command. Update validators validate the update operation against the model's schema
  * @param {Boolean} [options.setDefaultsOnInsert=true] If `setDefaultsOnInsert` and `upsert` are true, mongoose will apply the [defaults](https://mongoosejs.com/docs/defaults.html) specified in the model's schema if a new document is created
- * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
+ * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html)
  * @param {Boolean} [options.upsert=false] if true, and no documents found, insert a new document
  * @param {Boolean} [options.new=false] if true, return the modified document rather than the original
  * @param {Object|String} [options.select] sets the document fields to return.
@@ -2737,7 +2790,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](/docs/transactions.html).
- * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
+ * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html)
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
  * @param {Object|String} [options.select] sets the document fields to return.
  * @param {Number} [options.maxTimeMS] puts a time limit on the query - requires mongodb >= 2.6.0
@@ -2838,7 +2891,7 @@ Model.findByIdAndDelete = function(id, options, callback) {
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
- * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
+ * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html)
  * @param {Object|String} [options.select] sets the document fields to return.
  * @param {Number} [options.maxTimeMS] puts a time limit on the query - requires mongodb >= 2.6.0
  * @param {Function} [callback]
@@ -2918,7 +2971,7 @@ Model.findOneAndReplace = function(filter, replacement, options, callback) {
  * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
- * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
+ * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html)
  * @param {Object|String} [options.select] sets the document fields to return.
  * @param {Number} [options.maxTimeMS] puts a time limit on the query - requires mongodb >= 2.6.0
  * @param {Function} [callback]
@@ -2981,7 +3034,7 @@ Model.findOneAndRemove = function(conditions, options, callback) {
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](/docs/transactions.html).
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](#query_Query-select)
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
- * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
+ * @param {Boolean} [options.rawResult] if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html)
  * @param {Object|String} [options.select] sets the document fields to return.
  * @param {Function} [callback]
  * @return {Query}
@@ -3027,7 +3080,7 @@ Model.findByIdAndRemove = function(id, options, callback) {
  *     await Character.create([{ name: 'Jean-Luc Picard' }], { session });
  *
  * @param {Array|Object} docs Documents to insert, as a spread or array
- * @param {Object} [options] Options passed down to `save()`. To specify `options`, `docs` **must** be an array, not a spread.
+ * @param {Object} [options] Options passed down to `save()`. To specify `options`, `docs` **must** be an array, not a spread. See [Model.save](#model_Model-save) for available options.
  * @param {Function} [callback] callback
  * @return {Promise}
  * @api public
@@ -3176,7 +3229,7 @@ Model.create = function create(doc, options, callback) {
  *     await doc.remove();
  *
  * @param {Array} [pipeline]
- * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/3.0/api/Collection.html#watch)
+ * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#watch)
  * @param {Boolean} [options.hydrate=false] if true and `fullDocument: 'updateLookup'` is set, Mongoose will automatically hydrate `fullDocument` into a fully fledged Mongoose document
  * @return {ChangeStream} mongoose-specific change stream wrapper, inherits from EventEmitter
  * @api public
@@ -3228,7 +3281,7 @@ Model.watch = function(pipeline, options) {
  *     // secondary that is experiencing replication lag.
  *     doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });
  *
- * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/3.0/api/MongoClient.html#startSession)
+ * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/4.9/classes/MongoClient.html#startSession)
  * @param {Boolean} [options.causalConsistency=true] set to false to disable causal consistency
  * @param {Function} [callback]
  * @return {Promise<ClientSession>} promise that resolves to a MongoDB driver `ClientSession`
@@ -3264,9 +3317,9 @@ Model.startSession = function() {
  *     Movies.insertMany(arr, function(error, docs) {});
  *
  * @param {Array|Object|*} doc(s)
- * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#insertMany)
+ * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#insertMany)
  * @param {Boolean} [options.ordered=true] if true, will fail fast on the first error encountered. If false, will insert all the documents it can and report errors later. An `insertMany()` with `ordered = false` is called an "unordered" `insertMany()`.
- * @param {Boolean} [options.rawResult=false] if false, the returned promise resolves to the documents that passed mongoose document validation. If `true`, will return the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~insertWriteOpCallback) with a `mongoose` property that contains `validationErrors` if this is an unordered `insertMany`.
+ * @param {Boolean} [options.rawResult=false] if false, the returned promise resolves to the documents that passed mongoose document validation. If `true`, will return the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/InsertManyResult.html) with a `mongoose` property that contains `validationErrors` if this is an unordered `insertMany`.
  * @param {Boolean} [options.lean=false] if `true`, skips hydrating and validating the documents. This option is useful if you need the extra performance, but Mongoose won't validate the documents before inserting.
  * @param {Number} [options.limit=null] this limits the number of documents being processed (validation/casting) by mongoose in parallel, this does **NOT** send the documents in batches to MongoDB. Use this option if you're processing a large number of documents and your app is running out of memory.
  * @param {String|Object|Array} [options.populate=null] populates the result documents. This option is a no-op if `rawResult` is set.
@@ -3287,8 +3340,16 @@ Model.insertMany = function(arr, options, callback) {
   }, this.events);
 };
 
-/*!
+/**
  * ignore
+ *
+ * @param {Array} arr
+ * @param {Object} options
+ * @param {Function} callback
+ * @api private
+ * @memberOf Model
+ * @method $__insertMany
+ * @static
  */
 
 Model.$__insertMany = function(arr, options, callback) {
@@ -3520,23 +3581,23 @@ function _setIsNew(doc, val) {
  *
  * @param {Array} ops
  * @param {Object} [ops.insertOne.document] The document to insert
- * @param {Object} [opts.updateOne.filter] Update the first document that matches this filter
- * @param {Object} [opts.updateOne.update] An object containing [update operators](https://docs.mongodb.com/manual/reference/operator/update/)
- * @param {Boolean} [opts.updateOne.upsert=false] If true, insert a doc if none match
- * @param {Boolean} [opts.updateOne.timestamps=true] If false, do not apply [timestamps](https://mongoosejs.com/docs/guide.html#timestamps) to the operation
- * @param {Object} [opts.updateOne.collation] The [MongoDB collation](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations) to use
- * @param {Array} [opts.updateOne.arrayFilters] The [array filters](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-36-array-filters.html) used in `update`
- * @param {Object} [opts.updateMany.filter] Update all the documents that match this filter
- * @param {Object} [opts.updateMany.update] An object containing [update operators](https://docs.mongodb.com/manual/reference/operator/update/)
- * @param {Boolean} [opts.updateMany.upsert=false] If true, insert a doc if no documents match `filter`
- * @param {Boolean} [opts.updateMany.timestamps=true] If false, do not apply [timestamps](https://mongoosejs.com/docs/guide.html#timestamps) to the operation
- * @param {Object} [opts.updateMany.collation] The [MongoDB collation](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations) to use
- * @param {Array} [opts.updateMany.arrayFilters] The [array filters](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-36-array-filters.html) used in `update`
- * @param {Object} [opts.deleteOne.filter] Delete the first document that matches this filter
- * @param {Object} [opts.deleteMany.filter] Delete all documents that match this filter
- * @param {Object} [opts.replaceOne.filter] Replace the first document that matches this filter
- * @param {Object} [opts.replaceOne.replacement] The replacement document
- * @param {Boolean} [opts.replaceOne.upsert=false] If true, insert a doc if no documents match `filter`
+ * @param {Object} [ops.updateOne.filter] Update the first document that matches this filter
+ * @param {Object} [ops.updateOne.update] An object containing [update operators](https://docs.mongodb.com/manual/reference/operator/update/)
+ * @param {Boolean} [ops.updateOne.upsert=false] If true, insert a doc if none match
+ * @param {Boolean} [ops.updateOne.timestamps=true] If false, do not apply [timestamps](https://mongoosejs.com/docs/guide.html#timestamps) to the operation
+ * @param {Object} [ops.updateOne.collation] The [MongoDB collation](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations) to use
+ * @param {Array} [ops.updateOne.arrayFilters] The [array filters](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-36-array-filters.html) used in `update`
+ * @param {Object} [ops.updateMany.filter] Update all the documents that match this filter
+ * @param {Object} [ops.updateMany.update] An object containing [update operators](https://docs.mongodb.com/manual/reference/operator/update/)
+ * @param {Boolean} [ops.updateMany.upsert=false] If true, insert a doc if no documents match `filter`
+ * @param {Boolean} [ops.updateMany.timestamps=true] If false, do not apply [timestamps](https://mongoosejs.com/docs/guide.html#timestamps) to the operation
+ * @param {Object} [ops.updateMany.collation] The [MongoDB collation](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations) to use
+ * @param {Array} [ops.updateMany.arrayFilters] The [array filters](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-36-array-filters.html) used in `update`
+ * @param {Object} [ops.deleteOne.filter] Delete the first document that matches this filter
+ * @param {Object} [ops.deleteMany.filter] Delete all documents that match this filter
+ * @param {Object} [ops.replaceOne.filter] Replace the first document that matches this filter
+ * @param {Object} [ops.replaceOne.replacement] The replacement document
+ * @param {Boolean} [ops.replaceOne.upsert=false] If true, insert a doc if no documents match `filter`
  * @param {Object} [options]
  * @param {Boolean} [options.ordered=true] If true, execute writes in order and stop at the first error. If false, execute writes in parallel and continue until all writes have either succeeded or errored.
  * @param {ClientSession} [options.session=null] The session associated with this bulk write. See [transactions docs](/docs/transactions.html).
@@ -3547,7 +3608,7 @@ function _setIsNew(doc, val) {
  * @param {Boolean} [options.bypassDocumentValidation=false] If true, disable [MongoDB server-side schema validation](https://docs.mongodb.com/manual/core/schema-validation/) for all writes in this bulk.
  * @param {Boolean} [options.strict=null] Overwrites the [`strict` option](/docs/guide.html#strict) on schema. If false, allows filtering and writing fields not defined in the schema for all writes in this bulk.
  * @param {Function} [callback] callback `function(error, bulkWriteOpResult) {}`
- * @return {Promise} resolves to a [`BulkWriteOpResult`](https://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#~BulkWriteOpResult) if the operation succeeds
+ * @return {Promise} resolves to a [`BulkWriteOpResult`](https://mongodb.github.io/node-mongodb-native/4.9/classes/BulkWriteResult.html) if the operation succeeds
  * @api public
  */
 
@@ -3960,10 +4021,10 @@ Model.hydrate = function(obj, projection, options) {
  * @param {Boolean} [options.setDefaultsOnInsert=false] `true` by default. If `setDefaultsOnInsert` and `upsert` are true, mongoose will apply the [defaults](https://mongoosejs.com/docs/defaults.html) specified in the model's schema if a new document is created.
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Does nothing if schema-level timestamps are not set.
  * @param {Boolean} [options.overwrite=false] By default, if you don't include any [update operators](https://docs.mongodb.com/manual/reference/operator/update/) in `doc`, Mongoose will wrap `doc` in `$set` for you. This prevents you from accidentally overwriting the document. This option tells Mongoose to skip adding `$set`.
- * @param {Function} [callback] params are (error, [updateWriteOpResult](https://mongodb.github.io/node-mongodb-native/3.6/api/Collection.html#~updateWriteOpResult))
+ * @param {Function} [callback] params are (error, [updateWriteOpResult](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/UpdateResult.html))
  * @return {Query}
  * @see MongoDB docs https://docs.mongodb.com/manual/reference/command/update/#update-command-output
- * @see writeOpResult https://mongodb.github.io/node-mongodb-native/3.6/api/Collection.html#~updateWriteOpResult
+ * @see UpdateResult https://mongodb.github.io/node-mongodb-native/4.9/interfaces/UpdateResult.html
  * @see Query docs https://mongoosejs.com/docs/queries.html
  * @api public
  */
@@ -4006,7 +4067,7 @@ Model.update = function update(conditions, doc, options, callback) {
  * @return {Query}
  * @see Query docs https://mongoosejs.com/docs/queries.html
  * @see MongoDB docs https://docs.mongodb.com/manual/reference/command/update/#update-command-output
- * @see writeOpResult https://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~WriteOpResult
+ * @see UpdateResult https://mongodb.github.io/node-mongodb-native/4.9/interfaces/UpdateResult.html
  * @api public
  */
 
@@ -4047,7 +4108,7 @@ Model.updateMany = function updateMany(conditions, doc, options, callback) {
  * @return {Query}
  * @see Query docs https://mongoosejs.com/docs/queries.html
  * @see MongoDB docs https://docs.mongodb.com/manual/reference/command/update/#update-command-output
- * @see writeOpResult https://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~WriteOpResult
+ * @see UpdateResult https://mongodb.github.io/node-mongodb-native/4.9/interfaces/UpdateResult.html
  * @api public
  */
 
@@ -4084,7 +4145,7 @@ Model.updateOne = function updateOne(conditions, doc, options, callback) {
  * @param {Function} [callback] `function(error, res) {}` where `res` has 3 properties: `n`, `nModified`, `ok`.
  * @return {Query}
  * @see Query docs https://mongoosejs.com/docs/queries.html
- * @see writeOpResult https://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~WriteOpResult
+ * @see UpdateResult https://mongodb.github.io/node-mongodb-native/4.9/interfaces/UpdateResult.html
  * @return {Query}
  * @api public
  */
@@ -4100,9 +4161,10 @@ Model.replaceOne = function replaceOne(conditions, doc, options, callback) {
   return _update(this, 'replaceOne', conditions, doc, options, callback);
 };
 
-/*!
+/**
  * Common code for `updateOne()`, `updateMany()`, `replaceOne()`, and `update()`
  * because they need to do the same thing
+ * @api private
  */
 
 function _update(model, op, conditions, doc, options, callback) {
@@ -4129,7 +4191,7 @@ function _update(model, op, conditions, doc, options, callback) {
 /**
  * Executes a mapReduce command.
  *
- * `opts` is an object specifying all mapReduce options as well as the map and reduce functions. All options are delegated to the driver implementation. See [node-mongodb-native mapReduce() documentation](https://mongodb.github.io/node-mongodb-native/api-generated/collection.html#mapreduce) for more detail about options.
+ * `opts` is an object specifying all mapReduce options as well as the map and reduce functions. All options are delegated to the driver implementation. See [node-mongodb-native mapReduce() documentation](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#mapReduce) for more detail about options.
  *
  * This function does not trigger any middleware.
  *
@@ -4513,13 +4575,14 @@ Model.populate = function(docs, paths, callback) {
   }, this.events);
 };
 
-/*!
+/**
  * Populate helper
  *
  * @param {Model} model the model to use
  * @param {Document|Array} docs Either a single document or array of documents to populate.
  * @param {Object} paths
- * @param {Function} [cb(err,doc)] Optional callback, executed upon completion. Receives `err` and the `doc(s)`.
+ * @param {never} cache Unused
+ * @param {Function} [callback] Optional callback, executed upon completion. Receives `err` and the `doc(s)`.
  * @return {Function}
  * @api private
  */
@@ -4704,7 +4767,7 @@ function populate(model, docs, options, callback) {
  */
 
 function _execPopulateQuery(mod, match, select, assignmentOpts, callback) {
-  const subPopulate = utils.clone(mod.options.populate);
+  let subPopulate = utils.clone(mod.options.populate);
   const queryOptions = Object.assign({
     skip: mod.options.skip,
     limit: mod.options.limit,
@@ -4749,6 +4812,8 @@ function _execPopulateQuery(mod, match, select, assignmentOpts, callback) {
     if (mod.model.baseModelName != null) {
       if (Array.isArray(subPopulate)) {
         subPopulate.forEach(pop => { pop.strictPopulate = false; });
+      } else if (typeof subPopulate === 'string') {
+        subPopulate = { path: subPopulate, strictPopulate: false };
       } else {
         subPopulate.strictPopulate = false;
       }
@@ -4888,7 +4953,7 @@ function _assign(model, vals, mod, assignmentOpts) {
   });
 }
 
-/*!
+/**
  * Compiler utility.
  *
  * @param {String|Function} name model name or class extending Model
@@ -4896,6 +4961,7 @@ function _assign(model, vals, mod, assignmentOpts) {
  * @param {String} collectionName
  * @param {Connection} connection
  * @param {Mongoose} base mongoose instance
+ * @api private
  */
 
 Model.compile = function compile(name, schema, collectionName, connection, base) {
@@ -5004,11 +5070,12 @@ Model.compile = function compile(name, schema, collectionName, connection, base)
   return model;
 };
 
-/*!
+/**
  * Register custom query methods for this model
  *
  * @param {Model} model
  * @param {Schema} schema
+ * @api private
  */
 
 function applyQueryMethods(model, methods) {
@@ -5017,13 +5084,17 @@ function applyQueryMethods(model, methods) {
   }
 }
 
-/*!
+/**
  * Subclass this model with `conn`, `schema`, and `collection` settings.
  *
  * @param {Connection} conn
  * @param {Schema} [schema]
  * @param {String} [collection]
  * @return {Model}
+ * @api private
+ * @memberOf Model
+ * @static
+ * @method __subclass
  */
 
 Model.__subclass = function subclass(conn, schema, collection) {
@@ -5100,8 +5171,14 @@ Model.$handleCallbackError = function(callback) {
   };
 };
 
-/*!
+/**
  * ignore
+ *
+ * @param {Function} callback
+ * @api private
+ * @method $wrapCallback
+ * @memberOf Model
+ * @static
  */
 
 Model.$wrapCallback = function(callback) {
@@ -5138,10 +5215,7 @@ Model.inspect = function() {
 };
 
 if (util.inspect.custom) {
-  /*!
-  * Avoid Node deprecation warning DEP0079
-  */
-
+  // Avoid Node deprecation warning DEP0079
   Model[util.inspect.custom] = Model.inspect;
 }