fix(document): allow calling $assertPopulated() with values to better support manual population

lib/document.js

@@ -4417,23 +4417,32 @@ Document.prototype.$populated = Document.prototype.populated;
  *     doc.$assertPopulated('author'); // does not throw
  *     doc.$assertPopulated('other path'); // throws an error
  *
+ *     // Manually populate and assert in one call. The following does
+ *     // `doc.$set({ likes })` before asserting.
+ *     doc.$assertPopulated('likes', { likes });
  *
- * @param {String|String[]} paths
+ *
+ * @param {String|String[]} path path or array of paths to check. `$assertPopulated` throws if any of the given paths is not populated.
+ * @param {Object} [values] optional values to `$set()`. Convenient if you want to manually populate a path and assert that the path was populated in 1 call.
  * @return {Document} this
  * @memberOf Document
  * @method $assertPopulated
  * @instance
  * @api public
  */
 
-Document.prototype.$assertPopulated = function $assertPopulated(paths) {
-  if (Array.isArray(paths)) {
-    paths.forEach(path => this.$assertPopulated(path));
+Document.prototype.$assertPopulated = function $assertPopulated(path, values) {
+  if (Array.isArray(path)) {
+    path.forEach(p => this.$assertPopulated(p, values));
     return this;
   }
 
-  if (!this.$populated(paths)) {
-    throw new MongooseError(`Expected path "${paths}" to be populated`);
+  if (arguments.length > 1) {
+    this.$set(values);
+  }
+
+  if (!this.$populated(path)) {
+    throw new MongooseError(`Expected path "${path}" to be populated`);
   }
 
   return this;

types/document.d.ts

@@ -26,7 +26,7 @@ declare module 'mongoose' {
     __v?: any;
 
     /** Assert that a given path or paths is populated. Throws an error if not populated. */
-    $assertPopulated<Paths = {}>(paths: string | string[]): Omit<this, keyof Paths> & Paths;
+    $assertPopulated<Paths = {}>(path: string | string[], values?: Partial<Paths>): Omit<this, keyof Paths> & Paths;
 
     /* Get all subdocs (by bfs) */
     $getAllSubdocs(): Document[];