Merge pull request #13696 from Automattic/vkarpov15/gh-12942

docs(typescript): highlight auto type inference for methods and statics, add info on using methods with generics

docs/layout.pug

@@ -104,7 +104,7 @@ html(lang='en')
                         li.pure-menu-item.sub-item
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/schemas.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/schemas.html` ? 'selected' : '') Schemas
                         li.pure-menu-item.sub-item
-                          a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/statics-and-methods.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/statics-and-methods.html` ? 'selected' : '') Statics
+                          a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/statics-and-methods.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/statics-and-methods.html` ? 'selected' : '') Statics and Methods
                         li.pure-menu-item.sub-item
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/query-helpers.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/query-helpers.html` ? 'selected' : '') Query Helpers
                         li.pure-menu-item.sub-item

docs/typescript/statics.md

@@ -1,5 +1,37 @@
 # Statics in TypeScript
 
+To use Mongoose's automatic type inference to define types for your [statics](guide.html#statics) and [methods](guide.html#methods), you should define your methods and statics using the `methods` and `statics` schema options as follows.
+Do **not** use `Schema.prototype.method()` and `Schema.prototype.static()`.
+
+```typescript
+const userSchema = new mongoose.Schema(
+  { name: { type: String, required: true } },
+  {
+    methods: {
+      updateName(name: string) {
+        this.name = name;
+        return this.save();
+      }
+    },
+    statics: {
+      createWithName(name: string) {
+        return this.create({ name });
+      }
+    }
+  }
+);
+const UserModel = mongoose.model('User', userSchema);
+
+const doc = new UserModel({ name: 'test' });
+// Compiles correctly
+doc.updateName('foo');
+// Compiles correctly
+UserModel.createWithName('bar');
+```
+
+## With Generics
+
+We recommend using Mongoose's automatic type inference where possible, but you can use `Schema` and `Model` generics to set up type inference for your statics and methods.
 Mongoose [models](../models.html) do **not** have an explicit generic parameter for [statics](guide.html#statics).
 If your model has statics, we recommend creating an interface that [extends](https://www.typescriptlang.org/docs/handbook/interfaces.html) Mongoose's `Model` interface as shown below.
 
@@ -24,24 +56,27 @@ const User = model<IUser, UserModel>('User', schema);
 const answer: number = User.myStaticMethod(); // 42
 ```
 
-Mongoose does support auto typed static functions that it are supplied in schema options.
-Static functions can be defined by:
+You should pass methods as the 3rd generic param to the `Schema` constructor as follows.
 
 ```typescript
-import { Schema, model } from 'mongoose';
+import { Model, Schema, model } from 'mongoose';
 
-const schema = new Schema(
-  { name: String },
-  {
-    statics: {
-      myStaticMethod() {
-        return 42;
-      }
-    }
-  }
-);
+interface IUser {
+  name: string;
+}
 
-const User = model('User', schema);
+interface UserMethods {
+  updateName(name: string): Promise<any>;
+}
 
-const answer = User.myStaticMethod(); // 42
+const schema = new Schema<IUser, Model<IUser>, UserMethods>({ name: String });
+schema.method('updateName', function updateName(name) {
+  this.name = name;
+  return this.save();
+});
+
+const User = model('User', schema);
+const doc = new User({ name: 'test' });
+// Compiles correctly
+doc.updateName('foo');
 ```