BREAKING CHANGE: rely on transforms over middleware to apply virtuals and add findOneAndReplace support

.github/workflows/test.yml

@@ -44,7 +44,7 @@ jobs:
       fail-fast: false
       matrix:
         node: [22]
-        os: [ubuntu-22.04]
+        os: [ubuntu-24.04]
     name: TypeScript Test
     steps:
       - uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # v3

index.js

@@ -7,25 +7,16 @@ const attachVirtualsFnMap = new WeakMap();
 
 module.exports = function mongooseLeanVirtuals(schema, options) {
   const fn = attachVirtualsMiddleware(schema, options);
-  schema.pre('find', function() {
-    if (typeof this.map === 'function') {
-      this.map((res) => {
-        fn.call(this, res);
-        return res;
-      });
-    } else {
-      this.options.transform = (res) => {
-        fn.call(this, res);
-        return res;
-      };
-    }
+  schema.pre(['find', 'findOne', 'findOneAndUpdate', 'findOneAndDelete', 'findOneAndReplace'], function mongooseLeanVirtualsMiddleware() {
+    const _this = this;
+    // Unshift ensures this transform runs before any other transforms and middleware (middleware runs after transforms).
+    // This is crucial to ensure that virtuals are applied to the data structure first, preventing user-specified transforms
+    // from operating on an unexpected or incomplete data structure. See gh-75 for more details.
+    this._transforms.unshift(function applyLeanVirtuals(res) {
+      fn.call(_this, res);
+      return res;
+    });
   });
-
-  schema.post('find', fn);
-  schema.post('findOne', fn);
-  schema.post('findOneAndUpdate', fn);
-  schema.post('findOneAndRemove', fn);
-  schema.post('findOneAndDelete', fn);
 };
 
 module.exports.parent = function(obj) {
@@ -43,7 +34,7 @@ module.exports.parent = function(obj) {
 };
 
 function attachVirtualsMiddleware(schema, options = {}) {
-  return function(res) {
+  return function attachVirtualsToQueryResult(res) {
     let virtuals = this._mongooseOptions.lean && this._mongooseOptions.lean.virtuals != null ? this._mongooseOptions.lean.virtuals : options.enabledByDefault;
     if (virtuals) {
       if (Array.isArray(virtuals)) {

package.json

@@ -37,7 +37,7 @@
     "typescript": "5.x"
   },
   "peerDependencies": {
-    "mongoose": ">=5.11.10"
+    "mongoose": ">=8.0.0"
   },
   "author": "Valeri Karpov <val@karpov.io>",
   "license": "Apache 2.0",

test/index.test.js

@@ -95,6 +95,10 @@ const supportedOps = {
     leanOptions = leanOptions || defaultLeanOptions;
     return model.findOneAndDelete({ _id: docId }).lean(leanOptions).exec();
   },
+  'findOneAndReplace': function(model, docId, leanOptions) {
+    leanOptions = leanOptions || defaultLeanOptions;
+    return model.findOneAndReplace({ _id: docId }, { ...baseObj }).lean(leanOptions).exec();
+  }
 };
 const supportedOpsKeys = Object.keys(supportedOps);
 
@@ -808,6 +812,34 @@ describe('Discriminators work', () => {
     );
   });
 
+  it('with transform (gh-75)', async function() {
+    const schema = new mongoose.Schema({ name: String });
+    schema.virtual('lower').get(function() {
+      return this.name.toLowerCase();
+    });
+
+    schema.plugin(mongooseLeanVirtuals);
+    const Model = mongoose.model('gh75', schema);
+
+    await Model.create([
+      { name: 'JOHN' },
+      { name: 'JANE' }
+    ]);
+
+    const docs = await Model.find().lean({ virtuals: true }).transform((docs) => {
+      const map = {};
+      docs.forEach(doc => {
+        map[doc._id.toString()] = doc;
+      });
+      return map;
+    });
+
+    assert.equal(Object.keys(docs).length, 2);
+    for (const [id, doc] of Object.entries(docs)) {
+      assert.equal(doc.name.toLowerCase(), doc.lower);
+    }
+  });
+
   it('populates empty array instead of undefined for empty virtuals with justOne: false (Automattic/mongoose#10816)', async function() {
     const matchSchema = new mongoose.Schema({
       timestamp: { type: Number }