From db299292813e019e21c43326c47187f0757b7546 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Sun, 10 Sep 2023 12:52:27 -0400
Subject: [PATCH 1/2] docs(model): add examples of using `diffIndexes()` to
 `syncIndexes()` and `diffIndexes()` api docs

Fix #13771
---
 lib/model.js              | 20 ++++++++++++++++++--
 test/types/schema.test.ts |  2 +-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/lib/model.js b/lib/model.js
index 320ea334153..dca25a92ef6 100644
--- a/lib/model.js
+++ b/lib/model.js
@@ -1451,6 +1451,17 @@ Model.createCollection = async function createCollection(options) {
  *     // Will drop the 'age' index and create an index on `name`
  *     await Customer.syncIndexes();
  *
+ * You should be careful about running `syncIndexes()` on production applications under heavy load,
+ * because index builds are expensive operations, and unexpected index drops can lead to degraded
+ * performance. Before running `syncIndexes()`, you can use the [`diffIndexes()` function](#Model.diffIndexes())
+ * to check what indexes `syncIndexes()` will drop and create.
+ *
+ * #### Example:
+ *
+ *     const { toDrop, toCreate } = await Model.diffIndexes();
+ *     toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
+ *     toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create
+ *
  * @param {Object} [options] options to pass to `ensureIndexes()`
  * @param {Boolean} [options.background=null] if specified, overrides each index's `background` property
  * @return {Promise}
@@ -1483,9 +1494,14 @@ Model.syncIndexes = async function syncIndexes(options) {
 /**
  * Does a dry-run of `Model.syncIndexes()`, returning the indexes that `syncIndexes()` would drop and create if you were to run `syncIndexes()`.
  *
+ * #### Example:
+ *
+ *     const { toDrop, toCreate } = await Model.diffIndexes();
+ *     toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
+ *     toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create
+ *
  * @param {Object} [options]
- * @returns {Promise} which contains an object, {toDrop, toCreate}, which
- * are indexes that would be dropped in MongoDB and indexes that would be created in MongoDB.
+ * @returns {Promise<{ toDrop: string[], toCreate: string[] }>} contains the indexes that would be dropped in MongoDB and indexes that would be created in MongoDB.
  */
 
 Model.diffIndexes = async function diffIndexes() {
diff --git a/test/types/schema.test.ts b/test/types/schema.test.ts
index b6726bfdc78..16f58ed938b 100644
--- a/test/types/schema.test.ts
+++ b/test/types/schema.test.ts
@@ -1217,4 +1217,4 @@ function gh13800() {
     expectType<string>(this.lastName);
     expectError<string>(this.someOtherField);
   });
-}
\ No newline at end of file
+}

From e14e049d40fcc3c1579ac969247b72175a39ad97 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Sun, 10 Sep 2023 12:57:11 -0400
Subject: [PATCH 2/2] docs: quick fix for diffIndexes() api docs

---
 lib/model.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/model.js b/lib/model.js
index dca25a92ef6..a6743f87d3d 100644
--- a/lib/model.js
+++ b/lib/model.js
@@ -1501,7 +1501,7 @@ Model.syncIndexes = async function syncIndexes(options) {
  *     toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create
  *
  * @param {Object} [options]
- * @returns {Promise<{ toDrop: string[], toCreate: string[] }>} contains the indexes that would be dropped in MongoDB and indexes that would be created in MongoDB.
+ * @return {Promise<Object>} contains the indexes that would be dropped in MongoDB and indexes that would be created in MongoDB as `{ toDrop: string[], toCreate: string[] }`.
  */
 
 Model.diffIndexes = async function diffIndexes() {