Merge pull request #13850 from Automattic/vkarpov15/gh-13771

docs(model): add examples of using `diffIndexes()` to `syncIndexes()`and `diffIndexes()` api docs

Author: vkarpov15

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.
+ * @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() {

test/types/schema.test.ts

@@ -1217,4 +1217,4 @@ function gh13800() {
     expectType<string>(this.lastName);
     expectError<string>(this.someOtherField);
   });
-}
+}