Merge branch '9.2'

Author: vkarpov15

docs/source/api.js

@@ -209,8 +209,18 @@ function processName(input) {
 }
 
 // helper function to keep translating array types to string consistent
-function convertTypesToString(types) {
-  return Array.isArray(types) ? types.join('|') : types;
+// typesDescription is used as fallback when types contains '[object Object]'
+// (happens with string literal types like 'before'|'after' due to dox/jsdoctypeparser bug)
+function convertTypesToString(types, typesDescription) {
+  if (!Array.isArray(types)) {
+    return types;
+  }
+  const result = types.join('|');
+  if (result.includes('[object Object]') && typesDescription) {
+    // Strip HTML code tags from typesDescription: <code>foo</code> -> foo
+    return typesDescription.replace(/<\/?code>/g, '');
+  }
+  return result;
 }
 
 /**
@@ -295,12 +305,12 @@ function processFile(props) {
           ctx.name = tag.name;
           // only assign "type" if there are types
           if (tag.types.length > 0) {
-            ctx.type = convertTypesToString(tag.types);
+            ctx.type = convertTypesToString(tag.types, tag.typesDescription);
           }
 
           break;
         case 'type':
-          ctx.type = convertTypesToString(tag.types);
+          ctx.type = convertTypesToString(tag.types, tag.typesDescription);
           break;
         case 'static':
           ctx.type = 'property';
@@ -359,7 +369,7 @@ function processFile(props) {
             tag.types.push('null');
           }
           if (tag.types) {
-            tag.types = convertTypesToString(tag.types);
+            tag.types = convertTypesToString(tag.types, tag.typesDescription);
           }
           ctx[tag.type].push(tag);
           if (tag.name != null && tag.name.startsWith('[') && tag.name.endsWith(']') && tag.name.includes('.')) {

docs/timestamps.md

@@ -22,7 +22,7 @@ await doc.save();
 console.log(doc.createdAt); // 2022-02-26T16:37:48.244Z
 console.log(doc.updatedAt); // 2022-02-26T16:37:48.307Z
 
-doc = await User.findOneAndUpdate({ _id: doc._id }, { name: 'test3' }, { new: true });
+doc = await User.findOneAndUpdate({ _id: doc._id }, { name: 'test3' }, { returnDocument: 'after' });
 console.log(doc.createdAt); // 2022-02-26T16:37:48.244Z
 console.log(doc.updatedAt); // 2022-02-26T16:37:48.366Z
 ```
@@ -51,7 +51,7 @@ console.log(doc.updatedAt); // 2022-02-26T17:08:13.991Z
 doc = await User.findOneAndUpdate(
   { _id: doc._id },
   { name: 'test3', createdAt: new Date(0), updatedAt: new Date(0) },
-  { new: true }
+  { returnDocument: 'after' }
 );
 console.log(doc.createdAt); // 2022-02-26T17:08:13.930Z
 console.log(doc.updatedAt); // 2022-02-26T17:08:14.008Z
@@ -66,7 +66,7 @@ Calling `replaceOne()` or `findOneAndReplace()` will update the `createdAt` time
 doc = await User.findOneAndReplace(
   { _id: doc._id },
   { name: 'test3' },
-  { new: true }
+  { returnDocument: 'after' }
 );
 console.log(doc.createdAt); // 2022-02-26T17:08:14.008Z
 console.log(doc.updatedAt); // 2022-02-26T17:08:14.008Z
@@ -80,7 +80,7 @@ doc = await User.findOneAndReplace(
     createdAt: new Date('2022-06-01'),
     updatedAt: new Date('2022-06-01')
   },
-  { new: true }
+  { returnDocument: 'after' }
 );
 console.log(doc.createdAt); // 2022-06-01T00:00:00.000Z
 console.log(doc.updatedAt); // 2022-06-01T00:00:00.000Z
@@ -120,7 +120,7 @@ console.log(doc.updatedAt); // 2022-02-26T23:28:54.264Z
 // Similarly, setting `timestamps: false` on a query tells Mongoose to skip updating
 // `updatedAt`.
 doc = await User.findOneAndUpdate({ _id: doc._id }, { name: 'test3' }, {
-  new: true,
+  returnDocument: 'after',
   timestamps: false
 });
 console.log(doc.updatedAt); // 2022-02-26T23:28:54.264Z
@@ -159,15 +159,15 @@ let doc = await User.create({ name: 'test' });
 // To update `updatedAt`, do a `findOneAndUpdate()` with `timestamps: false` and
 // `updatedAt` set to the value you want
 doc = await User.findOneAndUpdate({ _id: doc._id }, { updatedAt: new Date(0) }, {
-  new: true,
+  returnDocument: 'after',
   timestamps: false
 });
 console.log(doc.updatedAt); // 1970-01-01T00:00:00.000Z
 
 // To update `createdAt`, you also need to set `strict: false` because `createdAt`
 // is immutable
 doc = await User.findOneAndUpdate({ _id: doc._id }, { createdAt: new Date(0) }, {
-  new: true,
+  returnDocument: 'after',
   timestamps: false,
   strict: false
 });

docs/tutorials/findoneandupdate.md

@@ -26,22 +26,17 @@ In the following example, `doc` initially only has `name` and `_id` properties.
 [require:Tutorial.*findOneAndUpdate.*basic case]
 ```
 
-You should set the `new` option to `true` to return the document **after** `update` was applied.
+You should set the `returnDocument` option to `'after'` to return the document **after** `update` was applied.
 
 ```acquit
-[require:Tutorial.*findOneAndUpdate.*new option]
+[require:Tutorial.*findOneAndUpdate.*returnDocument option]
 ```
 
 Mongoose's `findOneAndUpdate()` is slightly different from [the MongoDB Node.js driver's `findOneAndUpdate()`](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#findOneAndUpdate) because it returns the document itself, not a [result object](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#~findAndModifyWriteOpResult).
 
-As an alternative to the `new` option, you can also use the `returnOriginal` option.
-`returnOriginal: false` is equivalent to `new: true`. The `returnOriginal` option
-exists for consistency with the [the MongoDB Node.js driver's `findOneAndUpdate()`](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#findOneAndUpdate),
-which has the same option.
-
-```acquit
-[require:Tutorial.*findOneAndUpdate.*returnOriginal option]
-```
+The `new` and `returnOriginal` options are **deprecated** in favor of `returnDocument`.
+Use `returnDocument: 'after'` instead of `new: true` or `returnOriginal: false`.
+Use `returnDocument: 'before'` instead of `new: false` or `returnOriginal: true`.
 
 ## Atomic Updates
 

lib/aggregate.js

@@ -719,7 +719,7 @@ Aggregate.prototype.read = function(pref, tags) {
  *
  *     await Model.aggregate(pipeline).readConcern('majority');
  *
- * @param {String} level one of the listed read concern level or their aliases
+ * @param {'local'|'available'|'majority'|'snapshot'|'linearizable'|'l'|'a'|'m'|'s'|'lz'} level one of the listed read concern level or their aliases
  * @see mongodb https://www.mongodb.com/docs/manual/reference/read-concern/
  * @return {Aggregate} this
  * @api public
@@ -785,7 +785,7 @@ Aggregate.prototype.redact = function(expression, thenExpr, elseExpr) {
  *
  *     Model.aggregate(..).explain()
  *
- * @param {String} [verbosity]
+ * @param {'queryPlanner'|'executionStats'|'allPlansExecution'} [verbosity]
  * @return {Promise}
  */
 

lib/cursor/aggregationCursor.js

@@ -389,7 +389,7 @@ function _transformForAsyncIterator(doc) {
  * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html#addCursorFlag).
  * Useful for setting the `noCursorTimeout` and `tailable` flags.
  *
- * @param {String} flag
+ * @param {'tailable'|'oplogReplay'|'noCursorTimeout'|'awaitData'|'partial'} flag
  * @param {Boolean} value
  * @return {AggregationCursor} this
  * @api public

lib/cursor/queryCursor.js

@@ -371,7 +371,7 @@ QueryCursor.prototype.options;
  * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/4.9/classes/FindCursor.html#addCursorFlag).
  * Useful for setting the `noCursorTimeout` and `tailable` flags.
  *
- * @param {String} flag
+ * @param {'tailable'|'oplogReplay'|'noCursorTimeout'|'awaitData'|'partial'} flag
  * @param {Boolean} value
  * @return {AggregationCursor} this
  * @api public

lib/document.js

@@ -861,7 +861,7 @@ function init(self, obj, doc, opts, prefix) {
  * @param {Object} update
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
  * @param {Object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.lean()) and the [Mongoose lean tutorial](https://mongoosejs.com/docs/tutorials/lean.html).
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/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 {Boolean|Object} [options.middleware=true] set to `false` to skip all user-defined middleware
  * @param {Boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks

lib/helpers/query/castUpdate.js

@@ -41,7 +41,7 @@ const mongodbUpdateOperators = new Set([
  * @param {Schema} schema
  * @param {Object} obj
  * @param {Object} [options]
- * @param {Boolean|String} [options.strict] defaults to true
+ * @param {Boolean|'throw'} [options.strict] defaults to true
  * @param {Query} context passed to setters
  * @return {Boolean} true iff the update is non-empty
  * @api private
@@ -205,7 +205,7 @@ function castPipelineOperator(op, val) {
  * @param {Object} obj part of a query
  * @param {String} op the atomic operator ($pull, $set, etc)
  * @param {Object} [options]
- * @param {Boolean|String} [options.strict]
+ * @param {Boolean|'throw'} [options.strict]
  * @param {Query} context
  * @param {Object} filter
  * @param {String} pref path prefix (internal only)