feat(query): make Query#pre() and Query#post() public

Fix #9784

lib/document.js

@@ -779,10 +779,10 @@ Document.prototype.update = function update() {
 
 Document.prototype.updateOne = function updateOne(doc, options, callback) {
   const query = this.constructor.updateOne({ _id: this._id }, doc, options);
-  query._pre(cb => {
+  query.pre(cb => {
     this.constructor._middleware.execPre('updateOne', this, [this], cb);
   });
-  query._post(cb => {
+  query.post(cb => {
     this.constructor._middleware.execPost('updateOne', this, [this], {}, cb);
   });
 

lib/query.js

@@ -4470,20 +4470,54 @@ Query.prototype.catch = function(reject) {
   return this.exec().then(null, reject);
 };
 
-/*!
- * ignore
+/**
+ * Add pre [middleware](/docs/middleware.html) to this query instance. Doesn't affect
+ * other queries.
+ *
+ * ####Example:
+ *
+ *     const q1 = Question.find({ answer: 42 });
+ *     q1.pre(function middleware() {
+ *       console.log(this.getFilter());
+ *     });
+ *     await q1.exec(); // Prints "{ answer: 42 }"
+ *
+ *     // Doesn't print anything, because `middleware()` is only
+ *     // registered on `q1`.
+ *     await Question.find({ answer: 42 });
+ *
+ * @param {Function} fn
+ * @return {Promise}
+ * @api public
  */
 
-Query.prototype._pre = function(fn) {
+Query.prototype.pre = function(fn) {
   this._hooks.pre('exec', fn);
   return this;
 };
 
-/*!
- * ignore
+/**
+ * Add post [middleware](/docs/middleware.html) to this query instance. Doesn't affect
+ * other queries.
+ *
+ * ####Example:
+ *
+ *     const q1 = Question.find({ answer: 42 });
+ *     q1.post(function middleware() {
+ *       console.log(this.getFilter());
+ *     });
+ *     await q1.exec(); // Prints "{ answer: 42 }"
+ *
+ *     // Doesn't print anything, because `middleware()` is only
+ *     // registered on `q1`.
+ *     await Question.find({ answer: 42 });
+ *
+ * @param {Function} fn
+ * @return {Promise}
+ * @api public
  */
 
-Query.prototype._post = function(fn) {
+Query.prototype.post = function(fn) {
   this._hooks.post('exec', fn);
   return this;
 };

test/query.test.js

@@ -3724,4 +3724,21 @@ describe('Query', function() {
       assert.equal(quiz.questions[1].choices[0].choice_text, 'choice 1');
     });
   });
+
+  it('Query#pre() (gh-9784)', function() {
+    const Question = db.model('Test', Schema({ answer: Number }));
+    return co(function*() {
+      const q1 = Question.find({ answer: 42 });
+      const called = [];
+      q1.pre(function middleware() {
+        called.push(this.getFilter());
+      });
+      yield q1.exec();
+      assert.equal(called.length, 1);
+      assert.deepEqual(called[0], { answer: 42 });
+
+      yield Question.find({ answer: 42 });
+      assert.equal(called.length, 1);
+    });
+  });
 });