mongoose 9.7.4 → 9.8.0

package/README.md

@@ -32,7 +32,7 @@ Check out the [plugins search site](https://plugins.mongoosejs.io/) to see hundr
 Pull requests are always welcome! Please base pull requests against the `master`
 branch and follow the [contributing guide](https://github.com/Automattic/mongoose/blob/master/CONTRIBUTING.md).
 
-If your pull requests makes documentation changes, please do **not**
+If your pull request makes documentation changes, please do **not**
 modify any `.html` files. The `.html` files are compiled code, so please make
 your changes in `docs/*.pug`, `lib/*.js`, or `test/docs/*.js`.
 
@@ -341,7 +341,7 @@ new Schema({
 ### Driver Access
 
 Mongoose is built on top of the [official MongoDB Node.js driver](https://github.com/mongodb/node-mongodb-native). Each mongoose model keeps a reference to a [native MongoDB driver collection](http://mongodb.github.io/node-mongodb-native/2.1/api/Collection.html). The collection object can be accessed using `YourModel.collection`. However, using the collection object directly bypasses all mongoose features, including hooks, validation, etc. The one
-notable exception that `YourModel.collection` still buffers
+notable exception is that `YourModel.collection` still buffers
 commands. As such, `YourModel.collection.find()` will **not**
 return a cursor.
 

package/lib/aggregate.js

@@ -615,6 +615,9 @@ Aggregate.prototype.graphLookup = function(options) {
  *
  *     aggregate.sample(3); // Add a pipeline that picks 3 random documents
  *
+ *     // `$match` before `$sample` samples from the filtered subset
+ *     aggregate.match({ difficulty: 'easy' }).sample(3);
+ *
  * @see $sample https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/#pipe._S_sample
  * @param {number} size number of random documents to pick
  * @return {Aggregate}

package/lib/cast.js

@@ -413,7 +413,7 @@ function _cast(val, numbertype, context) {
         _cast(item, numbertype, context);
         val[nkey] = item;
       } else {
-        val[nkey] = numbertype.castForQuery({ val: item, context: context });
+        val[nkey] = numbertype.castForQuery(null, item, context);
       }
     }
   }

package/lib/document.js

@@ -756,6 +756,7 @@ function init(self, obj, doc, opts, prefix) {
   let i;
   const strict = self.$__.strictMode;
   const docSchema = self.$__schema;
+  const strictRead = docSchema.options.strictRead;
 
   for (let index = 0; index < len; ++index) {
     i = keys[index];
@@ -773,6 +774,14 @@ function init(self, obj, doc, opts, prefix) {
     }
 
     const value = obj[i];
+    if (!schemaType && strictRead && docSchema.pathType(path) === 'adhocOrUndefined') {
+      if (strictRead === 'throw') {
+        throw new StrictModeError(path, 'Field `' + path + '` is not in schema and strictRead is set to throw.');
+      } else if (strictRead === true) {
+        continue;
+      }
+    }
+
     if (!schemaType && utils.isPOJO(value)) {
       // assume nested object
       if (!doc[i]) {
@@ -785,6 +794,13 @@ function init(self, obj, doc, opts, prefix) {
       }
       init(self, value, doc[i], opts, path + '.');
     } else if (!schemaType) {
+      // Handle strictRead: filter unknown fields during document hydration from DB
+      if (strictRead === 'throw') {
+        throw new StrictModeError(path, 'Field `' + path + '` is not in schema and strictRead is set to throw.');
+      } else if (strictRead === true) {
+        // Skip this field - do not store in _doc
+        continue;
+      }
       doc[i] = value;
       if (!strict && !prefix) {
         self[i] = value;
@@ -3567,6 +3583,10 @@ function _checkImmutableSubpaths(subdoc, schematype, priorVal) {
  * @param {number} [options.wtimeout] sets a [timeout for the write concern](https://www.mongodb.com/docs/manual/reference/write-concern/#wtimeout). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern).
  * @param {boolean} [options.checkKeys=true] the MongoDB driver prevents you from saving keys that start with '$' or contain '.' by default. Set this option to `false` to skip that check. See [restrictions on field names](https://www.mongodb.com/docs/manual/reference/limits/#Restrictions-on-Field-Names)
  * @param {boolean} [options.timestamps=true] if `false` and [timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this `save()`.
+ * @param {Array} [options.pathsToSave] An array of paths that tell mongoose to only validate and save the paths in `pathsToSave`.
+ * @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
  * @method save
  * @memberOf Document
  * @instance
@@ -4718,6 +4738,9 @@ Document.prototype.equals = function(doc) {
  * @param {boolean} [options.getters=false] if true, Mongoose will call any getters defined on the `localField`. By default, Mongoose gets the raw value of `localField`. For example, you would need to set this option to `true` if you wanted to [add a `lowercase` getter to your `localField`](https://mongoosejs.com/docs/schematypes.html#schematype-options).
  * @param {boolean} [options.clone=false] When you do `BlogPost.find().populate('author')`, blog posts with the same author will share 1 copy of an `author` doc. Enable this option to make Mongoose clone populated docs before assigning them.
  * @param {object|Function} [options.match=null] Add an additional filter to the populate query. Can be a filter object containing [MongoDB query syntax](https://www.mongodb.com/docs/manual/tutorial/query-documents/), or a function that returns a filter object.
+ * @param {boolean} [options.skipInvalidIds=false] By default, Mongoose throws a cast error if `localField` and `foreignField` schemas don't line up. If you enable this option, Mongoose will instead filter out any `localField` properties that cannot be casted to `foreignField`'s schema type.
+ * @param {number} [options.perDocumentLimit=null] For legacy reasons, `limit` with `populate()` may give incorrect results when populating multiple parent documents because it executes a single query for all parents. If you set `perDocumentLimit`, Mongoose will execute a separate query per parent document to ensure correct per-document `limit`.
+ * @param {boolean} [options.strictPopulate=true] Set to false to allow populating paths that aren't defined in the given model's schema.
  * @param {Function} [options.transform=null] Function that Mongoose will call on every populated document that allows you to transform the populated document.
  * @param {object} [options.options=null] Additional options like `limit` and `lean`.
  * @param {boolean} [options.forceRepopulate=true] Set to `false` to prevent Mongoose from repopulating paths that are already populated
@@ -5147,8 +5170,8 @@ Document.prototype.$__delta = function $__delta(pathsToSave, pathsToSaveSet) {
       const optimisticConcurrencyExcludeSet = this.$__schema.options._optimisticConcurrencyExcludeSet;
       const modPaths = this.directModifiedPaths();
       const hasRelevantModPaths = pathsToSave == null ?
-        modPaths.find(path => !_pathOverlapsSet(path, optimisticConcurrencyExcludeSet)) :
-        modPaths.find(path => !_pathOverlapsSet(path, optimisticConcurrencyExcludeSet) && isInPathsToSave(path, pathsToSaveSet, pathsToSave));
+        modPaths.find(path => !_pathOrAncestorInSet(path, optimisticConcurrencyExcludeSet)) :
+        modPaths.find(path => !_pathOrAncestorInSet(path, optimisticConcurrencyExcludeSet) && isInPathsToSave(path, pathsToSaveSet, pathsToSave));
       if (hasRelevantModPaths) {
         this.$__.version = dirty.length ? VERSION_ALL : VERSION_WHERE;
       }
@@ -5661,34 +5684,17 @@ Document.prototype._applyVersionIncrement = function _applyVersionIncrement() {
   }
 };
 
-/*!
- * Increment this document's version if necessary.
- */
-
-Document.prototype._applyVersionIncrement = function _applyVersionIncrement() {
-  if (!this.$__.version) return;
-  const doIncrement = VERSION_INC === (VERSION_INC & this.$__.version);
-
-  this.$__.version = undefined;
-  if (doIncrement) {
-    const key = this.$__schema.options.versionKey;
-    const version = this.$__getValue(key) || 0;
-    this.$__setValue(key, version + 1); // increment version if was successful
-  }
-};
-
 /*!
  * Module exports.
  */
 
 /*!
- * Check if `path`, any of its ancestor paths, or any of its descendant paths
- * exist in `pathSet`.
+ * Check if `path` or any of its ancestor paths exist in `pathSet`.
  * For example:
- *   _pathOverlapsSet('profile.firstName', Set(['profile'])) === true
- *   _pathOverlapsSet('profile', Set(['profile.firstName'])) === true
+ *   _pathOrAncestorInSet('profile.firstName', Set(['profile'])) === true
+ *   _pathOrAncestorInSet('profile', Set(['profile.firstName'])) === false
  */
-function _pathOverlapsSet(path, pathSet) {
+function _pathOrAncestorInSet(path, pathSet) {
   if (pathSet.has(path)) {
     return true;
   }
@@ -5699,6 +5705,20 @@ function _pathOverlapsSet(path, pathSet) {
     }
     idx = path.indexOf('.', idx + 1);
   }
+  return false;
+}
+
+/*!
+ * Check if `path`, any of its ancestor paths, or any of its descendant paths
+ * exist in `pathSet`.
+ * For example:
+ *   _pathOverlapsSet('profile.firstName', Set(['profile'])) === true
+ *   _pathOverlapsSet('profile', Set(['profile.firstName'])) === true
+ */
+function _pathOverlapsSet(path, pathSet) {
+  if (_pathOrAncestorInSet(path, pathSet)) {
+    return true;
+  }
   for (const p of pathSet) {
     if (p.length > path.length + 1 && p[path.length] === '.' && p.slice(0, path.length) === path) {
       return true;

package/lib/model.js

@@ -3656,12 +3656,16 @@ async function buildPreSavePromise(document, options) {
 }
 
 async function handleSuccessfulWrite(document, options) {
-  if (document.$isNew) {
+  const wasNew = document.$isNew;
+  if (wasNew) {
     _setIsNew(document, false);
   }
 
   document.$__reset();
-  document._applyVersionIncrement();
+  // version key gets initialized to 0 when inserting a new document so avoid incrementing version key here
+  if (!wasNew) {
+    document._applyVersionIncrement();
+  }
   const postFilter = buildMiddlewareFilter(options, 'post');
   return document.schema.s.hooks.execPost('save', document, [document], { filter: postFilter });
 }
@@ -3911,6 +3915,12 @@ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, op
 
     const isANewDocument = document.isNew;
     if (isANewDocument) {
+      // Like `$__version()` on insert, initialize the version key so
+      // inserted documents get the same shape as `save()` gives them
+      const versionKey = document.$__schema.options.versionKey;
+      if (versionKey) {
+        document.$__setValue(versionKey, 0);
+      }
       const writeOperation = { insertOne: { document } };
       utils.injectTimestampsOption(writeOperation.insertOne, options.timestamps);
       return writeOperation;

package/lib/query.js

@@ -5088,12 +5088,17 @@ Query.prototype._castUpdate = function _castUpdate(obj) {
  * @param {object} [match] Conditions for the population query
  * @param {object} [options] Options for the population query (sort, etc)
  * @param {string} [options.path=null] The path to populate.
+ * @param {string|PopulateOptions} [options.populate=null] Recursively populate paths in the populated documents. See [deep populate docs](https://mongoosejs.com/docs/populate.html#deep-populate).
  * @param {boolean} [options.retainNullValues=false] by default, Mongoose removes null and undefined values from populated arrays. Use this option to make `populate()` retain `null` and `undefined` array entries.
  * @param {boolean} [options.getters=false] if true, Mongoose will call any getters defined on the `localField`. By default, Mongoose gets the raw value of `localField`. For example, you would need to set this option to `true` if you wanted to [add a `lowercase` getter to your `localField`](https://mongoosejs.com/docs/schematypes.html#schematype-options).
  * @param {boolean} [options.clone=false] When you do `BlogPost.find().populate('author')`, blog posts with the same author will share 1 copy of an `author` doc. Enable this option to make Mongoose clone populated docs before assigning them.
  * @param {object|Function} [options.match=null] Add an additional filter to the populate query. Can be a filter object containing [MongoDB query syntax](https://www.mongodb.com/docs/manual/tutorial/query-documents/), or a function that returns a filter object.
+ * @param {boolean} [options.skipInvalidIds=false] By default, Mongoose throws a cast error if `localField` and `foreignField` schemas don't line up. If you enable this option, Mongoose will instead filter out any `localField` properties that cannot be casted to `foreignField`'s schema type.
+ * @param {number} [options.perDocumentLimit=null] For legacy reasons, `limit` with `populate()` may give incorrect results because it only executes a single query for every document being populated. If you set `perDocumentLimit`, Mongoose will ensure correct `limit` per document by executing a separate query for each document to `populate()`. For example, `.find().populate({ path: 'test', perDocumentLimit: 2 })` will execute 2 additional queries if `.find()` returns 2 documents.
+ * @param {boolean} [options.strictPopulate=true] Set to false to allow populating paths that aren't defined in the given model's schema.
  * @param {Function} [options.transform=null] Function that Mongoose will call on every populated document that allows you to transform the populated document.
  * @param {object} [options.options=null] Additional options like `limit` and `lean`.
+ * @param {boolean} [options.ordered=false] Set to `true` to execute any populate queries one at a time, as opposed to in parallel. Set this option to `true` if populating multiple paths or paths with multiple models in transactions.
  * @see population https://mongoosejs.com/docs/populate.html
  * @see Query#select https://mongoosejs.com/docs/api/query.html#Query.prototype.select()
  * @see Model.populate https://mongoosejs.com/docs/api/model.html#Model.populate()

package/lib/schema/array.js

@@ -510,9 +510,9 @@ SchemaArray.prototype._castForQuery = function(val, context) {
   }
 
   if (Array.isArray(val)) {
-    this.setters.reverse().forEach(setter => {
-      val = setter.call(this, val, this);
-    });
+    for (let i = this.setters.length - 1; i >= 0; i--) {
+      val = this.setters[i].call(this, val, this);
+    }
     val = val.map(function(v) {
       if (utils.isObject(v) && v.$elemMatch) {
         return v;

package/lib/schema.js

@@ -72,6 +72,7 @@ const numberRE = /^\d+$/;
  * - [shardKey](https://mongoosejs.com/docs/guide.html#shardKey): object - defaults to `null`
  * - [strict](https://mongoosejs.com/docs/guide.html#strict): bool - defaults to true
  * - [strictQuery](https://mongoosejs.com/docs/guide.html#strictQuery): bool - defaults to false
+ * - [strictRead](https://mongoosejs.com/docs/guide.html#strictRead): bool or 'throw' - defaults to false. If set to `true`, fields not in the schema will be stripped when hydrating documents from MongoDB. If set to `'throw'`, an error will be thrown when a field not in the schema is encountered during document hydration.
  * - [toJSON](https://mongoosejs.com/docs/guide.html#toJSON) - object - no default
  * - [toObject](https://mongoosejs.com/docs/guide.html#toObject) - object - no default
  * - [typeKey](https://mongoosejs.com/docs/guide.html#typeKey) - string - defaults to 'type'
@@ -606,10 +607,12 @@ Schema.prototype.defaultOptions = function(options) {
   const baseOptions = this.base?.options || {};
   const defaultStrict = baseOptions.strict ?? true;
   const defaultStrictQuery = baseOptions.strictQuery ?? false;
+  const defaultStrictRead = baseOptions.strictRead ?? false;
   const defaultId = baseOptions.id ?? true;
   options = {
     strict: defaultStrict,
     strictQuery: defaultStrictQuery,
+    strictRead: defaultStrictRead,
     bufferCommands: true,
     capped: false, // { size, max, autoIndexId }
     versionKey: '__v',

package/lib/types/subdocument.js

@@ -403,7 +403,9 @@ if (util.inspect.custom) {
 
 /**
  * Override `$toObject()` to handle minimizing the whole path. Should not minimize if schematype-level minimize
- * is set to false re: gh-11247, gh-14058, gh-14151
+ * is set to false re: gh-11247, gh-14058, gh-14151. Should not minimize document array elements: an array
+ * element cannot be removed without shifting the array, so minimizing it to `undefined` makes the BSON
+ * serializer store `null` re: gh-7322.
  */
 
 Subdocument.prototype.$toObject = function $toObject(options, json) {
@@ -413,7 +415,7 @@ Subdocument.prototype.$toObject = function $toObject(options, json) {
   // If minimize is set, then we can minimize out the whole object.
   if (utils.hasOwnKeys(ret) === false && options?._calledWithOptions != null) {
     const minimize = options._calledWithOptions?.minimize ?? this?.$__schemaTypeOptions?.minimize ?? options.minimize;
-    if (minimize && !this.constructor.$__required) {
+    if (minimize && !this.constructor.$__required && !this.$isDocumentArrayElement) {
       return undefined;
     }
   }

package/lib/validOptions.js

@@ -32,6 +32,7 @@ const VALID_OPTIONS = Object.freeze([
   'strict',
   'strictPopulate',
   'strictQuery',
+  'strictRead',
   'timestamps.createdAt.immutable',
   'toJSON',
   'toObject',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "9.7.4",
+  "version": "9.8.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -22,7 +22,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "kareem": "3.3.0",
-    "mongodb": "~7.2",
+    "mongodb": "~7.5",
     "mpath": "0.9.0",
     "mquery": "6.0.0",
     "ms": "2.1.3",
@@ -55,7 +55,7 @@
     "mkdirp": "^3.0.1",
     "mocha": "12.0.0-beta-10",
     "moment": "2.30.1",
-    "mongodb-client-encryption": "~7.0",
+    "mongodb-client-encryption": "^7.2.0",
     "mongodb-memory-server": "11.2.0",
     "mongodb-runner": "^6.0.0",
     "ncp": "^2.0.0",
@@ -99,17 +99,17 @@
     "mongo": "node ./tools/repl.js",
     "publish-7x": "npm publish --tag 7x",
     "create-separate-require-instance": "rm -rf ./node_modules/mongoose-separate-require-instance && node ./scripts/create-tarball && tar -xzf mongoose.tgz -C ./node_modules && mv ./node_modules/package ./node_modules/mongoose-separate-require-instance",
-    "test": "mocha --exit ./test/*.test.js",
+    "test": "mocha --exit --ignore \"test/encryption/**/*.test.js\" \"./test/**/*.test.js\"",
     "test:ci": "npm run test -- --reporter min",
     "test-deno": "deno run --allow-env --allow-read --allow-net --allow-run --allow-sys --allow-write ./test/deno.mjs",
     "test-deno:ci": "npm run test-deno -- --reporter min",
-    "test-rs": "START_REPLICA_SET=1 mocha --timeout 30000 --exit ./test/*.test.js",
+    "test-rs": "START_REPLICA_SET=1 mocha --timeout 30000 --exit --ignore \"test/encryption/**/*.test.js\" \"./test/**/*.test.js\"",
     "test-rs:ci": "npm run test-rs -- --reporter min",
     "test:types": "tstyche",
     "setup-test-encryption": "node scripts/setup-encryption-tests.js",
     "test-encryption": "mocha --exit ./test/encryption/*.test.js",
     "test-encryption:ci": "npm run test-encryption -- --reporter min",
-    "tdd": "mocha --watch --inspect --recursive ./test/*.test.js --watch-files lib/**/*.js test/**/*.js",
+    "tdd": "mocha --watch --inspect --ignore \"test/encryption/**/*.test.js\" \"./test/**/*.test.js\" --watch-files lib/**/*.js test/**/*.js",
     "test-coverage": "c8 --reporter=html --reporter=text npm test",
     "test-coverage:ci": "c8 --reporter=html --reporter=text npm run test:ci",
     "ts-benchmark": "cd ./benchmarks/typescript/simple && npm install && npm run benchmark | node ../../../scripts/tsc-diagnostics-check",

package/types/models.d.ts

@@ -116,6 +116,8 @@ declare module 'mongoose' {
     SessionOption {
     checkKeys?: boolean;
     j?: boolean;
+    /** An array of paths that tell mongoose to only validate and save the paths in `pathsToSave`. */
+    pathsToSave?: string[];
     safe?: boolean | WriteConcern;
     timestamps?: boolean | QueryTimestampsConfig;
     validateBeforeSave?: boolean;
@@ -516,8 +518,16 @@ declare module 'mongoose' {
     /**
      * Shortcut for creating a new Document from existing raw data, pre-saved in the DB.
      * The document returned has no paths marked as modified initially.
+     * With `strict: false`, fields not in the schema are kept on the document; pass
+     * `ExtraFields` to describe their types, e.g.
+     * `Model.hydrate<{ totalOrders: number }>(obj, null, { strict: false })`.
      */
-    hydrate(obj: any, projection?: ProjectionType<TRawDocType>, options?: HydrateOptions): THydratedDocumentType;
+    hydrate<ExtraFields = unknown>(
+      obj: any,
+      projection: ProjectionType<TRawDocType> | null | undefined,
+      options: HydrateOptions & { strict: false }
+    ): THydratedDocumentType & ExtraFields;
+    hydrate(obj: any, projection?: ProjectionType<TRawDocType> | null | undefined, options?: HydrateOptions): THydratedDocumentType;
 
     /**
      * This function is responsible for building [indexes](https://www.mongodb.com/docs/manual/indexes/),

package/types/mongooseoptions.d.ts

@@ -192,6 +192,14 @@ declare module 'mongoose' {
      */
     strictQuery?: boolean | 'throw';
 
+    /**
+     * Sets the default [strictRead](https://mongoosejs.com/docs/guide.html#strictRead) mode for schemas.
+     * May be `false`, `true`, or `'throw'`.
+     *
+     * @default false
+     */
+    strictRead?: boolean | 'throw';
+
     /**
      * Overwrites default objects to `toJSON()`, for determining how Mongoose
      * documents get serialized by `JSON.stringify()`

package/types/populate.d.ts

@@ -61,6 +61,14 @@ declare module 'mongoose' {
     match?: any;
     /** optional model to use for population */
     model?: string | Model<any>;
+    /** by default, Mongoose removes null and undefined values from populated arrays. Use this option to make `populate()` retain `null` and `undefined` array entries. */
+    retainNullValues?: boolean;
+    /** if true, Mongoose will call any getters defined on the `localField`. By default, Mongoose gets the raw value of `localField`. */
+    getters?: boolean;
+    /** if true, Mongoose will clone populated docs before assigning them, so docs that are populated onto multiple parents don't share 1 copy. */
+    clone?: boolean;
+    /** By default, Mongoose throws a cast error if `localField` and `foreignField` schemas don't line up. If you enable this option, Mongoose will instead filter out any `localField` properties that cannot be casted to `foreignField`'s schema type. */
+    skipInvalidIds?: boolean;
     /** optional query options like sort, limit, etc */
     options?: QueryOptions;
     /** correct limit on populated array */

package/types/schemaoptions.d.ts

@@ -158,6 +158,11 @@ declare module 'mongoose' {
      * [strictQuery](https://mongoosejs.com/docs/guide.html#strictQuery) mode for schemas.
      */
     strictQuery?: boolean | 'throw';
+    /**
+     * May be `false`, `true`, or `'throw'`. Sets the default
+     * [strictRead](https://mongoosejs.com/docs/guide.html#strictRead) mode for schemas.
+     */
+    strictRead?: boolean | 'throw';
     /** Exactly the same as the toObject option but only applies when the document's toJSON method is called. */
     toJSON?: ToObjectOptions<DocType, THydratedDocumentType>;
     /**