fix(populate): various cleanup for ordered option

Fix Automattic#15210

Author: vkarpov15

lib/document.js

@@ -4508,6 +4508,8 @@ Document.prototype.equals = function(doc) {
  * @param {Object|Function} [options.match=null] Add an additional filter to the populate query. Can be a filter object containing [MongoDB query syntax](https://www.mongodb.com/docs/manual/tutorial/query-documents/), or a function that returns a filter object.
  * @param {Function} [options.transform=null] Function that Mongoose will call on every populated document that allows you to transform the populated document.
  * @param {Object} [options.options=null] Additional options like `limit` and `lean`.
+ * @param {Boolean} [options.forceRepopulate=true] Set to `false` to prevent Mongoose from repopulating paths that are already populated
+ * @param {Boolean} [options.ordered=false] Set to `true` to execute any populate queries one at a time, as opposed to in parallel. We recommend setting this option to `true` if using transactions, especially if also populating multiple paths or paths with multiple models. MongoDB server does **not** support multiple operations in parallel on a single transaction.
  * @param {Function} [callback] Callback
  * @see population https://mongoosejs.com/docs/populate.html
  * @see Query#select https://mongoosejs.com/docs/api/query.html#Query.prototype.select()
@@ -4525,20 +4527,15 @@ Document.prototype.populate = async function populate() {
     throw new MongooseError('Document.prototype.populate() no longer accepts a callback');
   }
 
-  let ordered = null;
   if (args.length !== 0) {
     // use hash to remove duplicate paths
     const res = utils.populate.apply(null, args);
-    ordered = res.ordered;
     for (const populateOptions of res) {
       pop[populateOptions.path] = populateOptions;
     }
   }
 
   const paths = utils.object.vals(pop);
-  if (ordered) {
-    paths.ordered = ordered;
-  }
 
   let topLevelModel = this.constructor;
   if (this.$__isNested) {

lib/model.js

@@ -4258,6 +4258,7 @@ Model.validate = async function validate(obj, pathsOrOptions, context) {
  * @param {Object} [options.options=null] Additional options like `limit` and `lean`.
  * @param {Function} [options.transform=null] Function that Mongoose will call on every populated document that allows you to transform the populated document.
  * @param {Boolean} [options.forceRepopulate=true] Set to `false` to prevent Mongoose from repopulating paths that are already populated
+ * @param {Boolean} [options.ordered=false] Set to `true` to execute any populate queries one at a time, as opposed to in parallel. Set this option to `true` if populating multiple paths or paths with multiple models in transactions.
  * @return {Promise}
  * @api public
  */
@@ -4275,9 +4276,10 @@ Model.populate = async function populate(docs, paths) {
   }
 
   // each path has its own query options and must be executed separately
-  if (paths.ordered) {
+  if (paths.find(p => p.ordered)) {
     // Populate in series, primarily for transactions because MongoDB doesn't support multiple operations on
     // one transaction in parallel.
+    // Note that if _any_ path has `ordered`, we make the top-level populate `ordered` as well.
     for (const path of paths) {
       await _populatePath(this, docs, path);
     }

lib/utils.js

@@ -523,11 +523,7 @@ exports.populate = function populate(path, select, model, match, options, subPop
 
     if (Array.isArray(path)) {
       const singles = makeSingles(path);
-      const ret = singles.map(o => exports.populate(o)[0]);
-      if (path.ordered) {
-        ret.ordered = path.ordered;
-      }
-      return ret;
+      return singles.map(o => exports.populate(o)[0]);
     }
 
     if (exports.isObject(path)) {
@@ -617,13 +613,6 @@ function _populateObj(obj) {
     ret.push(new PopulateOptions(Object.assign({}, obj, { path: path })));
   }
 
-  if (obj.ordered) {
-    ret.ordered = true;
-    for (const path of ret) {
-      path.ordered = true;
-    }
-  }
-
   return ret;
 }
 

types/populate.d.ts

@@ -39,6 +39,12 @@ declare module 'mongoose' {
     foreignField?: string;
     /** Set to `false` to prevent Mongoose from repopulating paths that are already populated */
     forceRepopulate?: boolean;
+    /**
+     * Set to `true` to execute any populate queries one at a time, as opposed to in parallel.
+     * We recommend setting this option to `true` if using transactions, especially if also populating multiple paths or paths with multiple models.
+     * MongoDB server does **not** support multiple operations in parallel on a single transaction.
+     */
+    ordered?: boolean;
   }
 
   interface PopulateOption {