mongoose 9.6.2 → 9.7.0

package/README.md

@@ -96,6 +96,10 @@ You can then run the above script using the following.
 deno run --allow-net --allow-read --allow-sys --allow-env mongoose-test.js
 ```
 
+## Mongoose Studio
+
+[Mongoose Studio](https://mongoosestudio.app?utm_source=mongoose&utm_medium=referral&utm_campaign=readme) is a free, fully open-source, browser-based MongoDB GUI built by the Mongoose team for apps that already use Mongoose. Install `@mongoosejs/studio` from npm and run it alongside your app as Express middleware, or deploy it on Vercel or Netlify, to browse and edit documents, query with your existing models and schemas with autocomplete, build dashboards, visualize and edit GeoJSON, and use AI-assisted MongoDB workflows without moving data into a hosted third-party workspace or sharing raw MongoDB connection strings.
+
 ## Mongoose for Enterprise
 
 Available as part of the Tidelift Subscription
@@ -172,8 +176,6 @@ Comment.pre('save', function(next) {
 });
 ```
 
-Take a look at the example in [`examples/schema/schema.js`](https://github.com/Automattic/mongoose/blob/master/examples/schema/schema.js) for an end-to-end example of a typical setup.
-
 ### Accessing a Model
 
 Once we define a model through `mongoose.model('ModelName', mySchema)`, we can access it through the same function

package/lib/aggregate.js

@@ -15,6 +15,8 @@ const { buildMiddlewareFilter } = require('./helpers/buildMiddlewareFilter');
 const stringifyFunctionOperators = require('./helpers/aggregate/stringifyFunctionOperators');
 const utils = require('./utils');
 const { modelSymbol } = require('./helpers/symbols');
+const { createTracedChannel } = require('./tracing');
+const { trace: traceAggregate } = createTracedChannel('mongoose:aggregate');
 const read = Query.prototype.read;
 const readConcern = Query.prototype.readConcern;
 
@@ -1032,7 +1034,7 @@ Aggregate.prototype.pipeline = function() {
  *     const base = MyModel.aggregate().match({ test: 1 });
  *     base.pipelineForUnionWith(); // [{ $match: { test: 1 } }]
  *
- * @return {Array} The current pipeline with `$unionWith` stage restrictions
+ * @return {PipelineStage[]} The current pipeline with `$unionWith` stage restrictions
  * @api public
  */
 
@@ -1071,8 +1073,20 @@ Aggregate.prototype.exec = async function exec() {
 
     this._optionsForExec();
 
-    const cursor = await this._connection.client.db().aggregate(this._pipeline, this.options);
-    return await cursor.toArray();
+    const _this = this;
+    return traceAggregate(async function maybeTracedConnectionAggregate() {
+      const cursor = await _this._connection.client.db().aggregate(_this._pipeline, _this.options);
+      return await cursor.toArray();
+    }, () => ({
+      operation: 'aggregate',
+      database: _this._connection.name,
+      serverAddress: _this._connection.host,
+      serverPort: _this._connection.port,
+      args: {
+        pipeline: _this._pipeline,
+        options: _this.options
+      }
+    }));
   }
 
   const model = this._model;
@@ -1090,32 +1104,45 @@ Aggregate.prototype.exec = async function exec() {
   prepareDiscriminatorPipeline(this._pipeline, this._model.schema);
   stringifyFunctionOperators(this._pipeline);
 
-  const preFilter = buildMiddlewareFilter(this.options, 'pre');
-  const postFilter = buildMiddlewareFilter(this.options, 'post');
+  const _this = this;
+  return traceAggregate(async function maybeTracedAggregateExec() {
+    const preFilter = buildMiddlewareFilter(_this.options, 'pre');
+    const postFilter = buildMiddlewareFilter(_this.options, 'post');
 
-  try {
-    await model.hooks.execPre('aggregate', this, [], { filter: preFilter });
-  } catch (error) {
-    return await model.hooks.execPost('aggregate', this, [null], { error, filter: postFilter });
-  }
+    try {
+      await model.hooks.execPre('aggregate', _this, [], { filter: preFilter });
+    } catch (error) {
+      return await model.hooks.execPost('aggregate', _this, [null], { error, filter: postFilter });
+    }
 
-  if (!this._pipeline.length) {
-    throw new MongooseError('Aggregate has empty pipeline');
-  }
+    if (!_this._pipeline.length) {
+      throw new MongooseError('Aggregate has empty pipeline');
+    }
 
-  const options = clone(this.options || {});
-  delete options.middleware;
+    const options = clone(_this.options || {});
+    delete options.middleware;
 
-  let result;
-  try {
-    const cursor = await collection.aggregate(this._pipeline, options);
-    result = await cursor.toArray();
-  } catch (error) {
-    return await model.hooks.execPost('aggregate', this, [null], { error, filter: postFilter });
-  }
+    let result;
+    try {
+      const cursor = await collection.aggregate(_this._pipeline, options);
+      result = await cursor.toArray();
+    } catch (error) {
+      return await model.hooks.execPost('aggregate', _this, [null], { error, filter: postFilter });
+    }
 
-  await model.hooks.execPost('aggregate', this, [result], { error: null, filter: postFilter });
-  return result;
+    await model.hooks.execPost('aggregate', _this, [result], { error: null, filter: postFilter });
+    return result;
+  }, () => ({
+    operation: 'aggregate',
+    collection: collection.name,
+    database: model.db?.name,
+    serverAddress: model.db?.host,
+    serverPort: model.db?.port,
+    args: {
+      pipeline: _this._pipeline,
+      options: _this.options
+    }
+  }));
 };
 
 /**

package/lib/connection.js

@@ -1354,7 +1354,7 @@ Connection.prototype.onClose = function onClose(force) {
 
 /**
  * Retrieves a raw collection instance, creating it if not cached.
- * This method returns a thin wrapper around a [MongoDB Node.js driver collection]([MongoDB Node.js driver collection](https://mongodb.github.io/node-mongodb-native/Next/classes/Collection.html)).
+ * This method returns a thin wrapper around a [MongoDB Node.js driver collection](https://mongodb.github.io/node-mongodb-native/Next/classes/Collection.html).
  * Using a Collection bypasses Mongoose middleware, validation, and casting,
  * letting you use [MongoDB Node.js driver](https://mongodb.github.io/node-mongodb-native/) functionality directly.
  *

package/lib/cursor/aggregationCursor.js

@@ -10,6 +10,7 @@ const eachAsync = require('../helpers/cursor/eachAsync');
 const immediate = require('../helpers/immediate');
 const kareem = require('kareem');
 const util = require('util');
+const { cursorNextChannel } = require('../tracing');
 
 /**
  * An AggregationCursor is a concurrency primitive for processing aggregation
@@ -62,13 +63,7 @@ util.inherits(AggregationCursor, Readable);
  */
 
 function _init(model, c, agg) {
-  if (!model.collection.buffer) {
-    model.hooks.execPre('aggregate', agg).then(() => onPreComplete(null), err => onPreComplete(err));
-  } else {
-    model.collection.emitter.once('queue', function() {
-      model.hooks.execPre('aggregate', agg).then(() => onPreComplete(null), err => onPreComplete(err));
-    });
-  }
+  model.hooks.execPre('aggregate', agg).then(() => onPreComplete(null), err => onPreComplete(err));
 
   function onPreComplete(err) {
     if (err != null) {
@@ -79,8 +74,28 @@ function _init(model, c, agg) {
       c._transforms.push(agg.options.cursor.transform);
     }
 
-    c.cursor = model.collection.aggregate(agg._pipeline, agg.options || {});
-    c.emit('cursor', c.cursor);
+    if (model.collection._shouldBufferCommands() && model.collection.buffer) {
+      model.collection.queue.push([
+        () => _getRawCursor(model, c, agg)
+      ]);
+    } else {
+      _getRawCursor(model, c, agg);
+    }
+  }
+}
+
+/*!
+ * ignore
+ */
+
+function _getRawCursor(model, aggregationCursor, agg) {
+  try {
+    const cursor = model.collection.aggregate(agg._pipeline, agg.options || {});
+    aggregationCursor.cursor = cursor;
+    aggregationCursor.emit('cursor', cursor);
+  } catch (err) {
+    aggregationCursor._markError(err);
+    aggregationCursor.listeners('error').length > 0 && aggregationCursor.emit('error', aggregationCursor._error);
   }
 }
 
@@ -277,14 +292,30 @@ AggregationCursor.prototype.next = async function next() {
   if (typeof arguments[0] === 'function') {
     throw new MongooseError('AggregationCursor.prototype.next() no longer accepts a callback');
   }
-  return new Promise((resolve, reject) => {
-    _next(this, (err, res) => {
-      if (err != null) {
-        return reject(err);
-      }
-      resolve(res);
+  const _this = this;
+  const model = this.agg._model;
+  return cursorNextChannel.trace(function maybeTracedAggCursorNext() {
+    return new Promise((resolve, reject) => {
+      _next(_this, (err, res) => {
+        if (err != null) {
+          return reject(err);
+        }
+        resolve(res);
+      });
     });
-  });
+  }, () => ({
+    operation: 'aggregate',
+    collection: model?.collection?.name,
+    database: model?.db?.name,
+    serverAddress: model?.db?.host,
+    serverPort: model?.db?.port,
+    batchSize: _this.agg.options?.cursor?.batchSize,
+    tailable: false,
+    args: {
+      pipeline: _this.agg._pipeline,
+      options: _this.agg.options
+    }
+  }));
 };
 
 /**

package/lib/cursor/queryCursor.js

@@ -12,6 +12,7 @@ const kareem = require('kareem');
 const immediate = require('../helpers/immediate');
 const { once } = require('events');
 const util = require('util');
+const { cursorNextChannel } = require('../tracing');
 
 /**
  * A QueryCursor is a concurrency primitive for processing query results
@@ -310,14 +311,29 @@ QueryCursor.prototype.next = async function next() {
   if (this._closed) {
     throw new MongooseError('Cannot call `next()` on a closed cursor');
   }
-  return new Promise((resolve, reject) => {
-    _next(this, function(error, doc) {
-      if (error) {
-        return reject(error);
-      }
-      resolve(doc);
+  const _this = this;
+  return cursorNextChannel.trace(function maybeTracedQueryCursorNext() {
+    return new Promise((resolve, reject) => {
+      _next(_this, function(error, doc) {
+        if (error) {
+          return reject(error);
+        }
+        resolve(doc);
+      });
     });
-  });
+  }, () => ({
+    operation: _this.query.op || 'find',
+    collection: _this.query.mongooseCollection.name,
+    database: _this.model.db?.name,
+    serverAddress: _this.model.db?.host,
+    serverPort: _this.model.db?.port,
+    batchSize: _this.options.batchSize || _this.query.options?.batchSize,
+    tailable: _this.options.tailable || _this.query.options?.tailable || false,
+    args: {
+      filter: _this.query.getFilter(),
+      options: _this.query._mongooseOptions
+    }
+  }));
 };
 
 /**

package/lib/document.js

@@ -3264,6 +3264,9 @@ function _handlePathsToSkip(paths, pathsToSkip) {
 /**
  * Executes registered validation rules (skipping asynchronous validators) for this document.
  *
+ * **Deprecated.** Use [`validate()`](https://mongoosejs.com/docs/api/document.html#Document.prototype.validate()) instead.
+ * `validateSync()` does not run validation middleware and will be removed in Mongoose 10.
+ *
  * #### Note:
  *
  * This method is useful if you need synchronous validation.
@@ -3281,14 +3284,21 @@ function _handlePathsToSkip(paths, pathsToSkip) {
  * @param {object} [options] options for validation
  * @param {boolean} [options.validateModifiedOnly=false] If `true`, Mongoose will only validate modified paths, as opposed to modified paths and `required` paths.
  * @param {Array|string} [options.pathsToSkip] list of paths to skip. If set, Mongoose will validate every modified path that is not in this list.
- * @param {boolean|object} [options.middleware=true] set to `false` to skip all user-defined middleware
- * @param {boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
- * @param {boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @return {ValidationError|undefined} ValidationError if there are errors during validation, or undefined if there is no error.
+ * @deprecated Use `validate()` instead. `validateSync()` does not run middleware and will be removed in Mongoose 10.
  * @api public
  */
 
-Document.prototype.validateSync = function(pathsToValidate, options) {
+Document.prototype.validateSync = function() {
+  utils.warn('Mongoose: `Document.prototype.validateSync()` is deprecated and will be removed in Mongoose 10. Use `Document.prototype.validate()` instead.');
+  return this.$__validateSync.apply(this, arguments);
+};
+
+/*!
+ * ignore
+ */
+
+Document.prototype.$__validateSync = function(pathsToValidate, options) {
   const _this = this;
 
   if (arguments.length === 1 && typeof arguments[0] === 'object' && !Array.isArray(arguments[0])) {
@@ -5266,6 +5276,12 @@ function checkDivergentArray(doc, path, array) {
     // If any array was selected using an $elemMatch projection, we deny the update.
     // NOTE: MongoDB only supports projected $elemMatch on top level array.
     const top = path.split('.')[0];
+    if (doc.$__.selected[top] && doc.$__.selected[top].$slice != null && utils.isMongooseArray(array)) {
+      const atomics = array[arrayAtomicsSymbol];
+      if (atomics.$set) {
+        return top;
+      }
+    }
     if (doc.$__.selected[top + '.$']) {
       return top;
     }

package/lib/error/divergentArray.js

@@ -17,7 +17,7 @@ class DivergentArrayError extends MongooseError {
 
   constructor(paths) {
     const msg = 'For your own good, using `document.save()` to update an array '
-            + 'which was selected using an $elemMatch projection OR '
+            + 'which was selected using an $elemMatch or $slice projection OR '
             + 'populated using skip, limit, query conditions, or exclusion of '
             + 'the _id field when the operation results in a $pop or $set of '
             + 'the entire array is not supported. The following '

package/lib/helpers/clone.js

@@ -202,10 +202,15 @@ function cloneArray(arr, options) {
 
   let ret = null;
   if (options?.retainDocuments) {
+    // Use the cloned parent doc (options.parentDoc) when available so the new
+    // array is wired up to the clone, not the source. Falling back to the
+    // source's parent preserves the previous behavior for callers that don't
+    // pass parentDoc.
+    const newParent = options.parentDoc ?? (arr.isMongooseArray ? arr.$parent() : undefined);
     if (arr.isMongooseDocumentArray) {
-      ret = new (arr.$schemaType().schema.base.Types.DocumentArray)([], arr.$path(), arr.$parent(), arr.$schemaType());
+      ret = new (arr.$schemaType().schema.base.Types.DocumentArray)([], arr.$path(), newParent, arr.$schemaType());
     } else if (arr.isMongooseArray) {
-      ret = new (arr.$parent().schema.base.Types.Array)([], arr.$path(), arr.$parent(), arr.$schemaType());
+      ret = new (arr.$parent().schema.base.Types.Array)([], arr.$path(), newParent, arr.$schemaType());
     } else {
       ret = new Array(len);
     }
@@ -218,9 +223,21 @@ function cloneArray(arr, options) {
     // Create new options object to avoid mutating the shared options.
     // Subdocs need parentArray to point to their own cloned array.
     options = { ...options, parentArray: ret };
-  }
-  for (i = 0; i < len; ++i) {
-    ret[i] = clone(arr[i], options, true);
+    // Skip change-tracking while populating the freshly cloned array: every
+    // index assignment would otherwise call markModified on the cloned parent
+    // doc and (before this guard) on the source parent doc.
+    for (i = 0; i < len; ++i) {
+      const doc = clone(arr[i], options, true);
+      // Document arrays can contain null entries, so only restamp actual subdocs.
+      if (typeof doc?.$setIndex === 'function') {
+        doc.$setIndex(i);
+      }
+      ret.set(i, doc, true);
+    }
+  } else {
+    for (i = 0; i < len; ++i) {
+      ret[i] = clone(arr[i], options, true);
+    }
   }
 
   return ret;

package/lib/helpers/populate/getModelsMapForPopulate.js

@@ -873,7 +873,11 @@ function _findRefPathForDiscriminators(doc, modelSchema, data, options, normaliz
 }
 
 /**
- * Throw an error if there are any $where keys
+ * Throw an error if there are any $where keys to defend against [CVE-2024-53900](https://nvd.nist.gov/vuln/detail/CVE-2024-53900)
+ *
+ * Note that this is ONLY for $where because sift executes $where in Node.js memory.
+ * Other forms of MongoDB server-side execution, like $expr, are NOT filtered out.
+ * This function is not meant to protect against server-side execution in MongoDB.
  */
 
 function throwOn$where(match) {

package/lib/helpers/update/applyTimestampsToUpdate.js

@@ -82,7 +82,9 @@ function applyTimestampsToUpdate(now, createdAt, updatedAt, currentUpdate, optio
 
   if (!skipCreatedAt && createdAt) {
     const overwriteImmutable = get(options, 'overwriteImmutable', false);
-    const hasUserCreatedAt = currentUpdate[createdAt] != null || currentUpdate.$set?.[createdAt] != null;
+    const hasUserCreatedAt = currentUpdate[createdAt] != null
+      || currentUpdate.$set?.[createdAt] != null
+      || currentUpdate.$setOnInsert?.[createdAt] != null;
 
     // If overwriteImmutable is true and user provided createdAt, keep their value
     if (overwriteImmutable && hasUserCreatedAt) {
@@ -91,7 +93,7 @@ function applyTimestampsToUpdate(now, createdAt, updatedAt, currentUpdate, optio
         updates.$set[createdAt] = currentUpdate[createdAt];
         delete currentUpdate[createdAt];
       }
-      // User's value is already in $set, nothing more to do
+      // User's value is already in $set or $setOnInsert, nothing more to do
     } else {
       if (currentUpdate[createdAt]) {
         delete currentUpdate[createdAt];

package/lib/model.js

@@ -7,6 +7,10 @@
 const Aggregate = require('./aggregate');
 const ChangeStream = require('./cursor/changeStream');
 const Document = require('./document');
+const { createTracedChannel } = require('./tracing');
+const { trace: traceSave } = createTracedChannel('mongoose:model:save');
+const { trace: traceInsertMany } = createTracedChannel('mongoose:model:insertMany');
+const { trace: traceBulkWrite } = createTracedChannel('mongoose:model:bulkWrite');
 const DocumentNotFoundError = require('./error/notFound');
 const EventEmitter = require('events').EventEmitter;
 const Kareem = require('kareem');
@@ -37,6 +41,7 @@ const applyVirtualsHelper = require('./helpers/document/applyVirtuals');
 const assignVals = require('./helpers/populate/assignVals');
 const castBulkWrite = require('./helpers/model/castBulkWrite');
 const clone = require('./helpers/clone');
+const convertErrorToStandardSchemaIssues = require('./standardSchema/convertErrorToIssues');
 const createPopulateQueryFilter = require('./helpers/populate/createPopulateQueryFilter');
 const decorateUpdateWithVersionKey = require('./helpers/update/decorateUpdateWithVersionKey');
 const getDefaultBulkwriteResult = require('./helpers/getDefaultBulkwriteResult');
@@ -663,19 +668,29 @@ Model.prototype.save = async function save(options) {
 
   this.$__.saveOptions = options;
 
-  try {
-    await this.$__save(options);
-  } catch (error) {
-    this.$__handleReject(error);
-    throw error;
-  } finally {
-    this.$__.saving = null;
-    this.$__.saveOptions = null;
-    this.$__.$versionError = null;
-    this.$op = null;
-  }
-
-  return this;
+  const _this = this;
+  return traceSave(async function maybeTracedSave() {
+    try {
+      await _this.$__save(options);
+    } catch (error) {
+      _this.$__handleReject(error);
+      throw error;
+    } finally {
+      _this.$__.saving = null;
+      _this.$__.saveOptions = null;
+      _this.$__.$versionError = null;
+      _this.$op = null;
+    }
+
+    return _this;
+  }, () => ({
+    operation: 'save',
+    collection: _this.constructor.collection.name,
+    database: _this.constructor.db?.name,
+    serverAddress: _this.constructor.db?.host,
+    serverPort: _this.constructor.db?.port,
+    args: { options }
+  }));
 };
 
 Model.prototype.$save = Model.prototype.save;
@@ -3015,6 +3030,18 @@ Model.insertMany = async function insertMany(arr, options) {
     throw new MongooseError('Model.insertMany() no longer accepts a callback');
   }
 
+  const ThisModel = this;
+  return traceInsertMany(function maybeTracedInsertMany() { return _insertMany.call(ThisModel, arr, options); }, () => ({
+    operation: 'insertMany',
+    collection: ThisModel.collection.name,
+    database: ThisModel.db?.name,
+    serverAddress: ThisModel.db?.host,
+    serverPort: ThisModel.db?.port,
+    args: { docs: arr, options }
+  }));
+};
+
+async function _insertMany(arr, options) {
   options = options || {};
   const preFilter = buildMiddlewareFilter(options, 'pre');
   const postFilter = buildMiddlewareFilter(options, 'post');
@@ -3250,7 +3277,7 @@ Model.insertMany = async function insertMany(arr, options) {
 
   const [result] = await this._middleware.execPost('insertMany', this, [docAttributes], { filter: postFilter });
   return result;
-};
+}
 
 /*!
  * ignore
@@ -3378,6 +3405,19 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
       typeof arguments[2] === 'function') {
     throw new MongooseError('Model.bulkWrite() no longer accepts a callback');
   }
+
+  const ThisModel = this;
+  return traceBulkWrite(function maybeTracedBulkWrite() { return _bulkWrite.call(ThisModel, ops, options); }, () => ({
+    operation: 'bulkWrite',
+    collection: ThisModel.collection.name,
+    database: ThisModel.db?.name,
+    serverAddress: ThisModel.db?.host,
+    serverPort: ThisModel.db?.port,
+    args: { ops, options }
+  }));
+};
+
+async function _bulkWrite(ops, options) {
   options = options || {};
   const preFilter = buildMiddlewareFilter(options, 'pre');
   const postFilter = buildMiddlewareFilter(options, 'post');
@@ -3516,7 +3556,7 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
   await this.hooks.execPost('bulkWrite', this, [res], { filter: postFilter });
 
   return res;
-};
+}
 
 /**
  * Takes an array of documents, gets the changes and inserts/updates documents in the database
@@ -3861,7 +3901,7 @@ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, op
         throw new MongooseError(`documents.${i} was not a mongoose document, documents must be an array of mongoose documents (instanceof mongoose.Document).`);
       }
       if (options.validateBeforeSave == null || options.validateBeforeSave) {
-        const err = document.validateSync();
+        const err = document.$__validateSync();
         if (err != null) {
           throw err;
         }
@@ -4188,13 +4228,24 @@ Model.aggregate = function aggregate(pipeline, options) {
  *       age: { type: Number, required: true }
  *     });
  *
+ *     // Succeeds
+ *     await Model.validate({ name: 'John Smith', age: 31 });
+ *
  *     try {
- *       await Model.validate({ name: null }, ['name'])
+ *       await Model.validate({ name: null });
  *     } catch (err) {
  *       err instanceof mongoose.Error.ValidationError; // true
  *       Object.keys(err.errors); // ['name']
  *     }
  *
+ * Note: the `pathsToSkip` and `pathsToValidate` options **only** apply to validation, not
+ * casting. This function will still throw an error for values that cannot be casted to the
+ * schema-specified type. Remove any paths you do not want to cast.
+ *
+ *     // The following will still throw an error because the value of `age` cannot be
+ *     // casted to a number. Remove the `age` property before calling `validate()`.
+ *     await Model.validate({ name: 'Test', age: 'not a number' }, ['name']);
+ *
  * @param {object} obj
  * @param {object|Array|string} pathsOrOptions
  * @param {object} [context]
@@ -4299,6 +4350,33 @@ Model.validate = async function validate(obj, pathsOrOptions, context) {
   return obj;
 };
 
+/**
+ * Standard Schema adapter for this model.
+ * Calls [`Model.validate()`](https://mongoosejs.com/docs/api/model.html#Model.validate()) internally with the provided `libraryOptions`
+ * to cast and validate the given value.
+ *
+ * @api public
+ * @property ~standard
+ * @memberOf Model
+ * @static
+ */
+
+Object.defineProperty(Model, '~standard', {
+  configurable: true,
+  get() {
+    return {
+      version: 1,
+      vendor: 'mongoose',
+      validate: (value, options) => {
+        return this.validate(value, options?.libraryOptions).then(
+          value => ({ value }),
+          error => ({ issues: convertErrorToStandardSchemaIssues(error) })
+        );
+      }
+    };
+  }
+});
+
 /**
  * Populates document references.
  *

package/lib/mongoose.js

@@ -398,8 +398,8 @@ Mongoose.prototype.get = Mongoose.prototype.set;
  * @param {string} [options.user] username for authentication, equivalent to `options.auth.username`. Maintained for backwards compatibility.
  * @param {string} [options.pass] password for authentication, equivalent to `options.auth.password`. Maintained for backwards compatibility.
  * @param {boolean} [options.autoIndex=true] Mongoose-specific option. Set to false to disable automatic index creation for all models associated with this connection.
- * @param {number} [options.maxPoolSize=5] The maximum number of sockets the MongoDB driver will keep open for this connection. Keep in mind that MongoDB only allows one operation per socket at a time, so you may want to increase this if you find you have a few slow queries that are blocking faster queries from proceeding. See [Slow Trains in MongoDB and Node.js](https://thecodebarbarian.com/slow-trains-in-mongodb-and-nodejs).
- * @param {number} [options.minPoolSize=1] The minimum number of sockets the MongoDB driver will keep open for this connection. Keep in mind that MongoDB only allows one operation per socket at a time, so you may want to increase this if you find you have a few slow queries that are blocking faster queries from proceeding. See [Slow Trains in MongoDB and Node.js](https://thecodebarbarian.com/slow-trains-in-mongodb-and-nodejs).
+ * @param {number} [options.maxPoolSize=100] The maximum number of sockets the MongoDB driver will keep open for this connection. Keep in mind that MongoDB only allows one operation per socket at a time, so you may want to increase this if you find you have a few slow queries that are blocking faster queries from proceeding. See [Slow Trains in MongoDB and Node.js](https://thecodebarbarian.com/slow-trains-in-mongodb-and-nodejs).
+ * @param {number} [options.minPoolSize=0] The minimum number of sockets the MongoDB driver will keep open for this connection. Keep in mind that MongoDB only allows one operation per socket at a time, so you may want to increase this if you find you have a few slow queries that are blocking faster queries from proceeding. See [Slow Trains in MongoDB and Node.js](https://thecodebarbarian.com/slow-trains-in-mongodb-and-nodejs).
  * @param {number} [options.socketTimeoutMS=0] How long the MongoDB driver will wait before killing a socket due to inactivity _after initial connection_. Defaults to 0, which means Node.js will not time out the socket due to inactivity. A socket may be inactive because of either no activity or a long-running operation. This option is passed to [Node.js `socket#setTimeout()` function](https://nodejs.org/api/net.html#net_socket_settimeout_timeout_callback) after the MongoDB driver successfully completes.
  * @param {number} [options.family=0] Passed transparently to [Node.js' `dns.lookup()`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) function. May be either `0`, `4`, or `6`. `4` means use IPv4 only, `6` means use IPv6 only, `0` means try both.
  * @return {Connection} the created Connection object. Connections are not thenable, so you can't do `await mongoose.createConnection()`. To await use `mongoose.createConnection(uri).asPromise()` instead.

package/lib/query.js

@@ -42,6 +42,8 @@ const updateValidators = require('./helpers/updateValidators');
 const util = require('util');
 const utils = require('./utils');
 const queryMiddlewareFunctions = require('./constants').queryMiddlewareFunctions;
+const { createTracedChannel } = require('./tracing');
+const { trace: traceQuery } = createTracedChannel('mongoose:query');
 
 const queryOptionMethods = new Set([
   'allowDiskUse',
@@ -4778,42 +4780,56 @@ Query.prototype.exec = async function exec(op) {
   }
   this._execCount++;
 
-  let skipWrappedFunction = null;
-  try {
-    await this._hooks.execPre('exec', this, []);
-  } catch (err) {
-    if (err instanceof Kareem.skipWrappedFunction) {
-      skipWrappedFunction = err;
-    } else {
-      throw err;
+  const _this = this;
+  return traceQuery(async function maybeTracedQueryExec() {
+    let skipWrappedFunction = null;
+    try {
+      await _this._hooks.execPre('exec', _this, []);
+    } catch (err) {
+      if (err instanceof Kareem.skipWrappedFunction) {
+        skipWrappedFunction = err;
+      } else {
+        throw err;
+      }
     }
-  }
 
-  let res;
+    let res;
 
-  let error = null;
-  try {
-    await _executePreHooks(this);
-    res = skipWrappedFunction ? skipWrappedFunction.args[0] : await this[thunk]();
+    let error = null;
+    try {
+      await _executePreHooks(_this);
+      res = skipWrappedFunction ? skipWrappedFunction.args[0] : await _this[thunk]();
 
-    for (const fn of this._transforms) {
-      res = fn(res);
-    }
-  } catch (err) {
-    if (err instanceof Kareem.skipWrappedFunction) {
-      res = err.args[0];
-    } else {
-      error = err;
-    }
+      for (const fn of _this._transforms) {
+        res = fn(res);
+      }
+    } catch (err) {
+      if (err instanceof Kareem.skipWrappedFunction) {
+        res = err.args[0];
+      } else {
+        error = err;
+      }
 
-    error = this.model.schema._transformDuplicateKeyError(error);
-  }
+      error = _this.model.schema._transformDuplicateKeyError(error);
+    }
 
-  res = await _executePostHooks(this, res, error);
+    res = await _executePostHooks(_this, res, error);
 
-  await this._hooks.execPost('exec', this, []);
+    await _this._hooks.execPost('exec', _this, []);
 
-  return res;
+    return res;
+  }, () => ({
+    operation: _this.op,
+    collection: _this.mongooseCollection.name,
+    database: _this.model.db?.name,
+    serverAddress: _this.model.db?.host,
+    serverPort: _this.model.db?.port,
+    args: {
+      filter: _this.getFilter(),
+      fields: _this._fields,
+      options: _this._mongooseOptions
+    }
+  }));
 };
 
 /*!

package/lib/schema/date.js

@@ -188,16 +188,18 @@ SchemaDate.prototype.expires = function(when) {
 SchemaDate._checkRequired = v => v instanceof Date;
 
 /**
- * Override the function the required validator uses to check whether a string
+ * Override the function the required validator uses to check whether a date
  * passes the `required` check.
  *
  * #### Example:
  *
- *     // Allow empty strings to pass `required` check
- *     mongoose.Schema.Types.String.checkRequired(v => v != null);
+ *     // Disallow "invalid date"
+ *     mongoose.Schema.Types.Date.checkRequired(v => v instanceof Date && !isNaN(v.valueOf()));
  *
- *     const M = mongoose.model({ str: { type: String, required: true } });
- *     new M({ str: '' }).validateSync(); // `null`, validation passes!
+ *     const schema = new mongoose.Schema({ myDate: { type: Date, required: true } });
+ *     const M = mongoose.model('Test', schema);
+ *     // returns a ValidationError due to date being invalid
+ *     new M({ myDate: new Date('invalid') }).validateSync();
  *
  * @param {Function} fn
  * @return {Function}

package/lib/schema/documentArray.js

@@ -314,7 +314,7 @@ SchemaDocumentArray.prototype.doValidateSync = function(array, scope, options) {
       continue;
     }
 
-    const subdocValidateError = doc.validateSync(options);
+    const subdocValidateError = doc.$__validateSync(options);
 
     if (subdocValidateError && resultError == null) {
       resultError = subdocValidateError;

package/lib/schema/string.js

@@ -473,12 +473,14 @@ SchemaString.prototype.maxlength = function(value, message) {
 
   if (value != null) {
     let msg = message || MongooseError.messages.String.maxlength;
-    msg = msg.replace(/{MAXLENGTH}/, value);
+    if (typeof msg !== 'function') {
+      msg = msg.replace(/{MAXLENGTH}/, value);
+    }
     this.validators.push({
       validator: this.maxlengthValidator = function(v) {
         return v === null || v.length <= value;
       },
-      message: msg,
+      message: formatMaxLengthValidatorMessage(msg),
       type: 'maxlength',
       maxlength: value
     });
@@ -729,3 +731,18 @@ SchemaString.prototype.autoEncryptionType = function autoEncryptionType() {
  */
 
 module.exports = SchemaString;
+
+function formatMaxLengthValidatorMessage(msg) {
+  return function(props, doc) {
+    if (typeof msg === 'function') {
+      return MongooseError.ValidatorError.prototype.formatMessage(msg, props, doc);
+    }
+
+    if (typeof msg === 'string' && typeof props.value === 'string' && props.value.length > 30) {
+      props = Object.assign({}, props, {
+        value: props.value.slice(0, 30) + '...'
+      });
+    }
+    return MongooseError.ValidatorError.prototype.formatMessage(msg, props, doc);
+  };
+}

package/lib/schema/subdocument.js

@@ -310,7 +310,7 @@ SchemaSubdocument.prototype.doValidateSync = function(value, scope, options) {
   if (!value) {
     return;
   }
-  return value.validateSync();
+  return value.$__validateSync();
 };
 
 /**

package/lib/schema/union.js

@@ -112,8 +112,8 @@ class Union extends SchemaType {
         return schemaTypeError;
       }
     }
-    if (value != null && typeof value.validateSync === 'function') {
-      return value.validateSync();
+    if (value != null && typeof value.$__validateSync === 'function') {
+      return value.$__validateSync();
     }
   }
 

package/lib/schemaType.js

@@ -1198,7 +1198,8 @@ SchemaType.prototype.required = function(required, message) {
  *       name: { type: String, allowNull: false }
  *     });
  *
- *     new Model({ name: undefined }).validateSync(); // OK
+ *     new Model({}).validateSync(); // OK
+ *     new Model({ name: undefined }).validateSync(); // OK, Mongoose strips out `name` when its value is `undefined`
  *     new Model({ name: null }).validateSync(); // ValidationError
  *
  * @param {boolean} allowNull
@@ -1456,9 +1457,6 @@ SchemaType.prototype.doValidate = async function doValidate(value, scope, option
     validatorProperties.value = value;
     if (typeof value === 'string') {
       validatorProperties.length = value.length;
-      if (validatorProperties.value.length > 30) {
-        validatorProperties.value = validatorProperties.value.slice(0, 30) + '...';
-      }
     }
 
     if (value === undefined && validator !== this.requiredValidator) {
@@ -1582,9 +1580,6 @@ SchemaType.prototype.doValidateSync = function(value, scope, options) {
     validatorProperties.value = value;
     if (typeof value === 'string') {
       validatorProperties.length = value.length;
-      if (validatorProperties.value.length > 30) {
-        validatorProperties.value = validatorProperties.value.slice(0, 30) + '...';
-      }
     }
     let ok = false;
 

package/lib/standardSchema/convertErrorToIssues.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const ValidationError = require('../error/validation');
+
+module.exports = function convertErrorToIssues(error) {
+  if (error instanceof ValidationError) {
+    return Object.keys(error.errors).map(path => {
+      const err = error.errors[path];
+      return {
+        message: err.message,
+        path: path.split('.').map(part => {
+          const num = +part;
+          return Number.isInteger(num) && String(num) === part ? num : part;
+        })
+      };
+    });
+  }
+
+  return [{ message: error.message }];
+};

package/lib/tracing.js

@@ -0,0 +1,38 @@
+'use strict';
+
+let dc;
+try {
+  dc = (typeof process !== 'undefined' && 'getBuiltinModule' in process)
+    ? process.getBuiltinModule('node:diagnostics_channel')
+    : require('node:diagnostics_channel');
+} catch {
+  // diagnostics_channel not available
+}
+
+const hasTracingChannel = !!dc && typeof dc.tracingChannel === 'function';
+
+function shouldTrace(channel) {
+  // Node 18 and Bun don't expose hasSubscribers on TracingChannel
+  // so undefined means it may or may not have subscribers, so we'll trace anyway
+  return !!channel && channel.hasSubscribers !== false;
+}
+
+function createTracedChannel(name) {
+  const ch = hasTracingChannel ? dc.tracingChannel(name) : undefined;
+
+  function trace(fn, contextFactory) {
+    if (!shouldTrace(ch)) {
+      return fn();
+    }
+
+    const traced = ch.tracePromise(fn, contextFactory());
+    return traced;
+  }
+
+  return { channel: ch, trace };
+}
+
+module.exports = {
+  createTracedChannel,
+  cursorNextChannel: createTracedChannel('mongoose:cursor:next')
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "9.6.2",
+  "version": "9.7.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -39,9 +39,9 @@
     "c8": "11.0.0",
     "cheerio": "1.2.0",
     "dox": "1.0.0",
-    "eslint": "10.2.1",
+    "eslint": "10.4.1",
     "eslint-plugin-mocha-no-only": "1.2.0",
-    "express": "4.22.1",
+    "express": "5.2.1",
     "fs-extra": "~11.3.0",
     "globals": "^17.4.0",
     "glob": "^13.0.6",
@@ -50,16 +50,16 @@
     "lodash.isequal": "4.5.0",
     "lodash.isequalwith": "4.4.0",
     "markdownlint-cli2": "0.22.1",
-    "marked": "18.0.2",
+    "marked": "18.0.4",
     "mkdirp": "^3.0.1",
     "mocha": "12.0.0-beta-10",
     "moment": "2.30.1",
     "mongodb-client-encryption": "~7.0",
-    "mongodb-memory-server": "11.1.0",
+    "mongodb-memory-server": "11.2.0",
     "mongodb-runner": "^6.0.0",
     "ncp": "^2.0.0",
     "pug": "3.0.4",
-    "sinon": "21.1.2",
+    "sinon": "22.0.0",
     "tstyche": "^7.0.0",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.31.1",

package/types/document.d.ts

@@ -11,6 +11,12 @@ declare module 'mongoose' {
     middleware?: boolean | SkipMiddlewareOptions;
   }
 
+  interface ValidateSyncOptions extends Omit<ValidateOptions, 'middleware'> {
+    /** `validateSync()` does not run middleware. Use `validate()` if you need middleware. */
+    middleware?: never;
+    [k: string]: any;
+  }
+
   interface DocumentSetOptions {
     merge?: boolean;
 
@@ -320,9 +326,20 @@ declare module 'mongoose' {
     validate(pathsToValidate?: pathsToValidate, options?: Omit<ValidateOptions, 'pathsToSkip'> & AnyObject): Promise<void>;
     validate(options: ValidateOptions): Promise<void>;
 
-    /** Executes registered validation rules (skipping asynchronous validators) for this document. */
-    validateSync(options: ValidateOptions & { [k: string]: any }): Error.ValidationError | null;
-    validateSync<T extends keyof DocType>(pathsToValidate?: T | T[], options?: Omit<ValidateOptions, 'pathsToSkip'> & AnyObject): Error.ValidationError | null;
-    validateSync(pathsToValidate?: pathsToValidate, options?: Omit<ValidateOptions, 'pathsToSkip'> & AnyObject): Error.ValidationError | null;
+    /**
+     * Executes registered validation rules (skipping asynchronous validators) for this document.
+     * @deprecated Use `validate()` instead. `validateSync()` does not run middleware and will be removed in Mongoose 10.
+     */
+    validateSync(options: ValidateSyncOptions): Error.ValidationError | null;
+    /**
+     * Executes registered validation rules (skipping asynchronous validators) for this document.
+     * @deprecated Use `validate()` instead. `validateSync()` does not run middleware and will be removed in Mongoose 10.
+     */
+    validateSync<T extends keyof DocType>(pathsToValidate?: T | T[], options?: Omit<ValidateSyncOptions, 'pathsToSkip'>): Error.ValidationError | null;
+    /**
+     * Executes registered validation rules (skipping asynchronous validators) for this document.
+     * @deprecated Use `validate()` instead. `validateSync()` does not run middleware and will be removed in Mongoose 10.
+     */
+    validateSync(pathsToValidate?: pathsToValidate, options?: Omit<ValidateSyncOptions, 'pathsToSkip'>): Error.ValidationError | null;
   }
 }

package/types/expressions.d.ts

@@ -2313,6 +2313,19 @@ declare module 'mongoose' {
       }
     }
 
+    export interface Percentile {
+      /**
+       * Returns an array of scalar values that correspond to specified percentile values.
+       *
+       * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/percentile/
+       */
+      $percentile: {
+        input: number | Expression,
+        p: (number | Expression)[],
+        method: 'approximate'
+      }
+    }
+
     export interface StdDevPop {
       /**
        * Calculates the population standard deviation of the input values. Use if the values encompass the entire
@@ -2874,6 +2887,7 @@ declare module 'mongoose' {
     Expression.Median |
     Expression.Min |
     Expression.MinN |
+    Expression.Percentile |
     Expression.Push |
     Expression.Rank |
     Expression.Shift |
@@ -2906,6 +2920,7 @@ declare module 'mongoose' {
     Expression.Max |
     Expression.Median |
     Expression.Min |
+    Expression.Percentile |
     Expression.StdDevPop |
     Expression.StdDevSamp |
     Expression.Sum;
@@ -2981,6 +2996,7 @@ declare module 'mongoose' {
     Expression.MergeObjects |
     Expression.Min |
     Expression.MinN |
+    Expression.Percentile |
     Expression.Push |
     Expression.StdDevPop |
     Expression.StdDevSamp |

package/types/index.d.ts

@@ -24,6 +24,7 @@
 /// <reference path="./inferrawdoctype.d.ts" />
 /// <reference path="./inferschematype.d.ts" />
 /// <reference path="./virtuals.d.ts" />
+/// <reference path="./tracing.d.ts" />
 /// <reference path="./augmentations.d.ts" />
 
 declare class NativeDate extends globalThis.Date { }

package/types/models.d.ts

@@ -108,6 +108,41 @@ declare module 'mongoose' {
    */
   type pathsToValidate = PathsToValidate;
 
+  export namespace StandardSchemaV1 {
+    export interface Props<Output = unknown> {
+      readonly version: 1;
+      readonly vendor: 'mongoose';
+      readonly validate: (
+        value: unknown,
+        options?: Options | undefined
+      ) => Result<Output> | Promise<Result<Output>>;
+    }
+
+    export interface Options {
+      readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+
+    export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+    export interface SuccessResult<Output> {
+      readonly value: Output;
+      readonly issues?: undefined;
+    }
+
+    export interface FailureResult {
+      readonly issues: ReadonlyArray<Issue>;
+    }
+
+    export interface Issue {
+      readonly message: string;
+      readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+
+    export interface PathSegment {
+      readonly key: PropertyKey;
+    }
+  }
+
   interface SaveOptions extends
     SessionOption {
     checkKeys?: boolean;
@@ -192,15 +227,15 @@ declare module 'mongoose' {
   type CreateObjectWithExtraKeys<T> = T & Record<string, unknown>;
   type ApplyBasicCreateCasting<T> = {
     [K in keyof T]: NonNullable<T[K]> extends Map<infer KeyType extends string, infer ValueType>
-      ? (Record<KeyType, ValueType> | Array<[KeyType, ValueType]> | T[K])
+      ? (Record<KeyType, ValueType> | Array<[KeyType, ValueType]> | T[K] | QueryTypeCasting<Extract<T[K], TreatAsPrimitives>>)
       : NonNullable<T[K]> extends Types.DocumentArray<infer RawSubdocType>
-         ? RawSubdocType[] | T[K]
+         ? RawSubdocType[] | T[K] | QueryTypeCasting<Extract<T[K], TreatAsPrimitives>>
          : NonNullable<T[K]> extends Document<any, any, infer RawSubdocType>
-           ? CreateObjectWithExtraKeys<ApplyBasicCreateCasting<RawSubdocType>> | T[K]
+           ? CreateObjectWithExtraKeys<ApplyBasicCreateCasting<RawSubdocType>> | T[K] | QueryTypeCasting<Extract<T[K], TreatAsPrimitives>>
            : NonNullable<T[K]> extends TreatAsPrimitives
               ? QueryTypeCasting<T[K]>
               : NonNullable<T[K]> extends object
-                ? CreateObjectWithExtraKeys<ApplyBasicCreateCasting<T[K]>> | T[K]
+                ? CreateObjectWithExtraKeys<ApplyBasicCreateCasting<T[K]>> | T[K] | QueryTypeCasting<Extract<T[K], TreatAsPrimitives>>
                 : QueryTypeCasting<T[K]>;
   };
 
@@ -234,6 +269,9 @@ declare module 'mongoose' {
     /** Base Mongoose instance the model uses. */
     base: Mongoose;
 
+    /** Standard Schema adapter for validating input with this model's schema. */
+    readonly '~standard': StandardSchemaV1.Props<TRawDocType>;
+
     /**
      * If this is a discriminator model, `baseModelName` is the name of
      * the base model.

package/types/tracing.d.ts

@@ -0,0 +1,10 @@
+declare module 'mongoose' {
+  interface TracingContext {
+    operation: string;
+    collection: string;
+    database: string;
+    serverAddress: string;
+    serverPort: number;
+    args: Record<string, any>;
+  }
+}