mongoose 6.2.7 → 6.2.10

package/lib/query.js

@@ -39,12 +39,37 @@ const utils = require('./utils');
 const validOps = require('./helpers/query/validOps');
 const wrapThunk = require('./helpers/query/wrapThunk');
 
+const queryOptionMethods = new Set([
+  'allowDiskUse',
+  'batchSize',
+  'collation',
+  'comment',
+  'explain',
+  'hint',
+  'j',
+  'lean',
+  'limit',
+  'maxScan',
+  'maxTimeMS',
+  'maxscan',
+  'projection',
+  'read',
+  'select',
+  'skip',
+  'slice',
+  'sort',
+  'tailable',
+  'w',
+  'writeConcern',
+  'wtimeout'
+]);
+
 /**
  * Query constructor used for building queries. You do not need
  * to instantiate a `Query` directly. Instead use Model functions like
  * [`Model.find()`](/docs/api.html#find_find).
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = MyModel.find(); // `query` is an instance of `Query`
  *     query.setOptions({ lean : true });
@@ -129,7 +154,9 @@ Query.base = mquery.prototype;
 /**
  * Flag to opt out of using `$geoWithin`.
  *
- *     mongoose.Query.use$geoWithin = false;
+ * ```javascript
+ * mongoose.Query.use$geoWithin = false;
+ * ```
  *
  * MongoDB 2.4 deprecated the use of `$within`, replacing it with `$geoWithin`. Mongoose uses `$geoWithin` by default (which is 100% backward compatible with `$within`). If you are running an older version of MongoDB, set this flag to `false` so your `within()` queries continue to work.
  *
@@ -146,7 +173,7 @@ Query.use$geoWithin = mquery.use$geoWithin;
 /**
  * Converts this query to a customized, reusable query constructor with all arguments and options retained.
  *
- * ####Example
+ * #### Example
  *
  *     // Create a query for adventure movies and read from the primary
  *     // node in the replica-set unless it is down, in which case we'll
@@ -228,7 +255,7 @@ Query.prototype.toConstructor = function toConstructor() {
 /**
  * Make a copy of this query so you can re-execute it.
  *
- * ####Example:
+ * #### Example:
  *     const q = Book.findOne({ title: 'Casino Royale' });
  *     await q.exec();
  *     await q.exec(); // Throws an error because you can't execute a query twice
@@ -276,7 +303,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a javascript function or expression to pass to MongoDBs query system.
  *
- * ####Example
+ * #### Example
  *
  *     query.$where('this.comments.length === 10 || this.name.length === 5')
  *
@@ -286,7 +313,7 @@ Query.prototype.clone = function clone() {
  *       return this.comments.length === 10 || this.name.length === 5;
  *     })
  *
- * ####NOTE:
+ * #### Note:
  *
  * Only use `$where` when you have a condition that cannot be met using other MongoDB operators like `$lt`.
  * **Be sure to read about all of [its caveats](https://docs.mongodb.org/manual/reference/operator/where/) before using.**
@@ -304,7 +331,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a `path` for use with chaining.
  *
- * ####Example
+ * #### Example
  *
  *     // instead of writing:
  *     User.find({age: {$gte: 21, $lte: 65}}, callback);
@@ -334,13 +361,13 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a `$slice` projection for an array.
  *
- * ####Example
+ * #### Example
  *
- *     query.slice('comments', 5)
- *     query.slice('comments', -5)
- *     query.slice('comments', [10, 5])
- *     query.where('comments').slice(5)
- *     query.where('comments').slice([-10, 5])
+ *     query.slice('comments', 5);
+ *     query.slice('comments', -5);
+ *     query.slice('comments', [10, 5]);
+ *     query.where('comments').slice(5);
+ *     query.where('comments').slice([-10, 5]);
  *
  * @method slice
  * @memberOf Query
@@ -412,7 +439,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies the complementary comparison value for paths specified with `where()`
  *
- * ####Example
+ * #### Example
  *
  *     User.where('age').equals(49);
  *
@@ -431,9 +458,9 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for an `$or` condition.
  *
- * ####Example
+ * #### Example
  *
- *     query.or([{ color: 'red' }, { status: 'emergency' }])
+ *     query.or([{ color: 'red' }, { status: 'emergency' }]);
  *
  * @see $or https://docs.mongodb.org/manual/reference/operator/or/
  * @method or
@@ -447,9 +474,9 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for a `$nor` condition.
  *
- * ####Example
+ * #### Example
  *
- *     query.nor([{ color: 'green' }, { status: 'ok' }])
+ *     query.nor([{ color: 'green' }, { status: 'ok' }]);
  *
  * @see $nor https://docs.mongodb.org/manual/reference/operator/nor/
  * @method nor
@@ -463,7 +490,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for a `$and` condition.
  *
- * ####Example
+ * #### Example
  *
  *     query.and([{ color: 'green' }, { status: 'ok' }])
  *
@@ -481,12 +508,12 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * ####Example
+ * #### Example
  *
- *     Thing.find().where('age').gt(21)
+ *     Thing.find().where('age').gt(21);
  *
  *     // or
- *     Thing.find().gt('age', 21)
+ *     Thing.find().gt('age', 21);
  *
  * @method gt
  * @memberOf Query
@@ -586,7 +613,7 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * ####Example:
+ * #### Example:
  *
  *     MyModel.find().where('pets').all(['dog', 'cat', 'ferret']);
  *     // Equivalent:
@@ -606,7 +633,7 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * ####Example
+ * #### Example
  *
  *     const docs = await MyModel.where('tags').size(0).exec();
  *     assert(Array.isArray(docs));
@@ -653,7 +680,7 @@ Query.prototype._validateOp = function() {
  * Specifies a `$mod` condition, filters documents for documents whose
  * `path` property is a number that is equal to `remainder` modulo `divisor`.
  *
- * ####Example
+ * #### Example
  *
  *     // All find products whose inventory is odd
  *     Product.find().mod('inventory', [2, 1]);
@@ -699,7 +726,7 @@ Query.prototype.mod = function() {
 /**
  * Specifies an `$exists` condition
  *
- * ####Example
+ * #### Example
  *
  *     // { name: { $exists: true }}
  *     Thing.where('name').exists()
@@ -723,7 +750,7 @@ Query.prototype.mod = function() {
 /**
  * Specifies an `$elemMatch` condition
  *
- * ####Example
+ * #### Example
  *
  *     query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})
  *
@@ -752,7 +779,7 @@ Query.prototype.mod = function() {
 /**
  * Defines a `$within` or `$geoWithin` argument for geo-spatial queries.
  *
- * ####Example
+ * #### Example
  *
  *     query.where(path).within().box()
  *     query.where(path).within().circle()
@@ -768,11 +795,11 @@ Query.prototype.mod = function() {
  *
  * **MUST** be used after `where()`.
  *
- * ####NOTE:
+ * #### Note:
  *
  * As of Mongoose 3.7, `$geoWithin` is always used for queries. To change this behavior, see [Query.use$geoWithin](#query_Query-use%2524geoWithin).
  *
- * ####NOTE:
+ * #### Note:
  *
  * In Mongoose 3.7, `within` changed from a getter to a function. If you need the old syntax, use [this](https://github.com/ebensing/mongoose-within).
  *
@@ -791,11 +818,11 @@ Query.prototype.mod = function() {
 /**
  * Specifies the maximum number of documents the query will return.
  *
- * ####Example
+ * #### Example
  *
- *     query.limit(20)
+ *     query.limit(20);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -824,11 +851,11 @@ Query.prototype.limit = function limit(v) {
 /**
  * Specifies the number of documents to skip.
  *
- * ####Example
+ * #### Example
  *
- *     query.skip(100).limit(20)
+ *     query.skip(100).limit(20);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -858,11 +885,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the maxScan option.
  *
- * ####Example
+ * #### Example
  *
- *     query.maxScan(100)
+ *     query.maxScan(100);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -877,11 +904,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the batchSize option.
  *
- * ####Example
+ * #### Example
  *
  *     query.batchSize(100)
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -896,11 +923,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the `comment` option.
  *
- * ####Example
+ * #### Example
  *
  *     query.comment('login query')
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -915,13 +942,13 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies this query as a `snapshot` query.
  *
- * ####Example
+ * #### Example
  *
- *     query.snapshot() // true
- *     query.snapshot(true)
- *     query.snapshot(false)
+ *     query.snapshot(); // true
+ *     query.snapshot(true);
+ *     query.snapshot(false);
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -936,11 +963,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Sets query hints.
  *
- * ####Example
+ * #### Example
  *
- *     query.hint({ indexA: 1, indexB: -1})
+ *     query.hint({ indexA: 1, indexB: -1 });
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -960,7 +987,7 @@ Query.prototype.skip = function skip(v) {
  * Unlike `projection()`, the `select()` function modifies the current
  * projection in place. This function overwrites the existing projection.
  *
- * ####Example:
+ * #### Example:
  *
  *     const q = Model.find();
  *     q.projection(); // null
@@ -1003,7 +1030,7 @@ Query.prototype.projection = function(arg) {
  * either list the fields to include (which excludes all others), or list the fields
  * to exclude (which implies all other fields are included). The [`_id` field is the only exception because MongoDB includes it by default](https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/#suppress-id-field).
  *
- * ####Example
+ * #### Example
  *
  *     // include a and b, exclude other fields
  *     query.select('a b');
@@ -1114,49 +1141,30 @@ Query.prototype.select = function select() {
   throw new TypeError('Invalid select() argument. Must be string or object.');
 };
 
-/**
- * _DEPRECATED_ Sets the slaveOk option.
- *
- * **Deprecated** in MongoDB 2.2 in favor of [read preferences](#query_Query-read).
- *
- * ####Example:
- *
- *     query.slaveOk() // true
- *     query.slaveOk(true)
- *     query.slaveOk(false)
- *
- * @method slaveOk
- * @memberOf Query
- * @instance
- * @deprecated use read() preferences instead if on mongodb >= 2.2
- * @param {Boolean} v defaults to true
- * @see mongodb https://docs.mongodb.org/manual/applications/replication/#read-preference
- * @see slaveOk https://docs.mongodb.org/manual/reference/method/rs.slaveOk/
- * @see read() #query_Query-read
- * @return {Query} this
- * @api public
- */
-
 /**
  * Determines the MongoDB nodes from which to read.
  *
- * ####Preferences:
+ * #### Preferences:
  *
- *     primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
- *     secondary            Read from secondary if available, otherwise error.
- *     primaryPreferred     Read from primary if available, otherwise a secondary.
- *     secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
- *     nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.
+ * ```
+ * primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
+ * secondary            Read from secondary if available, otherwise error.
+ * primaryPreferred     Read from primary if available, otherwise a secondary.
+ * secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
+ * nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.
+ * ```
  *
  * Aliases
  *
- *     p   primary
- *     pp  primaryPreferred
- *     s   secondary
- *     sp  secondaryPreferred
- *     n   nearest
+ * ```
+ * p   primary
+ * pp  primaryPreferred
+ * s   secondary
+ * sp  secondaryPreferred
+ * n   nearest
+ * ```
  *
- * ####Example:
+ * #### Example:
  *
  *     new Query().read('primary')
  *     new Query().read('p')  // same as primary
@@ -1235,7 +1243,7 @@ Query.prototype.toString = function toString() {
  *
  * Calling `session(null)` removes the session from this query.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = await mongoose.startSession();
  *     await mongoose.model('Person').findOne({ name: 'Axl Rose' }).session(s);
@@ -1279,7 +1287,7 @@ Query.prototype.session = function session(v) {
  *
  * Defaults to the schema's [`writeConcern` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     // The 'majority' option means the `deleteOne()` promise won't resolve
  *     // until the `deleteOne()` has propagated to the majority of the replica set
@@ -1322,7 +1330,7 @@ Query.prototype.writeConcern = function writeConcern(val) {
  *
  * Defaults to the schema's [`writeConcern.w` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     // The 'majority' option means the `deleteOne()` promise won't resolve
  *     // until the `deleteOne()` has propagated to the majority of the replica set
@@ -1368,7 +1376,7 @@ Query.prototype.w = function w(val) {
  *
  * Defaults to the schema's [`writeConcern.j` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     await mongoose.model('Person').deleteOne({ name: 'Ned Stark' }).j(true);
  *
@@ -1412,7 +1420,7 @@ Query.prototype.j = function j(val) {
  *
  * Defaults to the schema's [`writeConcern.wtimeout` option](/docs/guide.html#writeConcern)
  *
- * ####Example:
+ * #### Example:
  *
  *     // The `deleteOne()` promise won't resolve until this `deleteOne()` has
  *     // propagated to at least `w = 2` members of the replica set. If it takes
@@ -1446,7 +1454,7 @@ Query.prototype.wtimeout = function wtimeout(ms) {
 /**
  * Sets the readConcern option for the query.
  *
- * ####Example:
+ * #### Example:
  *
  *     new Query().readConcern('local')
  *     new Query().readConcern('l')  // same as local
@@ -1464,21 +1472,25 @@ Query.prototype.wtimeout = function wtimeout(ms) {
  *     new Query().readConcern('s')  // same as snapshot
  *
  *
- * ####Read Concern Level:
+ * #### Read Concern Level:
  *
- *     local         MongoDB 3.2+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
- *     available     MongoDB 3.6+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
- *     majority      MongoDB 3.2+ The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
- *     linearizable  MongoDB 3.4+ The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results.
- *     snapshot      MongoDB 4.0+ Only available for operations within multi-document transactions. Upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.
+ * ```
+ * local         MongoDB 3.2+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
+ * available     MongoDB 3.6+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
+ * majority      MongoDB 3.2+ The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
+ * linearizable  MongoDB 3.4+ The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results.
+ * snapshot      MongoDB 4.0+ Only available for operations within multi-document transactions. Upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.
+ * ```
  *
  * Aliases
  *
- *     l   local
- *     a   available
- *     m   majority
- *     lz  linearizable
- *     s   snapshot
+ * ```
+ * l   local
+ * a   available
+ * m   majority
+ * lz  linearizable
+ * s   snapshot
+ * ```
  *
  * Read more about how to use read concern [here](https://docs.mongodb.com/manual/reference/read-concern/).
  *
@@ -1493,11 +1505,11 @@ Query.prototype.wtimeout = function wtimeout(ms) {
 /**
  * Gets query options.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.limit(10);
- *     query.setOptions({ maxTimeMS: 1000 })
+ *     query.setOptions({ maxTimeMS: 1000 });
  *     query.getOptions(); // { limit: 10, maxTimeMS: 1000 }
  *
  * @return {Object} the options
@@ -1511,7 +1523,7 @@ Query.prototype.getOptions = function() {
 /**
  * Sets query options. Some options only make sense for certain operations.
  *
- * ####Options:
+ * #### Options:
  *
  * The following options are only for `find()`:
  *
@@ -1630,7 +1642,19 @@ Query.prototype.setOptions = function(options, overwrite) {
     }
   }
 
-  return Query.base.setOptions.call(this, options);
+  // set arbitrary options
+  for (const key of Object.keys(options)) {
+    if (queryOptionMethods.has(key)) {
+      const args = Array.isArray(options[key]) ?
+        options[key] :
+        [options[key]];
+      this[key].apply(this, args);
+    } else {
+      this.options[key] = options[key];
+    }
+  }
+
+  return this;
 };
 
 /**
@@ -1641,7 +1665,7 @@ Query.prototype.setOptions = function(options, overwrite) {
  *
  * Calling `query.explain(v)` is equivalent to `query.setOptions({ explain: v })`
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     const res = await query.find({ a: 1 }).explain('queryPlanner');
@@ -1673,7 +1697,7 @@ Query.prototype.explain = function(verbose) {
  *
  * Calling `query.allowDiskUse(v)` is equivalent to `query.setOptions({ allowDiskUse: v })`
  *
- * ####Example:
+ * #### Example:
  *
  *     await query.find().sort({ name: 1 }).allowDiskUse(true);
  *     // Equivalent:
@@ -1702,7 +1726,7 @@ Query.prototype.allowDiskUse = function(v) {
  *
  * Calling `query.maxTimeMS(v)` is equivalent to `query.setOptions({ maxTimeMS: v })`
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     // Throws an error 'operation exceeded time limit' as long as there's
@@ -1722,7 +1746,7 @@ Query.prototype.maxTimeMS = function(ms) {
 /**
  * Returns the current query filter (also known as conditions) as a [POJO](https://masteringjs.io/tutorials/fundamentals/pojo).
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.find({ a: 1 }).where('b').gt(2);
@@ -1742,7 +1766,7 @@ Query.prototype.getFilter = function() {
  * You should use `getFilter()` instead of `getQuery()` where possible. `getQuery()`
  * will likely be deprecated in a future release.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.find({ a: 1 }).where('b').gt(2);
@@ -1759,7 +1783,7 @@ Query.prototype.getQuery = function() {
 /**
  * Sets the query conditions to the provided JSON object.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.find({ a: 1 })
@@ -1778,7 +1802,7 @@ Query.prototype.setQuery = function(val) {
 /**
  * Returns the current update operations as a JSON object.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.update({}, { $set: { a: 5 } });
@@ -1795,7 +1819,7 @@ Query.prototype.getUpdate = function() {
 /**
  * Sets the current update operation to new value.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = new Query();
  *     query.update({}, { $set: { a: 5 } });
@@ -1948,7 +1972,7 @@ Query.prototype._optionsForExec = function(model) {
  * javascript objects, not [Mongoose Documents](/api/document.html). They have no
  * `save` method, getters/setters, virtuals, or other Mongoose features.
  *
- * ####Example:
+ * #### Example:
  *
  *     new Query().lean() // true
  *     new Query().lean(true)
@@ -1983,7 +2007,7 @@ Query.prototype.lean = function(v) {
  * This is useful for query middleware so you can add an update regardless
  * of whether you use `updateOne()`, `updateMany()`, `findOneAndUpdate()`, etc.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Updates `{ $set: { updatedAt: new Date() } }`
  *     new Query().updateOne({}, {}).set('updatedAt', new Date());
@@ -2015,7 +2039,7 @@ Query.prototype.set = function(path, val) {
  * Useful for writing getters/setters that can work with both update operations
  * and `save()`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const query = Model.updateOne({}, { $set: { name: 'Jean-Luc Picard' } });
  *     query.get('name'); // 'Jean-Luc Picard'
@@ -2049,7 +2073,7 @@ Query.prototype.get = function get(path) {
  * Gets/sets the error flag on this query. If this flag is not null or
  * undefined, the `exec()` promise will reject without executing.
  *
- * ####Example:
+ * #### Example:
  *
  *     Query().error(); // Get current error value
  *     Query().error(null); // Unset the current error
@@ -2063,7 +2087,7 @@ Query.prototype.get = function get(path) {
  * Note that query casting runs **after** hooks, so cast errors will override
  * custom errors.
  *
- * ####Example:
+ * #### Example:
  *     const TestSchema = new Schema({ num: Number });
  *     const TestModel = db.model('Test', TestSchema);
  *     TestModel.find({ num: 'not a number' }).error(new Error('woops')).exec(function(error) {
@@ -2250,7 +2274,7 @@ Query.prototype._find = wrapThunk(function(callback) {
  * If there are too many documents in the result to fit in memory, use
  * [`Query.prototype.cursor()`](api.html#query_Query-cursor)
  *
- * ####Example
+ * #### Example
  *
  *     // Using async/await
  *     const arr = await Movie.find({ year: { $gte: 1980, $lte: 1989 } });
@@ -2456,7 +2480,7 @@ Query.prototype._findOne = wrapThunk(function(callback) {
  *
  * - `findOne()`
  *
- * ####Example
+ * #### Example
  *
  *     const query  = Kitten.where({ color: 'white' });
  *     query.findOne(function (err, kitten) {
@@ -2607,7 +2631,7 @@ Query.prototype._estimatedDocumentCount = wrapThunk(function(callback) {
  *
  * - `count()`
  *
- * ####Example:
+ * #### Example:
  *
  *     const countQuery = model.where({ 'color': 'black' }).count();
  *
@@ -2664,7 +2688,7 @@ Query.prototype.count = function(filter, callback) {
  *
  * - `estimatedDocumentCount()`
  *
- * ####Example:
+ * #### Example:
  *
  *     await Model.find().estimatedDocumentCount();
  *
@@ -2710,7 +2734,7 @@ Query.prototype.estimatedDocumentCount = function(options, callback) {
  *
  * - `countDocuments()`
  *
- * ####Example:
+ * #### Example:
  *
  *     const countQuery = model.where({ 'color': 'black' }).countDocuments();
  *
@@ -2804,7 +2828,7 @@ Query.prototype.__distinct = wrapThunk(function __distinct(callback) {
  *
  * This function does not trigger any middleware.
  *
- * ####Example
+ * #### Example
  *
  *     distinct(field, conditions, callback)
  *     distinct(field, conditions)
@@ -2865,7 +2889,7 @@ Query.prototype.distinct = function(field, conditions, callback) {
  * sort order of each path is ascending unless the path name is prefixed with `-`
  * which will be treated as descending.
  *
- * ####Example
+ * #### Example
  *
  *     // sort by "field" ascending and "test" descending
  *     query.sort({ field: 'asc', test: -1 });
@@ -2873,7 +2897,7 @@ Query.prototype.distinct = function(field, conditions, callback) {
  *     // equivalent
  *     query.sort('field -test');
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -2898,7 +2922,7 @@ Query.prototype.sort = function(arg) {
  *
  * This function does not trigger any middleware
  *
- * ####Example
+ * #### Example
  *
  *     Character.remove({ name: /Stark/ }, callback);
  *
@@ -2910,13 +2934,13 @@ Query.prototype.sort = function(arg) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * ####Example
+ * #### Example
  *
  *     const res = await Character.remove({ name: /Stark/ });
  *     // Number of docs deleted
  *     res.deletedCount;
  *
- * ####Note
+ * #### Note
  *
  * Calling `remove()` creates a [Mongoose query](./queries.html), and a query
  * does not execute until you either pass a callback, call [`Query#then()`](#query_Query-then),
@@ -2990,7 +3014,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
  *
  * This function triggers `deleteOne` middleware.
  *
- * ####Example
+ * #### Example
  *
  *     await Character.deleteOne({ name: 'Eddard Stark' });
  *
@@ -3005,7 +3029,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * ####Example
+ * #### Example
  *
  *     const res = await Character.deleteOne({ name: 'Eddard Stark' });
  *     // `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }`
@@ -3076,7 +3100,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  *
  * This function triggers `deleteMany` middleware.
  *
- * ####Example
+ * #### Example
  *
  *     await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
  *
@@ -3091,7 +3115,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * ####Example
+ * #### Example
  *
  *     const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
  *     // `0` if no docs matched the filter, number of docs deleted otherwise
@@ -3226,7 +3250,7 @@ function prepareDiscriminatorCriteria(query) {
  *
  * - `findOneAndUpdate()`
  *
- * ####Available options
+ * #### Available 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.
@@ -3237,13 +3261,13 @@ function prepareDiscriminatorCriteria(query) {
  * - `setDefaultsOnInsert`: `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.
  * - `rawResult`: if true, returns the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     query.findOneAndUpdate(conditions, update, options, callback) // executes
  *     query.findOneAndUpdate(conditions, update, options)  // returns Query
@@ -3373,19 +3397,19 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) {
  *
  * - `findOneAndRemove()`
  *
- * ####Available options
+ * #### Available 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
  * - `rawResult`: if true, resolves to the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     A.where().findOneAndRemove(conditions, options, callback) // executes
  *     A.where().findOneAndRemove(conditions, options)  // return Query
@@ -3460,19 +3484,19 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) {
  * this distinction is purely pedantic. You should use `findOneAndDelete()`
  * unless you have a good reason not to.
  *
- * ####Available options
+ * #### Available 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
  * - `rawResult`: if true, resolves to the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     A.where().findOneAndDelete(conditions, options, callback) // executes
  *     A.where().findOneAndDelete(conditions, options)  // return Query
@@ -3579,19 +3603,19 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) {
  *
  * - `findOneAndReplace()`
  *
- * ####Available options
+ * #### Available 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
  * - `rawResult`: if true, resolves to the [raw result from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.3/interfaces/ModifyResult.html)
  *
- * ####Callback Signature
+ * #### Callback Signature
  *     function(error, doc) {
  *       // error: any errors that occurred
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * ####Examples
+ * #### Examples
  *
  *     A.where().findOneAndReplace(filter, replacement, options, callback); // executes
  *     A.where().findOneAndReplace(filter, replacement, options); // return Query
@@ -4156,15 +4180,15 @@ Query.prototype._replaceOne = wrapThunk(function(callback) {
  *
  * - `update()`
  *
- * ####Example
+ * #### Example
  *
- *     Model.where({ _id: id }).update({ title: 'words' })
+ *     Model.where({ _id: id }).update({ title: 'words' });
  *
  *     // becomes
  *
- *     Model.where({ _id: id }).update({ $set: { title: 'words' }})
+ *     Model.where({ _id: id }).update({ $set: { title: 'words' }});
  *
- * ####Valid options:
+ * #### Valid options:
  *
  *  - `upsert` (boolean) whether to create the doc if it doesn't match (false)
  *  - `multi` (boolean) whether multiple documents should be updated (false)
@@ -4174,47 +4198,51 @@ Query.prototype._replaceOne = wrapThunk(function(callback) {
  *  - `read`
  *  - `writeConcern`
  *
- * ####Note
+ * #### Note
  *
  * Passing an empty object `{}` as the doc will result in a no-op. The update operation will be ignored and the callback executed without sending the command to MongoDB.
  *
- * ####Note
+ * #### Note
  *
  * The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the `exec()` method.
  *
- *     const q = Model.where({ _id: id });
- *     q.update({ $set: { name: 'bob' }}).update(); // not executed
+ * ```javascript
+ * const q = Model.where({ _id: id });
+ * q.update({ $set: { name: 'bob' }}).update(); // not executed
  *
- *     q.update({ $set: { name: 'bob' }}).exec(); // executed
+ * q.update({ $set: { name: 'bob' }}).exec(); // executed
  *
- *     // keys that are not [atomic](https://docs.mongodb.com/manual/tutorial/model-data-for-atomic-operations/#pattern) ops become `$set`.
- *     // this executes the same command as the previous example.
- *     q.update({ name: 'bob' }).exec();
+ * // keys that are not [atomic](https://docs.mongodb.com/manual/tutorial/model-data-for-atomic-operations/#pattern) ops become `$set`.
+ * // this executes the same command as the previous example.
+ * q.update({ name: 'bob' }).exec();
  *
- *     // multi updates
- *     Model.where()
- *          .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)
+ * // multi updates
+ * Model.where()
+ *      .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)
  *
- *     // more multi updates
- *     Model.where()
- *          .setOptions({ multi: true })
- *          .update({ $set: { arr: [] }}, callback)
+ * // more multi updates
+ * Model.where()
+ *      .setOptions({ multi: true })
+ *      .update({ $set: { arr: [] }}, callback)
  *
- *     // single update by default
- *     Model.where({ email: 'address@example.com' })
- *          .update({ $inc: { counter: 1 }}, callback)
+ * // single update by default
+ * Model.where({ email: 'address@example.com' })
+ *      .update({ $inc: { counter: 1 }}, callback)
+ * ```
  *
  * API summary
  *
- *     update(filter, doc, options, cb) // executes
- *     update(filter, doc, options)
- *     update(filter, doc, cb) // executes
- *     update(filter, doc)
- *     update(doc, cb) // executes
- *     update(doc)
- *     update(cb) // executes
- *     update(true) // executes
- *     update()
+ * ```javascript
+ * update(filter, doc, options, cb); // executes
+ * update(filter, doc, options);
+ * update(filter, doc, cb); // executes
+ * update(filter, doc);
+ * update(doc, cb); // executes
+ * update(doc);
+ * update(cb); // executes
+ * update(true); // executes
+ * update();
+ * ```
  *
  * @param {Object} [filter]
  * @param {Object} [doc] the update command
@@ -4271,7 +4299,7 @@ Query.prototype.update = function(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.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4336,7 +4364,7 @@ Query.prototype.updateMany = function(conditions, doc, options, callback) {
  * **Note** updateOne will _not_ fire update middleware. Use `pre('updateOne')`
  * and `post('updateOne')` instead.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4399,7 +4427,7 @@ Query.prototype.updateOne = function(conditions, doc, options, callback) {
  * **Note** replaceOne will _not_ fire update middleware. Use `pre('replaceOne')`
  * and `post('replaceOne')` instead.
  *
- * ####Example:
+ * #### Example:
  *     const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
  *     res.n; // Number of documents matched
  *     res.nModified; // Number of documents modified
@@ -4503,7 +4531,7 @@ function _update(query, op, filter, doc, options, callback) {
  *
  * Any functions you pass to `transform()` will run **after** any post hooks.
  *
- * ####Example:
+ * #### Example:
  *
  *     const res = await MyModel.findOne().transform(res => {
  *       // Sets a `loadedAt` property on the doc that tells you the time the
@@ -4530,7 +4558,7 @@ Query.prototype.transform = function(fn) {
  * This is handy for integrating with async/await, because `orFail()` saves you
  * an extra `if` statement to check if no document was found.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Throws if no doc returned
  *     await Model.findOne({ foo: 'bar' }).orFail();
@@ -4620,7 +4648,7 @@ function _orFailError(err, query) {
 /**
  * Executes the query
  *
- * ####Examples:
+ * #### Examples:
  *
  *     const promise = query.exec();
  *     const promise = query.exec('update');
@@ -4760,7 +4788,7 @@ Query.prototype.catch = function(reject) {
  * Add pre [middleware](/docs/middleware.html) to this query instance. Doesn't affect
  * other queries.
  *
- * ####Example:
+ * #### Example:
  *
  *     const q1 = Question.find({ answer: 42 });
  *     q1.pre(function middleware() {
@@ -4786,7 +4814,7 @@ Query.prototype.pre = function(fn) {
  * Add post [middleware](/docs/middleware.html) to this query instance. Doesn't affect
  * other queries.
  *
- * ####Example:
+ * #### Example:
  *
  *     const q1 = Question.find({ answer: 42 });
  *     q1.post(function middleware() {
@@ -4885,7 +4913,7 @@ function castDoc(query, overwrite) {
 /**
  * Specifies paths which should be populated with other documents.
  *
- * ####Example:
+ * #### Example:
  *
  *     let book = await Book.findOne().populate('authors');
  *     book.title; // 'Node.js in Action'
@@ -4992,14 +5020,14 @@ Query.prototype.populate = function() {
 /**
  * Gets a list of paths to be populated by this query
  *
- * ####Example:
+ * #### Example:
  *      bookSchema.pre('findOne', function() {
  *        let keys = this.getPopulatedPaths(); // ['author']
  *      });
  *      ...
  *      Book.findOne({}).populate('author');
  *
- * ####Example:
+ * #### Example:
  *      // Deep populate
  *      const q = L1.find().populate({
  *        path: 'level2',
@@ -5041,7 +5069,7 @@ function _getPopulatedPaths(list, arr, prefix) {
 /**
  * Casts this query to the schema of `model`
  *
- * ####Note
+ * #### Note
  *
  * If `obj` is present, it is cast instead of this query.
  *
@@ -5166,7 +5194,7 @@ Query.prototype._applyPaths = function applyPaths() {
  *
  * The `.cursor()` function triggers pre find hooks, but **not** post find hooks.
  *
- * ####Example
+ * #### Example
  *
  *     // There are 2 ways to use a cursor. First, as a stream:
  *     Thing.
@@ -5190,7 +5218,7 @@ Query.prototype._applyPaths = function applyPaths() {
  *       console.log(doc);
  *     }
  *
- * ####Valid options
+ * #### Valid options
  *
  *   - `transform`: optional function which accepts a mongoose document. The return value of the function will be emitted on `data` and returned by `.next()`.
  *
@@ -5237,7 +5265,7 @@ Query.prototype.maxscan = Query.base.maxScan;
 /**
  * Sets the tailable option (for use with capped collections).
  *
- * ####Example
+ * #### Example
  *
  *     query.tailable(); // true
  *     query.tailable(true);
@@ -5246,7 +5274,7 @@ Query.prototype.maxscan = Query.base.maxScan;
  *     // Set both `tailable` and `awaitData` options
  *     query.tailable({ awaitData: true });
  *
- * ####Note
+ * #### Note
  *
  * Cannot be used with `distinct()`
  *
@@ -5287,23 +5315,23 @@ Query.prototype.tailable = function(val, opts) {
 /**
  * Declares an intersects query for `geometry()`.
  *
- * ####Example
+ * #### Example
  *
  *     query.where('path').intersects().geometry({
- *         type: 'LineString'
- *       , coordinates: [[180.0, 11.0], [180, 9.0]]
- *     })
+ *       type: 'LineString',
+ *       coordinates: [[180.0, 11.0], [180, 9.0]]
+ *     });
  *
  *     query.where('path').intersects({
- *         type: 'LineString'
- *       , coordinates: [[180.0, 11.0], [180, 9.0]]
- *     })
+ *       type: 'LineString',
+ *       coordinates: [[180.0, 11.0], [180, 9.0]]
+ *     });
  *
- * ####NOTE:
+ * #### Note:
  *
  * **MUST** be used after `where()`.
  *
- * ####NOTE:
+ * #### Note:
  *
  * In Mongoose 3.7, `intersects` changed from a getter to a function. If you need the old syntax, use [this](https://github.com/ebensing/mongoose-within).
  *
@@ -5320,7 +5348,7 @@ Query.prototype.tailable = function(val, opts) {
 /**
  * Specifies a `$geometry` condition
  *
- * ####Example
+ * #### Example
  *
  *     const polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
  *     query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })
@@ -5338,7 +5366,7 @@ Query.prototype.tailable = function(val, opts) {
  *
  * The argument is assigned to the most recent path passed to `where()`.
  *
- * ####NOTE:
+ * #### Note:
  *
  * `geometry()` **must** come after either `intersects()` or `within()`.
  *
@@ -5362,7 +5390,7 @@ Query.prototype.tailable = function(val, opts) {
  *
  * These operators return documents sorted by distance.
  *
- * ####Example
+ * #### Example
  *
  *     query.where('loc').near({ center: [10, 10] });
  *     query.where('loc').near({ center: [10, 10], maxDistance: 5 });
@@ -5445,13 +5473,13 @@ Query.prototype.near = function() {
 /**
  * _DEPRECATED_ Specifies a `$nearSphere` condition
  *
- * ####Example
+ * #### Example
  *
  *     query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });
  *
  * **Deprecated.** Use `query.near()` instead with the `spherical` option set to `true`.
  *
- * ####Example
+ * #### Example
  *
  *     query.where('loc').near({ center: [10, 10], spherical: true });
  *
@@ -5474,7 +5502,7 @@ Query.prototype.nearSphere = function() {
  * You do not need to call this function explicitly, the JavaScript runtime
  * will call it for you.
  *
- * ####Example
+ * #### Example
  *
  *     for await (const doc of Model.aggregate([{ $sort: { name: 1 } }])) {
  *       console.log(doc.name);
@@ -5502,10 +5530,10 @@ if (Symbol.asyncIterator != null) {
 /**
  * Specifies a `$polygon` condition
  *
- * ####Example
+ * #### Example
  *
- *     query.where('loc').within().polygon([10,20], [13, 25], [7,15])
- *     query.polygon('loc', [10,20], [13, 25], [7,15])
+ *     query.where('loc').within().polygon([10, 20], [13, 25], [7, 15]);
+ *     query.polygon('loc', [10, 20], [13, 25], [7, 15]);
  *
  * @method polygon
  * @memberOf Query
@@ -5521,7 +5549,7 @@ if (Symbol.asyncIterator != null) {
 /**
  * Specifies a `$box` condition
  *
- * ####Example
+ * #### Example
  *
  *     const lowerLeft = [40.73083, -73.99756]
  *     const upperRight= [40.741404,  -73.988135]
@@ -5558,7 +5586,7 @@ Query.prototype.box = function(ll, ur) {
 /**
  * Specifies a `$center` or `$centerSphere` condition.
  *
- * ####Example
+ * #### Example
  *
  *     const area = { center: [50, 50], radius: 10, unique: true }
  *     query.where('loc').within().circle(area)
@@ -5603,7 +5631,7 @@ Query.prototype.center = Query.base.circle;
  *
  * **Deprecated.** Use [circle](#query_Query-circle) instead.
  *
- * ####Example
+ * #### Example
  *
  *     const area = { center: [50, 50], radius: 10 };
  *     query.where('loc').within().centerSphere(area);
@@ -5642,9 +5670,9 @@ Query.prototype.centerSphere = function() {
 /**
  * Determines if inclusive field selection has been made.
  *
- *     query.selectedInclusively() // false
- *     query.select('name')
- *     query.selectedInclusively() // true
+ *     query.selectedInclusively(); // false
+ *     query.select('name');
+ *     query.selectedInclusively(); // true
  *
  * @method selectedInclusively
  * @memberOf Query
@@ -5660,10 +5688,10 @@ Query.prototype.selectedInclusively = function selectedInclusively() {
 /**
  * Determines if exclusive field selection has been made.
  *
- *     query.selectedExclusively() // false
- *     query.select('-name')
- *     query.selectedExclusively() // true
- *     query.selectedInclusively() // false
+ *     query.selectedExclusively(); // false
+ *     query.select('-name');
+ *     query.selectedExclusively(); // true
+ *     query.selectedInclusively(); // false
  *
  * @method selectedExclusively
  * @memberOf Query
@@ -5696,4 +5724,4 @@ Query.prototype.model;
  * Export
  */
 
-module.exports = Query;
+module.exports = Query;