Merge pull request #14514 from Automattic/vkarpov15/gh-14305

Add documentation for calling `schema.post()` with async function

Author: vkarpov15

docs/middleware.md

@@ -151,7 +151,7 @@ schema.pre('save', function() {
     then(() => doMoreStuff());
 });
 
-// Or, in Node.js >= 7.6.0:
+// Or, using async functions
 schema.pre('save', async function() {
   await doStuff();
   await doMoreStuff();
@@ -250,9 +250,7 @@ schema.post('deleteOne', function(doc) {
 
 <h2 id="post-async"><a href="#post-async">Asynchronous Post Hooks</a></h2>
 
-If your post hook function takes at least 2 parameters, mongoose will
-assume the second parameter is a `next()` function that you will call to
-trigger the next middleware in the sequence.
+If your post hook function takes at least 2 parameters, mongoose will assume the second parameter is a `next()` function that you will call to trigger the next middleware in the sequence.
 
 ```javascript
 // Takes 2 parameters: this is an asynchronous post hook
@@ -271,6 +269,25 @@ schema.post('save', function(doc, next) {
 });
 ```
 
+You can also pass an async function to `post()`.
+If you pass an async function that takes at least 2 parameters, you are still responsible for calling `next()`.
+However, you can also pass in an async function that takes less than 2 parameters, and Mongoose will wait for the promise to resolve.
+
+```javascript
+schema.post('save', async function(doc) {
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  console.log('post1');
+  // If less than 2 parameters, no need to call `next()`
+});
+
+schema.post('save', async function(doc, next) {
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  console.log('post1');
+  // If there's a `next` parameter, you need to call `next()`.
+  next();
+});
+```
+
 <h2 id="defining"><a href="#defining">Define Middleware Before Compiling Models</a></h2>
 
 Calling `pre()` or `post()` after [compiling a model](models.html#compiling)

test/types/middleware.test.ts

@@ -63,6 +63,10 @@ schema.post<ITest>('save', function() {
   console.log(this.name);
 });
 
+schema.post<ITest>('save', async function() {
+  console.log(this.name);
+});
+
 schema.post<ITest>('save', function(err: Error, res: ITest, next: Function) {
   console.log(this.name, err.stack);
 });