docs(api): add Document#$where to API docs

Fix #10583

Author: vkarpov15

index.d.ts

@@ -574,7 +574,7 @@ declare module 'mongoose' {
     $set(path: string, val: any, type: any, options?: any): this;
     $set(value: any): this;
 
-    /** Additional properties to attach to the query when calling `save()` and `isNew` is false. */
+    /** Set this property to add additional query filters when Mongoose saves this document and `isNew` is false. */
     $where: Record<string, unknown>;
 
     /** If this is a discriminator model, `baseModelName` is the name of the base model. */

lib/document.js

@@ -265,6 +265,28 @@ Object.defineProperty(Document.prototype, '$locals', {
 
 Document.prototype.isNew;
 
+/**
+ * Set this property to add additional query filters when Mongoose saves this document and `isNew` is false.
+ *
+ * ####Example:
+ *
+ *     // Make sure `save()` never updates a soft deleted document.
+ *     schema.pre('save', function() {
+ *       this.$where = { isDeleted: false };
+ *     });
+ *
+ * @api public
+ * @property $where
+ * @memberOf Document
+ * @instance
+ */
+
+Object.defineProperty(Document.prototype, '$where', {
+  configurable: false,
+  enumerable: false,
+  writable: true
+});
+
 /**
  * The string version of this documents _id.
  *