Merge pull request #9769 from Automattic/#8075

feat: Implemented setting explain flag

docs/index.pug

@@ -32,7 +32,7 @@ block content
     ```javascript
     // getting-started.js
     const mongoose = require('mongoose');
-    mongoose.connect('mongodb://localhost/test', {useNewUrlParser: true});
+    mongoose.connect('mongodb://localhost/test', {useNewUrlParser: true, useUnifiedTopology: true});
     ```
 
     We have a pending connection to the test database running on localhost.

index.d.ts

@@ -1096,7 +1096,7 @@ declare module 'mongoose' {
     method(obj: { [name: string]: Function }): this;
 
     /** Object of currently defined methods on this schema. */
-    methods: { [name: string]: Function };
+    methods: { [name: string]: (this: DocType, ...args: any[]) => void };
 
     /** The original object passed to the schema constructor */
     obj: any;
@@ -1167,10 +1167,11 @@ declare module 'mongoose' {
     virtualpath(name: string): VirtualType | null;
   }
 
-  interface SchemaDefinition {
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    [path: string]: SchemaTypeOptions<any> | Function | string | Schema | Schema[] | Array<SchemaTypeOptions<any>> | Function[] | SchemaDefinition | SchemaDefinition[];
-  }
+  type SchemaDefinitionProperty<T = undefined> = SchemaTypeOptions<any> | Function | string | Schema | Schema[] | Array<SchemaTypeOptions<any>> | Function[] | SchemaDefinition<T> | SchemaDefinition<T>[];
+
+  type SchemaDefinition<T = undefined> = T extends undefined
+    ? { [path: string]: SchemaDefinitionProperty; }
+    : { [path in keyof T]-?: SchemaDefinitionProperty<T[path]>; };
 
   interface SchemaOptions {
     /**

lib/model.js

@@ -1059,7 +1059,6 @@ Model.prototype.model = function model(name) {
 
 Model.exists = function exists(filter, options, callback) {
   _checkContext(this, 'exists');
-
   if (typeof options === 'function') {
     callback = options;
     options = null;
@@ -1079,8 +1078,12 @@ Model.exists = function exists(filter, options, callback) {
     });
     return;
   }
-
-  return query.then(doc => !!doc);
+  options = options || {};
+  if (!options.explain) {
+    return query.then(doc => !!doc);
+  }
+
+  return query.exec();
 };
 
 /**

lib/query.js

@@ -1338,7 +1338,6 @@ Query.prototype.setOptions = function(options, overwrite) {
     }
     return this;
   }
-
   if (options == null) {
     return this;
   }

test/model.test.js

@@ -7083,4 +7083,26 @@ describe('Model', function() {
       });
     });
   });
+  describe('Setting the explain flag', function() {
+    it('should give an object back rather than a boolean (gh-8275)', function() {
+      return co(function*() {
+        const MyModel = db.model('Character', mongoose.Schema({
+          name: String,
+          age: Number,
+          rank: String
+        }));
+
+        yield MyModel.create([
+          { name: 'Jean-Luc Picard', age: 59, rank: 'Captain' },
+          { name: 'William Riker', age: 29, rank: 'Commander' },
+          { name: 'Deanna Troi', age: 28, rank: 'Lieutenant Commander' },
+          { name: 'Geordi La Forge', age: 29, rank: 'Lieutenant' },
+          { name: 'Worf', age: 24, rank: 'Lieutenant' }
+        ]);
+        const res = yield MyModel.exists({}, { explain: true });
+
+        assert.equal(typeof res, 'object');
+      });
+    });
+  });
 });

test/typescript/main.test.js

@@ -166,7 +166,7 @@ describe('typescript syntax', function() {
   });
 
   it('methods', function() {
-    const errors = runTest('methods.ts');
+    const errors = runTest('methods.ts', { strict: true });
     if (process.env.D && errors.length) {
       console.log(errors);
     }

test/typescript/methods.ts

@@ -5,11 +5,12 @@ interface ITest extends Document {
   getAnswer(): number;
 }
 
-const TestSchema = new Schema({
+const TestSchema = new Schema<ITest>({
   foo: { type: String, required: true }
 });
 
 TestSchema.methods.getAnswer = function(): number {
+  console.log(this.foo.trim());
   return 42;
 };