Note: All examples are very contrived; minor suspension of disbelief is required. A while ago, my team was experimenting with some hooks in mongoose that modified the query conditions before executing it. We wanted to apply a filter at a global level, for example, only return records that have from the collection. pre-find age >= 18 persons Baking this logic inside the call itself seemed like a good idea initially. It saved us from having to modify every existing call in the codebase. This also provided a safeguard against devs forgetting to add the condition to every call in the future. Model.find() Model.find() ; mongoose = ( ); personSchema = mongoose.Schema({ : , : , }); { ( ._conditions.age >= ) next(); next( ( )); } personSchema.pre( , preFindHook); personSchema.pre( , preFindHook); PersonModel = mongoose.model( , personSchema); .exports = PersonModel; "use strict" const require "mongoose" const name String age Number ( ) function preFindHook next if this 18 else new Error "Invalid query" "find" "findOne" const "Person" module It worked perfectly; until a bunch of endpoints started to fail randomly. PATCH router.patch( , (req, res, next) => { { personId } = req.params; updatedPersonInfo = req.body; existingPersonRecord = PersonModel.findOne({ : personId, : { : }, }); (updatedPersonInfo.name) { existingPersonRecord.name = updatedPersonInfo.name; } existingPersonRecord.save(); res.json({ : existingPersonRecord.toObject() }); }) '/persons/${personId}' async const const const await _id age $gte 18 if await person We started searching for the issue using statements in route controllers. It seemed as if our recently registered hook was being triggered on as well. console.log pre-find Model.save() router.patch('/persons/${personId}', async (req, res, next) => { ... existingPersonRecord.name = updatedPersonInfo.name; } await existingPersonRecord.save(); res.json({ person: existingPersonRecord.toObject() }); }) + console.log('Reached this far without error'); Reached this far without error Invalid query at model.Query.preFindHook at callMiddlewareFunction Error: To confirm this, we turned on debug mode in mongoose and removed the hook. mongoose.set('debug', true) pre-find : ({ : ( ), age: { : } }, { : {} }) : ({ : ( ) }, { : undefined, projection: { _id: Mongoose people .findOne _id ObjectId "6031d9f91973241ccb4848e9" '$gte' 18 projection Reached this far without error Mongoose people .findOne _id ObjectId "6031d9f91973241ccb4848e9" session In debug mode, mongoose logs every query that it runs. It is clear that was executed here when was called. This call did not specify an age property in the filter. This made the hook throw an error. findOne() save() findOne() pre-find The very idea of mongoose executing a different operation than the one it was asked to was baffling to me. I spent the next hour scouring the web for hints or explanations, finding none. The mystery unraveled when I read the source code of as a last resort. The important parts are shown below. Complete source code can be found . Model.save here Model.prototype.$__handleSave = { ( .isNew) { [modelCollectionSymbol].insertOne( obj, saveOptions, { (err) { _setIsNew(_this, ); callback(err, ); ; } callback( , ret); } ); } { delta = .$__delta(); (delta) { [modelCollectionSymbol].updateOne( where, delta[ ], saveOptions, (err, ret) => { (err) { .$__undoReset(); callback(err); ; } ret.$where = where; callback( , ret); } ); } { optionsWithCustomValues = .assign({}, options, saveOptions); .constructor .exists( .$__where(), optionsWithCustomValues) .then( { (!documentExists) { DocumentNotFoundError( .$__where(), .constructor.modelName ); } callback(); }) .catch(callback); ; } } }; ( ) function options, callback if this this ( ) function err, ret if true null return null else const this if this 1 if this return null else const Object this this ( ) => documentExists if throw new this this return Mongoose internally tracks whether a document is ‘new’ or not. It also tracks the fields (if any) that have been updated on the document. This information is used to decide what operation is performed when the method is called on the document. .save() When the document is ‘new’, mongoose performs an insert. When the document is not new, mongoose calculates the ‘delta’. If any fields have been modified, mongoose performs an update. If no fields have been modified, mongoose checks that the document exists in the database using findOne. What We Could Have Done Better The reason why only the PATCH calls failed was that in a PATCH operation, which is a partial update, there is a possibility that none of the fields are updated. In this case, we should not have called on the document in the first place. .save() The hook we wrote was flawed as well. The is a private property of 3rd party code. We should not be messing with it even if JavaScript allows us to. _conditions In hindsight, it seems like mongoose was doing the sensible thing by simply ensuring that the document existed in the database. Mongoose is a abstraction layer over Mongo. It is incorrect to think of its operations as simple wrappers to those of Mongo’s native driver. (heavy)
