mongoose 6.2.7 → 6.2.10

package/lib/model.js

@@ -82,7 +82,7 @@ const saveToObjectOptions = Object.assign({}, internalToObjectOptions, {
  * [`connection.model()`](./api.html#connection_Connection-model) functions
  * create subclasses of `mongoose.Model` as shown below.
  *
- * ####Example:
+ * #### Example:
  *
  *     // `UserModel` is a "Model", a subclass of `mongoose.Model`.
  *     const UserModel = mongoose.model('User', new Schema({ name: String }));
@@ -201,12 +201,12 @@ Model.prototype.baseModelName;
  * Event emitter that reports any errors that occurred. Useful for global error
  * handling.
  *
- * ####Example:
+ * #### Example:
  *
  *     MyModel.events.on('error', err => console.log(err.message));
  *
  *     // Prints a 'CastError' because of the above handler
- *     await MyModel.findOne({ _id: 'notanid' }).catch(noop);
+ *     await MyModel.findOne({ _id: 'Not a valid ObjectId' }).catch(noop);
  *
  * @api public
  * @fires error whenever any query or model function errors
@@ -245,8 +245,7 @@ function _applyCustomWhere(doc, where) {
  */
 
 Model.prototype.$__handleSave = function(options, callback) {
-  const _this = this;
-  let saveOptions = {};
+  const saveOptions = {};
 
   applyWriteConcern(this.$__schema, options);
   if (typeof options.writeConcern !== 'undefined') {
@@ -274,14 +273,10 @@ Model.prototype.$__handleSave = function(options, callback) {
   if ('checkKeys' in options) {
     saveOptions.checkKeys = options.checkKeys;
   }
-  const session = this.$session();
   if (!saveOptions.hasOwnProperty('session')) {
-    saveOptions.session = session;
+    saveOptions.session = this.$session();
   }
 
-  if (Object.keys(saveOptions).length === 0) {
-    saveOptions = null;
-  }
   if (this.$isNew) {
     // send entire doc
     const obj = this.toObject(saveToObjectOptions);
@@ -298,9 +293,9 @@ Model.prototype.$__handleSave = function(options, callback) {
     }
 
     this.$__version(true, obj);
-    this[modelCollectionSymbol].insertOne(obj, saveOptions, function(err, ret) {
+    this[modelCollectionSymbol].insertOne(obj, saveOptions, (err, ret) => {
       if (err) {
-        _setIsNew(_this, true);
+        _setIsNew(this, true);
 
         callback(err, null);
         return;
@@ -308,64 +303,68 @@ Model.prototype.$__handleSave = function(options, callback) {
 
       callback(null, ret);
     });
+
     this.$__reset();
     _setIsNew(this, false);
     // Make it possible to retry the insert
     this.$__.inserting = true;
-  } else {
-    // Make sure we don't treat it as a new object on error,
-    // since it already exists
-    this.$__.inserting = false;
-
-    const delta = this.$__delta();
-    if (delta) {
-      if (delta instanceof MongooseError) {
-        callback(delta);
-        return;
-      }
 
-      const where = this.$__where(delta[0]);
-      if (where instanceof MongooseError) {
-        callback(where);
-        return;
-      }
+    return;
+  }
 
-      _applyCustomWhere(this, where);
-      this[modelCollectionSymbol].updateOne(where, delta[1], saveOptions, (err, ret) => {
-        if (err) {
-          this.$__undoReset();
+  // Make sure we don't treat it as a new object on error,
+  // since it already exists
+  this.$__.inserting = false;
 
-          callback(err);
-          return;
-        }
-        ret.$where = where;
-        callback(null, ret);
-      });
-    } else {
-      const optionsWithCustomValues = Object.assign({}, options, saveOptions);
-      const where = this.$__where();
-      if (this.$__schema.options.optimisticConcurrency) {
-        const key = this.$__schema.options.versionKey;
-        const val = this.$__getValue(key);
-        if (val != null) {
-          where[key] = val;
-        }
-      }
-      this.constructor.exists(where, optionsWithCustomValues)
-        .then(documentExists => {
-          const matchedCount = !documentExists ? 0 : 1;
-          callback(null, { $where: where, matchedCount });
-        })
-        .catch(callback);
+  const delta = this.$__delta();
+  if (delta) {
+    if (delta instanceof MongooseError) {
+      callback(delta);
       return;
     }
 
-    // store the modified paths before the document is reset
-    this.$__.modifiedPaths = this.modifiedPaths();
-    this.$__reset();
+    const where = this.$__where(delta[0]);
+    if (where instanceof MongooseError) {
+      callback(where);
+      return;
+    }
 
-    _setIsNew(this, false);
+    _applyCustomWhere(this, where);
+    this[modelCollectionSymbol].updateOne(where, delta[1], saveOptions, (err, ret) => {
+      if (err) {
+        this.$__undoReset();
+
+        callback(err);
+        return;
+      }
+      ret.$where = where;
+      callback(null, ret);
+    });
+  } else {
+    const optionsWithCustomValues = Object.assign({}, options, saveOptions);
+    const where = this.$__where();
+    const optimisticConcurrency = this.$__schema.options.optimisticConcurrency;
+    if (optimisticConcurrency) {
+      const key = this.$__schema.options.versionKey;
+      const val = this.$__getValue(key);
+      if (val != null) {
+        where[key] = val;
+      }
+    }
+    this.constructor.exists(where, optionsWithCustomValues)
+      .then(documentExists => {
+        const matchedCount = !documentExists ? 0 : 1;
+        callback(null, { $where: where, matchedCount });
+      })
+      .catch(callback);
+    return;
   }
+
+  // store the modified paths before the document is reset
+  this.$__.modifiedPaths = this.modifiedPaths();
+  this.$__reset();
+
+  _setIsNew(this, false);
 };
 
 /*!
@@ -374,8 +373,8 @@ Model.prototype.$__handleSave = function(options, callback) {
 
 Model.prototype.$__save = function(options, callback) {
   this.$__handleSave(options, (error, result) => {
-    const hooks = this.$__schema.s.hooks;
     if (error) {
+      const hooks = this.$__schema.s.hooks;
       return hooks.execPost('save:error', this, [this], { error: error }, (error) => {
         callback(error, this);
       });
@@ -399,7 +398,7 @@ Model.prototype.$__save = function(options, callback) {
         }
       }
 
-      const versionBump = this.$__.version || this.$__schema.options.optimisticConcurrency;
+      const versionBump = this.$__.version;
       // was this an update that required a version bump?
       if (versionBump && !this.$__.inserting) {
         const doIncrement = VERSION_INC === (VERSION_INC & this.$__.version);
@@ -423,6 +422,7 @@ Model.prototype.$__save = function(options, callback) {
         this.$__undoReset();
         error = new DocumentNotFoundError(result.$where,
           this.constructor.modelName, numAffected, result);
+        const hooks = this.$__schema.s.hooks;
         return hooks.execPost('save:error', this, [this], { error: error }, (error) => {
           callback(error, this);
         });
@@ -453,7 +453,7 @@ function generateVersionError(doc, modifiedPaths) {
  * Saves this document by inserting a new document into the database if [document.isNew](/docs/api.html#document_Document-isNew) is `true`,
  * or sends an [updateOne](/docs/api.html#document_Document-updateOne) operation with just the modified paths if `isNew` is `false`.
  *
- * ####Example:
+ * #### Example:
  *
  *     product.sold = Date.now();
  *     product = await product.save();
@@ -461,7 +461,7 @@ function generateVersionError(doc, modifiedPaths) {
  * If save is successful, the returned promise will fulfill with the document
  * saved.
  *
- * ####Example:
+ * #### Example:
  *
  *     const newProduct = await product.save();
  *     newProduct === product; // true
@@ -516,9 +516,9 @@ Model.prototype.save = function(options, fn) {
     this.$__.saveOptions = options;
 
     this.$__save(options, error => {
-      this.$__.saving = undefined;
-      delete this.$__.saveOptions;
-      delete this.$__.$versionError;
+      this.$__.saving = null;
+      this.$__.saveOptions = null;
+      this.$__.$versionError = null;
       this.$op = null;
 
       if (error) {
@@ -576,7 +576,6 @@ function operand(self, where, delta, data, val, op) {
   if (VERSION_ALL === (VERSION_ALL & self.$__.version)) return;
 
   if (self.$__schema.options.optimisticConcurrency) {
-    self.$__.version = VERSION_ALL;
     return;
   }
 
@@ -699,6 +698,12 @@ function handleAtomics(self, where, delta, data, value) {
 
 Model.prototype.$__delta = function() {
   const dirty = this.$__dirty();
+
+  const optimisticConcurrency = this.$__schema.options.optimisticConcurrency;
+  if (optimisticConcurrency) {
+    this.$__.version = dirty.length ? VERSION_ALL : VERSION_WHERE;
+  }
+
   if (!dirty.length && VERSION_ALL !== this.$__.version) {
     return;
   }
@@ -884,7 +889,7 @@ Model.prototype.$__version = function(where, delta) {
 /**
  * Signal that we desire an increment of this documents version.
  *
- * ####Example:
+ * #### Example:
  *
  *     Model.findById(id, function (err, doc) {
  *       doc.increment();
@@ -928,7 +933,7 @@ Model.prototype.$__where = function _where(where) {
 /**
  * Removes this document from the db.
  *
- * ####Example:
+ * #### Example:
  *     product.remove(function (err, product) {
  *       if (err) return handleError(err);
  *       Product.findById(product._id, function (err, product) {
@@ -939,7 +944,7 @@ Model.prototype.$__where = function _where(where) {
  *
  * As an extra measure of flow control, remove will return a Promise (bound to `fn` if passed) so it could be chained, or hooked to receive errors
  *
- * ####Example:
+ * #### Example:
  *     product.remove().then(function (product) {
  *        ...
  *     }).catch(function (err) {
@@ -986,7 +991,7 @@ Model.prototype.delete = Model.prototype.remove;
 /**
  * Removes this document from the db. Equivalent to `.remove()`.
  *
- * ####Example:
+ * #### Example:
  *     product = await product.deleteOne();
  *     await Product.findById(product._id); // null
  *
@@ -1055,7 +1060,7 @@ Model.prototype.$__deleteOne = Model.prototype.$__remove;
 /**
  * Returns another Model instance.
  *
- * ####Example:
+ * #### Example:
  *
  *     const doc = new Tank;
  *     doc.model('User').findById(id, callback);
@@ -1075,7 +1080,7 @@ Model.prototype.model = function model(name) {
  * Under the hood, `MyModel.exists({ answer: 42 })` is equivalent to
  * `MyModel.findOne({ answer: 42 }).select({ _id: 1 }).lean()`
  *
- * ####Example:
+ * #### Example:
  *     await Character.deleteMany({});
  *     await Character.create({ name: 'Jean-Luc Picard' });
  *
@@ -1114,7 +1119,7 @@ Model.exists = function exists(filter, options, callback) {
 /**
  * Adds a discriminator type.
  *
- * ####Example:
+ * #### Example:
  *
  *     function BaseSchema() {
  *       Schema.apply(this, arguments);
@@ -1243,7 +1248,7 @@ for (const i in EventEmitter.prototype) {
  * to get back a promise that will resolve when your indexes are finished
  * building as an alternative to [`MyModel.on('index')`](/docs/guide.html#indexes)
  *
- * ####Example:
+ * #### Example:
  *
  *     const eventSchema = new Schema({ thing: { type: 'string', unique: true }})
  *     // This calls `Event.init()` implicitly, so you don't need to call
@@ -1329,7 +1334,7 @@ Model.init = function init(callback) {
  * Note 2: You don't have to call this if your schema contains index or unique field.
  * In that case, just use `Model.init()`
  *
- * ####Example:
+ * #### Example:
  *
  *     const userSchema = new Schema({ name: String })
  *     const User = mongoose.model('User', userSchema);
@@ -1411,7 +1416,7 @@ Model.createCollection = function createCollection(options, callback) {
  * See the [introductory blog post](https://thecodebarbarian.com/whats-new-in-mongoose-5-2-syncindexes)
  * for more information.
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ name: { type: String, unique: true } });
  *     const Customer = mongoose.model('Customer', schema);
@@ -1629,7 +1634,7 @@ Model.listIndexes = function init(callback) {
  * Sends `createIndex` commands to mongo for each index declared in the schema.
  * The `createIndex` commands are sent in series.
  *
- * ####Example:
+ * #### Example:
  *
  *     Event.ensureIndexes(function (err) {
  *       if (err) return handleError(err);
@@ -1637,7 +1642,7 @@ Model.listIndexes = function init(callback) {
  *
  * After completion, an `index` event is emitted on this `Model` passing an error if one occurred.
  *
- * ####Example:
+ * #### Example:
  *
  *     const eventSchema = new Schema({ thing: { type: 'string', unique: true }})
  *     const Event = mongoose.model('Event', eventSchema);
@@ -1874,7 +1879,7 @@ Model.discriminators;
 /**
  * Translate any aliases fields/conditions so the final query or document object is pure
  *
- * ####Example:
+ * #### Example:
  *
  *     Character
  *       .find(Character.translateAliases({
@@ -1882,10 +1887,10 @@ Model.discriminators;
  *       })
  *       .exec(function(err, characters) {})
  *
- * ####Note:
+ * #### Note:
  * Only translate arguments of object type anything else is returned raw
  *
- * @param {Object} raw fields/conditions that may contain aliased keys
+ * @param {Object} fields fields/conditions that may contain aliased keys
  * @return {Object} the translated 'pure' fields/conditions
  */
 Model.translateAliases = function translateAliases(fields) {
@@ -1971,12 +1976,12 @@ Model.translateAliases = function translateAliases(fields) {
  *
  * This method is deprecated. See [Deprecation Warnings](../deprecations.html#remove) for details.
  *
- * ####Example:
+ * #### Example:
  *
  *     const res = await Character.remove({ name: 'Eddard Stark' });
  *     res.deletedCount; // Number of documents removed
  *
- * ####Note:
+ * #### Note:
  *
  * This method sends a remove command directly to MongoDB, no Mongoose documents
  * are involved. Because no Mongoose documents are involved, Mongoose does
@@ -2018,11 +2023,11 @@ Model.remove = function remove(conditions, options, callback) {
  * Behaves like `remove()`, but deletes at most one document regardless of the
  * `single` option.
  *
- * ####Example:
+ * #### Example:
  *
  *     await Character.deleteOne({ name: 'Eddard Stark' }); // returns {deletedCount: 1}
  *
- * ####Note:
+ * #### Note:
  *
  * This function triggers `deleteOne` query hooks. Read the
  * [middleware docs](/docs/middleware.html#naming) to learn more.
@@ -2061,11 +2066,11 @@ Model.deleteOne = function deleteOne(conditions, options, callback) {
  * Behaves like `remove()`, but deletes all documents that match `conditions`
  * regardless of the `single` option.
  *
- * ####Example:
+ * #### Example:
  *
  *     await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }); // returns {deletedCount: x} where x is the number of documents deleted.
  *
- * ####Note:
+ * #### Note:
  *
  * This function triggers `deleteMany` query hooks. Read the
  * [middleware docs](/docs/middleware.html#naming) to learn more.
@@ -2104,7 +2109,7 @@ Model.deleteMany = function deleteMany(conditions, options, callback) {
  * See our [query casting tutorial](/docs/tutorials/query_casting.html) for
  * more information on how Mongoose casts `filter`.
  *
- * ####Examples:
+ * #### Examples:
  *
  *     // find all documents
  *     await MyModel.find({});
@@ -2180,7 +2185,7 @@ Model.find = function find(conditions, projection, options, callback) {
  * to `findOne({})` and return arbitrary documents. However, mongoose
  * translates `findById(undefined)` into `findOne({ _id: null })`.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Find the adventure with the given `id`, or `null` if not found
  *     await Adventure.findById(id).exec();
@@ -2223,7 +2228,7 @@ Model.findById = function findById(id, projection, options, callback) {
  * mongoose will send an empty `findOne` command to MongoDB, which will return
  * an arbitrary document. If you're querying by `_id`, use `findById()` instead.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Find one adventure whose `country` is 'Croatia', otherwise `null`
  *     await Adventure.findOne({ country: 'Croatia' }).exec();
@@ -2279,7 +2284,7 @@ Model.findOne = function findOne(conditions, projection, options, callback) {
  * `estimatedDocumentCount()` uses collection metadata rather than scanning
  * the entire collection.
  *
- * ####Example:
+ * #### Example:
  *
  *     const numAdventures = await Adventure.estimatedDocumentCount();
  *
@@ -2302,7 +2307,7 @@ Model.estimatedDocumentCount = function estimatedDocumentCount(options, callback
 /**
  * Counts number of documents matching `filter` in a database collection.
  *
- * ####Example:
+ * #### Example:
  *
  *     Adventure.countDocuments({ type: 'jungle' }, function (err, count) {
  *       console.log('there are %d jungle adventures', count);
@@ -2357,7 +2362,7 @@ Model.countDocuments = function countDocuments(conditions, options, callback) {
  * a collection, e.g. `count({})`, use the [`estimatedDocumentCount()` function](/docs/api.html#model_Model.estimatedDocumentCount)
  * instead. Otherwise, use the [`countDocuments()`](/docs/api.html#model_Model.countDocuments) function instead.
  *
- * ####Example:
+ * #### Example:
  *
  *     const count = await Adventure.count({ type: 'jungle' });
  *     console.log('there are %d jungle adventures', count);
@@ -2389,7 +2394,7 @@ Model.count = function count(conditions, callback) {
  *
  * Passing a `callback` executes the query.
  *
- * ####Example
+ * #### Example
  *
  *     Link.distinct('url', { clicks: {$gt: 100}}, function (err, result) {
  *       if (err) return handleError(err);
@@ -2481,7 +2486,7 @@ Model.$where = function $where() {
  *
  * Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found document (if any) to the callback. The query executes if `callback` is passed else a Query object is returned.
  *
- * ####Options:
+ * #### Options:
  *
  * - `new`: bool - if true, return the modified document rather than the original. defaults to false (changed in 4.0)
  * - `upsert`: bool - creates the object if it doesn't exist. defaults to false.
@@ -2494,7 +2499,7 @@ Model.$where = function $where() {
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  * - `strict`: overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict) for this update
  *
- * ####Examples:
+ * #### Examples:
  *
  *     A.findOneAndUpdate(conditions, update, options, callback) // executes
  *     A.findOneAndUpdate(conditions, update, options)  // returns Query
@@ -2502,11 +2507,11 @@ Model.$where = function $where() {
  *     A.findOneAndUpdate(conditions, update)           // returns Query
  *     A.findOneAndUpdate()                             // returns Query
  *
- * ####Note:
+ * #### Note:
  *
  * All top level update keys which are not `atomic` operation names are treated as set operations:
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = { name: 'borne' };
  *     Model.findOneAndUpdate(query, { name: 'jason bourne' }, options, callback)
@@ -2516,7 +2521,7 @@ Model.$where = function $where() {
  *
  * This helps prevent accidentally overwriting your document with `{ name: 'jason bourne' }`.
  *
- * ####Note:
+ * #### Note:
  *
  * `findOneAndX` and `findByIdAndX` functions support limited validation that
  * you can enable by setting the `runValidators` option.
@@ -2619,7 +2624,7 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) {
  *
  * - `findOneAndUpdate()`
  *
- * ####Options:
+ * #### Options:
  *
  * - `new`: bool - true to return the modified document rather than the original. defaults to false
  * - `upsert`: bool - creates the object if it doesn't exist. defaults to false.
@@ -2630,7 +2635,7 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) {
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  * - `strict`: overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict) for this update
  *
- * ####Examples:
+ * #### Examples:
  *
  *     A.findByIdAndUpdate(id, update, options, callback) // executes
  *     A.findByIdAndUpdate(id, update, options)  // returns Query
@@ -2638,11 +2643,11 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) {
  *     A.findByIdAndUpdate(id, update)           // returns Query
  *     A.findByIdAndUpdate()                     // returns Query
  *
- * ####Note:
+ * #### Note:
  *
  * All top level update keys which are not `atomic` operation names are treated as set operations:
  *
- * ####Example:
+ * #### Example:
  *
  *     Model.findByIdAndUpdate(id, { name: 'jason bourne' }, options, callback)
  *
@@ -2651,7 +2656,7 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) {
  *
  * This helps prevent accidentally overwriting your document with `{ name: 'jason bourne' }`.
  *
- * ####Note:
+ * #### Note:
  *
  * `findOneAndX` and `findByIdAndX` functions support limited validation. You can
  * enable validation by setting the `runValidators` option.
@@ -2722,7 +2727,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  * this distinction is purely pedantic. You should use `findOneAndDelete()`
  * unless you have a good reason not to.
  *
- * ####Options:
+ * #### Options:
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
@@ -2731,7 +2736,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) {
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  * - `strict`: overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict) for this update
  *
- * ####Examples:
+ * #### Examples:
  *
  *     A.findOneAndDelete(conditions, options, callback) // executes
  *     A.findOneAndDelete(conditions, options)  // return Query
@@ -2835,7 +2840,7 @@ Model.findByIdAndDelete = function(id, options, callback) {
  *
  * - `findOneAndReplace()`
  *
- * ####Options:
+ * #### Options:
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
@@ -2844,7 +2849,7 @@ Model.findByIdAndDelete = function(id, options, callback) {
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  * - `strict`: overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict) for this update
  *
- * ####Examples:
+ * #### Examples:
  *
  *     A.findOneAndReplace(filter, replacement, options, callback) // executes
  *     A.findOneAndReplace(filter, replacement, options)  // return Query
@@ -2914,7 +2919,7 @@ Model.findOneAndReplace = function(filter, replacement, options, callback) {
  *
  * - `findOneAndRemove()`
  *
- * ####Options:
+ * #### Options:
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `maxTimeMS`: puts a time limit on the query - requires mongodb >= 2.6.0
@@ -2923,7 +2928,7 @@ Model.findOneAndReplace = function(filter, replacement, options, callback) {
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  * - `strict`: overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict) for this update
  *
- * ####Examples:
+ * #### Examples:
  *
  *     A.findOneAndRemove(conditions, options, callback) // executes
  *     A.findOneAndRemove(conditions, options)  // return Query
@@ -2994,14 +2999,14 @@ Model.findOneAndRemove = function(conditions, options, callback) {
  *
  * - `findOneAndRemove()`
  *
- * ####Options:
+ * #### Options:
  *
  * - `sort`: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
  * - `select`: sets the document fields to return
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  * - `strict`: overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict) for this update
  *
- * ####Examples:
+ * #### Examples:
  *
  *     A.findByIdAndRemove(id, options, callback) // executes
  *     A.findByIdAndRemove(id, options)  // return Query
@@ -3044,7 +3049,7 @@ Model.findByIdAndRemove = function(id, options, callback) {
  *
  * - `save()`
  *
- * ####Example:
+ * #### Example:
  *
  *     // Insert one new `Character` document
  *     await Character.create({ name: 'Jean-Luc Picard' });
@@ -3196,7 +3201,7 @@ Model.create = function create(doc, options, callback) {
  * - 'end': Emitted if the underlying stream is closed
  * - 'close': Emitted if the underlying stream is closed
  *
- * ####Example:
+ * #### Example:
  *
  *     const doc = await Person.create({ name: 'Ned Stark' });
  *     const changeStream = Person.watch().on('change', change => console.log(change));
@@ -3245,7 +3250,7 @@ Model.watch = function(pipeline, options) {
  *
  * This function does not trigger any middleware.
  *
- * ####Example:
+ * #### Example:
  *
  *     const session = await Person.startSession();
  *     let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
@@ -3286,7 +3291,7 @@ Model.startSession = function() {
  *
  * - `insertMany()`
  *
- * ####Example:
+ * #### Example:
  *
  *     const arr = [{ name: 'Star Wars' }, { name: 'The Empire Strikes Back' }];
  *     Movies.insertMany(arr, function(error, docs) {});
@@ -3506,7 +3511,7 @@ function _setIsNew(doc, val) {
  * If you need to trigger
  * `save()` middleware for every document use [`create()`](https://mongoosejs.com/docs/api.html#model_Model.create) instead.
  *
- * ####Example:
+ * #### Example:
  *
  *     Character.bulkWrite([
  *       {
@@ -3762,7 +3767,7 @@ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, op
  * Shortcut for creating a new Document from existing raw data, pre-saved in the DB.
  * The document returned has no paths marked as modified initially.
  *
- * ####Example:
+ * #### Example:
  *
  *     // hydrate previous data into a Mongoose document
  *     const mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });
@@ -3797,7 +3802,7 @@ Model.hydrate = function(obj, projection) {
  *
  * This method is deprecated. See [Deprecation Warnings](../deprecations.html#update) for details.
  *
- * ####Examples:
+ * #### Examples:
  *
  *     MyModel.update({ age: { $gt: 18 } }, { oldEnough: true }, fn);
  *
@@ -3807,7 +3812,7 @@ Model.hydrate = function(obj, projection) {
  *     // had `ferret` set to `true`, `nModified` will be 0.
  *     res.nModified;
  *
- * ####Valid options:
+ * #### Valid options:
  *
  *  - `strict` (boolean): overrides the [schema-level `strict` option](/docs/guide.html#strict) for this update
  *  - `upsert` (boolean): whether to create the doc if it doesn't match (false)
@@ -3825,11 +3830,11 @@ Model.hydrate = function(obj, projection) {
  * - `err` is the error if any occurred
  * - `rawResponse` is the full response from Mongo
  *
- * ####Note:
+ * #### Note:
  *
  * All top level keys which are not `atomic` operation names are treated as set operations:
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = { name: 'borne' };
  *     Model.update(query, { name: 'jason bourne' }, options, callback);
@@ -3840,7 +3845,7 @@ Model.hydrate = function(obj, projection) {
  *
  * This helps prevent accidentally overwriting all documents in your collection with `{ name: 'jason bourne' }`.
  *
- * ####Note:
+ * #### Note:
  *
  * Be careful to not use an existing model instance for the update clause (this won't work and can cause weird behavior like infinite loops). Also, ensure that the update clause does not have an _id property, which causes Mongo to return a "Mod on _id not allowed" error.
  *
@@ -3881,7 +3886,7 @@ Model.update = function update(conditions, doc, options, callback) {
  * **Note** updateMany will _not_ fire update middleware. Use `pre('updateMany')`
  * and `post('updateMany')` instead.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
  *     res.matchedCount; // Number of documents matched
  *     res.modifiedCount; // Number of documents modified
@@ -3921,7 +3926,7 @@ Model.updateMany = function updateMany(conditions, doc, options, callback) {
  * - MongoDB will update _only_ the first document that matches `filter` regardless of the value of the `multi` option.
  * - Use `replaceOne()` if you want to overwrite an entire document rather than using atomic operators like `$set`.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
  *     res.matchedCount; // Number of documents matched
  *     res.modifiedCount; // Number of documents modified
@@ -3958,7 +3963,7 @@ Model.updateOne = function updateOne(conditions, doc, options, callback) {
  * Same as `update()`, except MongoDB replace the existing document with the
  * given document (no atomic operators like `$set`).
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
  *     res.matchedCount; // Number of documents matched
  *     res.modifiedCount; // Number of documents modified
@@ -4029,7 +4034,7 @@ function _update(model, op, conditions, doc, options, callback) {
  *
  * This function does not trigger any middleware.
  *
- * ####Example:
+ * #### Example:
  *
  *     const o = {};
  *     // `map()` and `reduce()` are run on the MongoDB server, not Node.js,
@@ -4040,7 +4045,7 @@ function _update(model, op, conditions, doc, options, callback) {
  *       console.log(results)
  *     })
  *
- * ####Other options:
+ * #### Other options:
  *
  * - `query` {Object} query filter object.
  * - `sort` {Object} sort input objects using this key
@@ -4053,7 +4058,7 @@ function _update(model, op, conditions, doc, options, callback) {
  * - `readPreference` {String}
  * - `out*` {Object, default: {inline:1}} sets the output target for the map reduce job.
  *
- * ####* out options:
+ * #### * out options:
  *
  * - `{inline:1}` the results are returned in an array
  * - `{replace: 'collectionName'}` add the results to collectionName: the results replace the collection
@@ -4062,7 +4067,7 @@ function _update(model, op, conditions, doc, options, callback) {
  *
  * If `options.out` is set to `replace`, `merge`, or `reduce`, a Model instance is returned that can be used for further querying. Queries run against this model are all executed with the [`lean` option](/docs/tutorials/lean.html); meaning only the js object is returned and no Mongoose magic is applied (getters, setters, etc).
  *
- * ####Example:
+ * #### Example:
  *
  *     const o = {};
  *     // You can also define `map()` and `reduce()` as strings if your
@@ -4155,7 +4160,7 @@ Model.mapReduce = function mapReduce(o, callback) {
  *
  * - `aggregate()`
  *
- * ####Example:
+ * #### Example:
  *
  *     // Find the max balance of all accounts
  *     const res = await Users.aggregate([
@@ -4172,7 +4177,7 @@ Model.mapReduce = function mapReduce(o, callback) {
  *       exec();
  *     console.log(res); // [ { maxBalance: 98 } ]
  *
- * ####NOTE:
+ * #### Note:
  *
  * - Mongoose does **not** cast aggregation pipelines to the model's schema because `$project` and `$group` operators allow redefining the "shape" of the documents at any stage of the pipeline, which may leave documents in an incompatible format. You can use the [mongoose-cast-aggregation plugin](https://github.com/AbdelrahmanHafez/mongoose-cast-aggregation) to enable minimal casting for aggregation pipelines.
  * - The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
@@ -4234,7 +4239,7 @@ Model.aggregate = function aggregate(pipeline, options, callback) {
  * Casts and validates the given object against this model's schema, passing the
  * given `context` to custom validators.
  *
- * ####Example:
+ * #### Example:
  *
  *     const Model = mongoose.model('Test', Schema({
  *       name: { type: String, required: true },
@@ -4368,7 +4373,7 @@ Model.validate = function validate(obj, pathsToValidate, context, callback) {
  * Changed in Mongoose 6: the model you call `populate()` on should be the
  * "local field" model, **not** the "foreign field" model.
  *
- * ####Available top-level options:
+ * #### Available top-level options:
  *
  * - path: space delimited path(s) to populate
  * - select: optional fields to select
@@ -4378,7 +4383,7 @@ Model.validate = function validate(obj, pathsToValidate, context, callback) {
  * - justOne: optional boolean, if true Mongoose will always set `path` to an array. Inferred from schema by default.
  * - strictPopulate: optional boolean, set to `false` to allow populating paths that aren't in the schema.
  *
- * ####Examples:
+ * #### Examples:
  *
  *     const Dog = mongoose.model('Dog', new Schema({ name: String, breed: String }));
  *     const Person = mongoose.model('Person', new Schema({
@@ -5028,7 +5033,7 @@ Model.$wrapCallback = function(callback) {
  * Helper for console.log. Given a model named 'MyModel', returns the string
  * `'Model { MyModel }'`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const MyModel = mongoose.model('Test', Schema({ name: String }));
  *     MyModel.inspect(); // 'Model { Test }'