Merge branch '4.8' of github.com:Automattic/mongoose into 4.8

lib/aggregate.js

@@ -312,7 +312,42 @@ Aggregate.prototype.lookup = function(options) {
 };
 
 /**
- * Appends new custom $sample operator(s) to this aggregate pipeline.
+ * Appends new custom $graphLookup operator(s) to this aggregate pipeline, performing a recursive search on a collection.
+ * 
+ * NOTE: graphLookup can only consume at most 100MB of memory, and does not allow disk use even if `{ allowDiskUse: true }` is specified. 
+ * 
+ * #### Examples:
+ *      // Suppose we have a collection of courses, where a document might look like `{ _id: 0, name: 'Calculus', prerequisite: 'Trigonometry'}` and `{ _id: 0, name: 'Trigonometry', prerequisite: 'Algebra' }`
+ *      aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites
+ * 
+ * @see $graphLookup https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/#pipe._S_graphLookup
+ * @param {Object} options to $graphLookup as described in the above link
+ * @return {Aggregate}
+ * @api public
+ */
+
+Aggregate.prototype.graphLookup = function(options) {
+  var cloneOptions = {};
+  if (options) {
+    if (!utils.isObject(options)) {
+      throw new TypeError('Invalid graphLookup() argument. Must be an object.');
+    }
+
+    cloneOptions = utils.merge({}, options);
+    var startWith = cloneOptions.startWith;
+
+    if (startWith && typeof startWith === 'string') {
+      cloneOptions.startWith = cloneOptions.startWith.charAt(0) === '$' ?
+        cloneOptions.startWith :
+        '$' + cloneOptions.startWith;
+    }
+
+  }
+  return this.append({ $graphLookup: cloneOptions });
+};
+
+/**
+ * Appepnds new custom $sample operator(s) to this aggregate pipeline.
  *
  * ####Examples:
  *