Merge branch '8.15' into csfle

Author: vkarpov15

.eslintrc.js

@@ -7,7 +7,6 @@ module.exports = {
   ignorePatterns: [
     'tools',
     'dist',
-    'website.js',
     'test/files/*',
     'benchmarks',
     '*.min.js',

.github/workflows/test.yml

@@ -39,7 +39,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: [16, 18, 20, 22]
+        node: [16, 18, 20, 22, 24]
         os: [ubuntu-22.04, ubuntu-24.04]
         mongodb: [6.0.15, 7.0.12, 8.0.0]
         include:
@@ -74,12 +74,6 @@ jobs:
       - name: NPM Test with Coverage
         run: npm run test-coverage
         if: matrix.coverage == true
-      - name: Archive code coverage results
-        uses: actions/upload-artifact@v4
-        if: matrix.coverage == true
-        with:
-          name: coverage
-          path: coverage
 
   test-deno:
     runs-on: ubuntu-22.04

.gitignore

@@ -59,6 +59,9 @@ index.html
 # yarn package-lock
 yarn.lock
 
+# deno lock
+deno.lock
+
 # npm pack output
 mongoose.tgz
 mongoose-*.tgz

CHANGELOG.md

@@ -1,3 +1,41 @@
+8.14.2 / 2025-05-08
+===================
+ * fix(query): handle casting array filter paths underneath array filter paths with embedded discriminators #15388 #15386
+ * docs(typescript): correct schema and model generic params in TS virtuals docs #15391
+ * docs+types(schema): add alternative optimisticConcurrency syntaxes to docs + types #15405 #10591
+ * chore: add Node 24 to CI matrix #15408 [stscoundrel](https://github.com/stscoundrel)
+
+7.8.7 / 2025-04-30
+==================
+ * types(aggregate): allow calling project() with a string #15304 #15300
+ * docs: update deleteOne & deleteMany API def #15360 [Elliot67](https://github.com/Elliot67) [SethFalco](https://github.com/SethFalco)
+
+8.14.1 / 2025-04-29
+===================
+ * fix: correct change tracking with maps of arrays of primitives and maps of maps #15374 #15350
+ * fix(populate): consistently convert Buffer representation of UUID to hex string to avoid confusing populate assignment #15383 #15382
+ *  docs: add TypeScript Query guide with info on lean() + transform() #15377 #15311
+
+8.14.0 / 2025-04-25
+===================
+ * feat: upgrade MongoDB driver -> 6.16 #15371
+ * feat: implement Query findById methods #15337 [sderrow](https://github.com/sderrow)
+ * feat(subdocument): support schematype-level minimize option to disable minimizing empty subdocuments #15336 #15313
+ * feat: add skipOriginalStackTraces option to avoid stack trace performance overhead #15345 #15194
+ * fix(model): disallow Model.findOneAndUpdate(update) and fix TypeScript types re: findOneAndUpdate #15365 #15363
+ * types: correctly recurse in InferRawDocType #15357 #14954 [JavaScriptBach](https://github.com/JavaScriptBach)
+ * types: include virtuals in toJSON and toObject output if virtuals: true set #15346 #15316
+ * types: make init hooks types accurately reflect runtime behavior #15331 #15301
+
+8.13.3 / 2025-04-24
+===================
+ * fix: export MongooseBulkSaveIncompleteError #15370 #15369
+ * fix: clone POJOs and arrays when casting query filter to avoid mutating objects #15367 #15364
+ * types(connection): add Connection.prototype.bulkWrite() to types #15368 #15359
+ * docs: add version requirements to v7 migration docs #15361 [SethFalco](https://github.com/SethFalco)
+ * docs: update links in deleteOne & deleteMany API def #15360 [Elliot67](https://github.com/Elliot67)
+ * docs: adds Model#count to list of fns callback removed from #15349 [SethFalco](https://github.com/SethFalco)
+
 8.13.2 / 2025-04-03
 ===================
  * fix: avoid double calling validators on paths in document arrays underneath subdocuments #15338 #15335

benchmarks/findOneWithCast.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const mongoose = require('../');
+
+run().catch(err => {
+  console.error(err);
+  process.exit(-1);
+});
+
+async function run() {
+  await mongoose.connect('mongodb://127.0.0.1:27017/mongoose_benchmark');
+
+  const SchemaParticipant = new mongoose.Schema(
+    {
+      user: mongoose.Schema.Types.UUID,
+    },
+    {
+      _id: false
+    }
+  );
+
+  const TestSchema = new mongoose.Schema(
+    {
+      participants1: { type: [SchemaParticipant] },
+      participants2: { type: [SchemaParticipant] },
+      participants3: { type: [SchemaParticipant] },
+      participants4: { type: [SchemaParticipant] },
+      participants5: { type: [SchemaParticipant] },
+      date: { type: Number },
+    },
+    {
+      collection: 'test_uuid_mutations',
+    }
+  );
+
+  const TestModel = mongoose.model('Test', TestSchema);
+
+  if (!process.env.MONGOOSE_BENCHMARK_SKIP_SETUP) {
+    await TestModel.deleteMany({});
+  }
+
+  const peer = {
+    user: '1583b99d-8462-4343-8dfd-9105252e5662',
+  };
+
+  const numIterations = 500;
+  const queryStart = Date.now();
+  for (let i = 0; i < numIterations; ++i) {
+    for (let j = 0; j < 10; ++j) {
+      await TestModel.findOne({
+        $or: [
+          { participants1: { $elemMatch: peer } },
+          { participants2: { $elemMatch: peer } },
+          { participants3: { $elemMatch: peer } },
+          { participants4: { $elemMatch: peer } },
+          { participants5: { $elemMatch: peer } }
+        ]
+      });
+    }
+  }
+  const queryEnd = Date.now();
+
+  const results = {
+    'Average findOne time ms': +((queryEnd - queryStart) / numIterations).toFixed(2)
+  };
+
+  console.log(JSON.stringify(results, null, '  '));
+  process.exit(0);
+}

docs/layout.pug

@@ -41,7 +41,7 @@ html(lang='en')
                   - if (versions.currentVersion.listed !== versions.latestVersion.listed)
                     li.pure-menu-item
                       a.pure-menu-link(href=`${versions.latestVersion.path}/docs/index.html`) Version #{versions.latestVersion.listed}
-                  each pastVersion in versions.pastVersions 
+                  each pastVersion in versions.pastVersions
                     li.pure-menu-item
                       a.pure-menu-link(href=`/docs/${pastVersion.path}/index.html`) Version #{pastVersion.listed}
               li.pure-menu-item.search
@@ -105,10 +105,14 @@ html(lang='en')
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/schemas.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/schemas.html` ? 'selected' : '') Schemas
                         li.pure-menu-item.sub-item
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/statics-and-methods.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/statics-and-methods.html` ? 'selected' : '') Statics and Methods
+                        li.pure-menu-item.sub-item
+                          a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/queries.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/queries.html` ? 'selected' : '') Queries
                         li.pure-menu-item.sub-item
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/query-helpers.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/query-helpers.html` ? 'selected' : '') Query Helpers
                         li.pure-menu-item.sub-item
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/populate.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/populate.html` ? 'selected' : '') Populate
+                        li.pure-menu-item.sub-item
+                          a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/virtuals.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/virtuals.html` ? 'selected' : '') Virtuals
                         li.pure-menu-item.sub-item
                           a.pure-menu-link(href=`${versions.versionedPath}/docs/typescript/subdocuments.html`, class=outputUrl === `${versions.versionedPath}/docs/typescript/subdocuments.html` ? 'selected' : '') Subdocuments
               li.pure-menu-item

docs/migrating_to_7.md

@@ -11,6 +11,7 @@ you should be aware of when migrating from Mongoose 6.x to Mongoose 7.x.
 
 If you're still on Mongoose 5.x, please read the [Mongoose 5.x to 6.x migration guide](migrating_to_6.html) and upgrade to Mongoose 6.x first.
 
+* [Version Requirements](#version-requirements)
 * [`strictQuery`](#strictquery)
 * [Removed `remove()`](#removed-remove)
 * [Dropped callback support](#dropped-callback-support)
@@ -28,6 +29,12 @@ If you're still on Mongoose 5.x, please read the [Mongoose 5.x to 6.x migration
   * [Removed `LeanDocument` and support for `extends Document`](#removed-leandocument-and-support-for-extends-document)
   * [New parameters for `HydratedDocument`](#new-parameters-for-hydrateddocument)
 
+## Version Requirements {#version-requirements}
+
+Mongoose now requires Node.js >= 14.0.0 and MongoDB Node Driver >= 5.0.0.
+
+See [the MongoDB Node Driver migration guide](https://github.com/mongodb/node-mongodb-native/blob/main/etc/notes/CHANGES_5.0.0.md) for detailed info.
+
 ## `strictQuery` {#strictquery}
 
 `strictQuery` is now false by default.

docs/typescript/queries.md

@@ -0,0 +1,41 @@
+# Queries in TypeScript
+
+Mongoose's [Query class](../api/query.html) is a chainable query builder that represents a MongoDB query.
+When you call `find()`, `findOne()`, `updateOne()`, `findOneAndUpdate()`, etc. on a model, Mongoose will return a Query instance.
+Queries have a `.then()` function that returns a Promise, so you can use them with `await`.
+
+In TypeScript, the Query class takes the following generic parameters:
+
+```ts
+class Query<
+  ResultType, // The type of the result of the query, like `DocType[]`
+  DocType, // The hydrated document type of the query's associated model
+  THelpers = {}, // Query helpers
+  RawDocType = unknown, // The "lean" document type of the query's associated model
+  QueryOp = 'find', // The operation that will be executed, like 'find', 'findOne', 'updateOne', etc.
+  TDocOverrides = Record<string, never> // Methods and virtuals on the hydrated document
+>
+```
+
+## Using `lean()` in TypeScript
+
+The [`lean()` method](../tutorials/lean.html) tells Mongoose to skip [hydrating](../api/model.html#model_Model-hydrate) the result documents, making queries faster and more memory efficient.
+`lean()` comes with some caveats in TypeScript when working with the query `transform()` function.
+In general, we recommend calling `lean()` before using the `transform()` function to ensure accurate types.
+
+```ts
+// Put `lean()` **before** `transform()` in TypeScript because `transform` modifies the query ResultType into a shape
+// that `lean()` does not know how to handle.
+const result = await ProjectModel
+  .find()
+  .lean()
+  .transform((docs) => new Map(docs.map((doc) => [doc._id.toString(), doc])));
+
+// Do **not** do the following
+const result = await ProjectModel
+  .find()
+  .transform((docs) => new Map(docs.map((doc) => [doc._id.toString(), doc])))
+  .lean();
+```
+
+In general, if you're having trouble with `lean()` inferring the correct type, you can try moving `lean()` earlier in the query chain.

docs/typescript/virtuals.md

@@ -72,9 +72,9 @@ interface UserVirtuals {
   fullName: string;
 }
 
-type UserModel = Model<UserDoc, {}, UserVirtuals>; // <-- add virtuals here...
+type UserModel = Model<UserDoc, {}, {}, UserVirtuals>; // <-- add virtuals here...
 
-const schema = new Schema<UserDoc, UserModel, UserVirtuals>({ // <-- and here
+const schema = new Schema<UserDoc, UserModel, {}, {}, UserVirtuals>({ // <-- and here
   firstName: String,
   lastName: String
 });

lib/document.js

@@ -2620,7 +2620,6 @@ Document.prototype.validate = async function validate(pathsToValidate, options)
   if (typeof pathsToValidate === 'function' || typeof options === 'function' || typeof arguments[2] === 'function') {
     throw new MongooseError('Document.prototype.validate() no longer accepts a callback');
   }
-  let parallelValidate;
   this.$op = 'validate';
 
   if (arguments.length === 1) {
@@ -2638,16 +2637,9 @@ Document.prototype.validate = async function validate(pathsToValidate, options)
   if (this.$isSubdocument != null) {
     // Skip parallel validate check for subdocuments
   } else if (this.$__.validating && !_skipParallelValidateCheck) {
-    parallelValidate = new ParallelValidateError(this, {
-      parentStack: options && options.parentStack,
-      conflictStack: this.$__.validating.stack
-    });
+    throw new ParallelValidateError(this);
   } else if (!_skipParallelValidateCheck) {
-    this.$__.validating = new ParallelValidateError(this, { parentStack: options && options.parentStack });
-  }
-
-  if (parallelValidate != null) {
-    throw parallelValidate;
+    this.$__.validating = true;
   }
 
   return new Promise((resolve, reject) => {
@@ -3818,6 +3810,8 @@ Document.prototype.$toObject = function(options, json) {
   let _minimize;
   if (options._calledWithOptions.minimize != null) {
     _minimize = options.minimize;
+  } else if (this.$__schemaTypeOptions?.minimize != null) {
+    _minimize = this.$__schemaTypeOptions.minimize;
   } else if (defaultOptions != null && defaultOptions.minimize != null) {
     _minimize = defaultOptions.minimize;
   } else {

lib/error/index.js

@@ -65,32 +65,32 @@ MongooseError.messages = require('./messages');
 MongooseError.Messages = MongooseError.messages;
 
 /**
- * An instance of this error class will be returned when `save()` fails
- * because the underlying
- * document was not found. The constructor takes one parameter, the
- * conditions that mongoose passed to `updateOne()` when trying to update
- * the document.
+ * An instance of this error class will be thrown when mongoose failed to
+ * cast a value.
  *
  * @api public
  * @memberOf Error
  * @static
  */
 
-MongooseError.DocumentNotFoundError = require('./notFound');
+MongooseError.CastError = require('./cast');
 
 /**
- * An instance of this error class will be returned when mongoose failed to
- * cast a value.
+ * An instance of this error class will be thrown when `save()` fails
+ * because the underlying
+ * document was not found. The constructor takes one parameter, the
+ * conditions that mongoose passed to `updateOne()` when trying to update
+ * the document.
  *
  * @api public
  * @memberOf Error
  * @static
  */
 
-MongooseError.CastError = require('./cast');
+MongooseError.DocumentNotFoundError = require('./notFound');
 
 /**
- * An instance of this error class will be returned when [validation](https://mongoosejs.com/docs/validation.html) failed.
+ * An instance of this error class will be thrown when [validation](https://mongoosejs.com/docs/validation.html) failed.
  * The `errors` property contains an object whose keys are the paths that failed and whose values are
  * instances of CastError or ValidationError.
  *
@@ -137,7 +137,7 @@ MongooseError.ValidationError = require('./validation');
 MongooseError.ValidatorError = require('./validator');
 
 /**
- * An instance of this error class will be returned when you call `save()` after
+ * An instance of this error class will be thrown when you call `save()` after
  * the document in the database was changed in a potentially unsafe way. See
  * the [`versionKey` option](https://mongoosejs.com/docs/guide.html#versionKey) for more information.
  *
@@ -149,7 +149,7 @@ MongooseError.ValidatorError = require('./validator');
 MongooseError.VersionError = require('./version');
 
 /**
- * An instance of this error class will be returned when you call `save()` multiple
+ * An instance of this error class will be thrown when you call `save()` multiple
  * times on the same document in parallel. See the [FAQ](https://mongoosejs.com/docs/faq.html) for more
  * information.
  *
@@ -181,6 +181,16 @@ MongooseError.OverwriteModelError = require('./overwriteModel');
 
 MongooseError.MissingSchemaError = require('./missingSchema');
 
+/**
+ * Thrown when some documents failed to save when calling `bulkSave()`
+ *
+ * @api public
+ * @memberOf Error
+ * @static
+ */
+
+MongooseError.MongooseBulkSaveIncompleteError = require('./bulkSaveIncompleteError');
+
 /**
  * Thrown when the MongoDB Node driver can't connect to a valid server
  * to send an operation to.
@@ -193,7 +203,7 @@ MongooseError.MissingSchemaError = require('./missingSchema');
 MongooseError.MongooseServerSelectionError = require('./serverSelection');
 
 /**
- * An instance of this error will be returned if you used an array projection
+ * An instance of this error will be thrown if you used an array projection
  * and then modified the array in an unsafe way.
  *
  * @api public

lib/helpers/clone.js

@@ -57,7 +57,6 @@ function clone(obj, options, isArrayChild) {
         return clonedDoc;
       }
     }
-    const isSingleNested = obj.$isSingleNested;
 
     if (isPOJO(obj) && obj.$__ != null && obj._doc != null) {
       return obj._doc;
@@ -70,10 +69,6 @@ function clone(obj, options, isArrayChild) {
       ret = obj.toObject(options);
     }
 
-    if (options && options.minimize && !obj.constructor.$__required && isSingleNested && Object.keys(ret).length === 0) {
-      return undefined;
-    }
-
     return ret;
   }