From 7629c94037c79fa07640fec77aacf9c25b6e8e96 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Tue, 9 Apr 2024 11:55:30 -0400
Subject: [PATCH] docs(middleware): add note about using async functions for
 post hooks

---
 docs/middleware.md | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/middleware.md b/docs/middleware.md
index 41440c9a6bc..e6dc8d30474 100644
--- a/docs/middleware.md
+++ b/docs/middleware.md
@@ -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)