mongoose 9.1.6 → 9.2.1

package/lib/aggregate.js

@@ -11,6 +11,7 @@ const { applyGlobalMaxTimeMS, applyGlobalDiskUse } = require('./helpers/query/ap
 const clone = require('./helpers/clone');
 const getConstructorName = require('./helpers/getConstructorName');
 const prepareDiscriminatorPipeline = require('./helpers/aggregate/prepareDiscriminatorPipeline');
+const { buildMiddlewareFilter } = require('./helpers/buildMiddlewareFilter');
 const stringifyFunctionOperators = require('./helpers/aggregate/stringifyFunctionOperators');
 const utils = require('./utils');
 const { modelSymbol } = require('./helpers/symbols');
@@ -718,7 +719,7 @@ Aggregate.prototype.read = function(pref, tags) {
  *
  *     await Model.aggregate(pipeline).readConcern('majority');
  *
- * @param {String} level one of the listed read concern level or their aliases
+ * @param {'local'|'available'|'majority'|'snapshot'|'linearizable'|'l'|'a'|'m'|'s'|'lz'} level one of the listed read concern level or their aliases
  * @see mongodb https://www.mongodb.com/docs/manual/reference/read-concern/
  * @return {Aggregate} this
  * @api public
@@ -784,7 +785,7 @@ Aggregate.prototype.redact = function(expression, thenExpr, elseExpr) {
  *
  *     Model.aggregate(..).explain()
  *
- * @param {String} [verbosity]
+ * @param {'queryPlanner'|'executionStats'|'allPlansExecution'} [verbosity]
  * @return {Promise}
  */
 
@@ -800,13 +801,20 @@ Aggregate.prototype.explain = async function explain(verbosity) {
 
   prepareDiscriminatorPipeline(this._pipeline, this._model.schema);
 
+  const preFilter = buildMiddlewareFilter(this.options, 'pre');
+  const postFilter = buildMiddlewareFilter(this.options, 'post');
+
+  // Remove middleware option before passing to MongoDB
+  const options = this.options != null ? { ...this.options } : {};
+  delete options.middleware;
+
   try {
-    await model.hooks.execPre('aggregate', this);
+    await model.hooks.execPre('aggregate', this, [], { filter: preFilter });
   } catch (error) {
-    return await model.hooks.execPost('aggregate', this, [null], { error });
+    return await model.hooks.execPost('aggregate', this, [null], { error, filter: postFilter });
   }
 
-  const cursor = model.collection.aggregate(this._pipeline, this.options);
+  const cursor = await model.collection.aggregate(this._pipeline, options);
 
   if (verbosity == null) {
     verbosity = true;
@@ -816,10 +824,10 @@ Aggregate.prototype.explain = async function explain(verbosity) {
   try {
     result = await cursor.explain(verbosity);
   } catch (error) {
-    return await model.hooks.execPost('aggregate', this, [null], { error });
+    return await model.hooks.execPost('aggregate', this, [null], { error, filter: postFilter });
   }
 
-  await model.hooks.execPost('aggregate', this, [result], { error: null });
+  await model.hooks.execPost('aggregate', this, [result], { error: null, filter: postFilter });
 
   return result;
 };
@@ -893,6 +901,9 @@ Aggregate.prototype.session = function(session) {
  * @param {Boolean} [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation
  * @param {Object} [options.collation] object see [`Aggregate.prototype.collation()`](https://mongoosejs.com/docs/api/aggregate.html#Aggregate.prototype.collation())
  * @param {ClientSession} [options.session] ClientSession see [`Aggregate.prototype.session()`](https://mongoosejs.com/docs/api/aggregate.html#Aggregate.prototype.session())
+ * @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
  * @see mongodb https://www.mongodb.com/docs/manual/reference/command/aggregate/
  * @return {Aggregate} this
  * @api public
@@ -1056,10 +1067,13 @@ 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');
+
   try {
-    await model.hooks.execPre('aggregate', this);
+    await model.hooks.execPre('aggregate', this, [], { filter: preFilter });
   } catch (error) {
-    return await model.hooks.execPost('aggregate', this, [null], { error });
+    return await model.hooks.execPost('aggregate', this, [null], { error, filter: postFilter });
   }
 
   if (!this._pipeline.length) {
@@ -1067,17 +1081,17 @@ Aggregate.prototype.exec = async function exec() {
   }
 
   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 });
+    return await model.hooks.execPost('aggregate', this, [null], { error, filter: postFilter });
   }
 
-  await model.hooks.execPost('aggregate', this, [result], { error: null });
-
+  await model.hooks.execPost('aggregate', this, [result], { error: null, filter: postFilter });
   return result;
 };
 

package/lib/cursor/aggregationCursor.js

@@ -389,7 +389,7 @@ function _transformForAsyncIterator(doc) {
  * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html#addCursorFlag).
  * Useful for setting the `noCursorTimeout` and `tailable` flags.
  *
- * @param {String} flag
+ * @param {'tailable'|'oplogReplay'|'noCursorTimeout'|'awaitData'|'partial'} flag
  * @param {Boolean} value
  * @return {AggregationCursor} this
  * @api public

package/lib/cursor/queryCursor.js

@@ -371,7 +371,7 @@ QueryCursor.prototype.options;
  * Adds a [cursor flag](https://mongodb.github.io/node-mongodb-native/4.9/classes/FindCursor.html#addCursorFlag).
  * Useful for setting the `noCursorTimeout` and `tailable` flags.
  *
- * @param {String} flag
+ * @param {'tailable'|'oplogReplay'|'noCursorTimeout'|'awaitData'|'partial'} flag
  * @param {Boolean} value
  * @return {AggregationCursor} this
  * @api public

package/lib/document.js

@@ -41,6 +41,7 @@ const minimize = require('./helpers/minimize');
 const mpath = require('mpath');
 const parentPaths = require('./helpers/path/parentPaths');
 const queryhelpers = require('./queryHelpers');
+const { buildMiddlewareFilter } = require('./helpers/buildMiddlewareFilter');
 const utils = require('./utils');
 const isPromise = require('./helpers/isPromise');
 
@@ -860,8 +861,11 @@ function init(self, obj, doc, opts, prefix) {
  * @param {Object} update
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
  * @param {Object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.lean()) and the [Mongoose lean tutorial](https://mongoosejs.com/docs/tutorials/lean.html).
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
+ * @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 {Query}
  * @api public
  * @memberOf Document
@@ -872,7 +876,7 @@ Document.prototype.updateOne = function updateOne(update, options) {
   const query = this.constructor.updateOne();
   const self = this;
   query.pre(async function queryPreUpdateOne() {
-    const res = await self._execDocumentPreHooks('updateOne', self, update, options);
+    const res = await self._execDocumentPreHooks('updateOne', options, [self, update, options]);
     // `self` is passed to pre hooks as argument for backwards compatibility, but that
     // isn't the actual arguments passed to the wrapped function.
     if (res[0] !== self || res[1] !== update || res[2] !== options) {
@@ -892,7 +896,7 @@ Document.prototype.updateOne = function updateOne(update, options) {
     return res;
   });
   query.post(function queryPostUpdateOne() {
-    return self._execDocumentPostHooks('updateOne');
+    return self._execDocumentPostHooks('updateOne', options);
   });
 
   return query;
@@ -2646,6 +2650,9 @@ Document.prototype.isDirectSelected = function isDirectSelected(path) {
  * @param {Object} [options] internal options
  * @param {Boolean} [options.validateModifiedOnly=false] if `true` mongoose validates only modified 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 {Promise} Returns a Promise.
  * @api public
  */
@@ -2961,16 +2968,18 @@ function _pushNestedArrayPaths(val, paths, path) {
  * ignore
  */
 
-Document.prototype._execDocumentPreHooks = async function _execDocumentPreHooks(opName, ...args) {
-  return this.$__middleware.execPre(opName, this, [...args]);
+Document.prototype._execDocumentPreHooks = async function _execDocumentPreHooks(opName, options, argsForHooks) {
+  const filter = buildMiddlewareFilter(options, 'pre');
+  return this.$__middleware.execPre(opName, this, argsForHooks || [], { filter });
 };
 
 /*!
  * ignore
  */
 
-Document.prototype._execDocumentPostHooks = async function _execDocumentPostHooks(opName, error) {
-  return this.$__middleware.execPost(opName, this, [this], { error });
+Document.prototype._execDocumentPostHooks = async function _execDocumentPostHooks(opName, options, error) {
+  const filter = buildMiddlewareFilter(options, 'post');
+  return this.$__middleware.execPost(opName, this, [this], { error, filter });
 };
 
 /*!
@@ -2979,9 +2988,9 @@ Document.prototype._execDocumentPostHooks = async function _execDocumentPostHook
 
 Document.prototype.$__validate = async function $__validate(pathsToValidate, options) {
   try {
-    [options] = await this._execDocumentPreHooks('validate', options);
+    [options] = await this._execDocumentPreHooks('validate', options, [options]);
   } catch (error) {
-    await this._execDocumentPostHooks('validate', error);
+    await this._execDocumentPostHooks('validate', options, error);
     return;
   }
 
@@ -3085,7 +3094,7 @@ Document.prototype.$__validate = async function $__validate(pathsToValidate, opt
 
   if (paths.length === 0) {
     const error = _complete();
-    await this._execDocumentPostHooks('validate', error);
+    await this._execDocumentPostHooks('validate', options, error);
     return;
   }
 
@@ -3108,7 +3117,7 @@ Document.prototype.$__validate = async function $__validate(pathsToValidate, opt
   }
   await Promise.all(promises);
   const error = _complete();
-  await this._execDocumentPostHooks('validate', error);
+  await this._execDocumentPostHooks('validate', options, error);
 
   async function validatePath(path) {
     if (path == null || validated[path]) {
@@ -3233,6 +3242,9 @@ 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.
  * @api public
  */
@@ -4162,6 +4174,7 @@ Document.prototype.$__toObjectShallow = function $__toObjectShallow(schemaFields
  * @param {Boolean} [options.versionKey=true] if false, exclude the version key (`__v` by default) from the output
  * @param {Boolean} [options.flattenMaps=false] if true, convert Maps to POJOs. Useful if you want to `JSON.stringify()` the result of `toObject()`.
  * @param {Boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
+ * @param {Boolean} [options.flattenUUIDs=false] if true, convert any UUIDs in the result to 36-character UUID strings in 8-4-4-4-12 format.
  * @param {Boolean} [options.useProjection=false] - If true, omits fields that are excluded in this document's projection. Unless you specified a projection, this will omit any field that has `select: false` in the schema.
  * @param {Boolean} [options.schemaFieldsOnly=false] - If true, the resulting object will only have fields that are defined in the document's schema. By default, `toObject()` returns all fields in the underlying document from MongoDB, including ones that are not listed in the schema.
  * @return {Object} document as a plain old JavaScript object (POJO). This object may contain ObjectIds, Maps, Dates, mongodb.Binary, Buffers, and other non-POJO values.
@@ -4434,6 +4447,7 @@ function omitDeselectedFields(self, json) {
  * @param {Object} options
  * @param {Boolean} [options.flattenMaps=true] if true, convert Maps to [POJOs](https://masteringjs.io/tutorials/fundamentals/pojo). Useful if you want to `JSON.stringify()` the result.
  * @param {Boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
+ * @param {Boolean} [options.flattenUUIDs=false] if true, convert any UUIDs in the result to 36-character UUID strings in 8-4-4-4-12 format.
  * @param {Boolean} [options.schemaFieldsOnly=false] - If true, the resulting object will only have fields that are defined in the document's schema. By default, `toJSON()` returns all fields in the underlying document from MongoDB, including ones that are not listed in the schema.
  * @return {Object}
  * @see Document#toObject https://mongoosejs.com/docs/api/document.html#Document.prototype.toObject()

package/lib/helpers/buildMiddlewareFilter.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const symbols = require('../schema/symbols');
+
+/**
+ * Filter predicate that returns true for built-in middleware (marked with `builtInMiddleware` symbol).
+ */
+const isBuiltInMiddleware = hook => hook.fn[symbols.builtInMiddleware];
+
+/**
+ * Builds a filter for kareem's execPre/execPost based on middleware options.
+ *
+ * @param {Object} options - Options object that may contain `middleware` setting
+ * @param {String} phase - Either 'pre' or 'post'
+ * @returns {Function|null} - null runs all middleware, isBuiltInMiddleware skips user middleware
+ */
+function buildMiddlewareFilter(options, phase) {
+  const shouldRun = options?.middleware?.[phase] ?? options?.middleware ?? true;
+  return shouldRun ? null : isBuiltInMiddleware;
+}
+
+module.exports = {
+  buildMiddlewareFilter
+};

package/lib/helpers/clone.js

@@ -12,6 +12,9 @@ const isPOJO = require('./isPOJO');
 const symbols = require('./symbols');
 const trustedSymbol = require('./query/trusted').trustedSymbol;
 const BSON = require('mongodb/lib/bson');
+const UUID = BSON.UUID;
+
+const Binary = BSON.Binary;
 
 /**
  * Object clone with Mongoose natives support.
@@ -45,6 +48,14 @@ function clone(obj, options, isArrayChild) {
 
   if (isMongooseObject(obj)) {
     if (options) {
+      if (options.flattenUUIDs) {
+        if (obj instanceof Binary && obj._subtype === Binary.SUBTYPE_UUID) {
+          return obj.toString();
+        }
+        if (obj?.isMongooseBuffer && obj._subtype === Binary.SUBTYPE_UUID) {
+          return obj.toUUID().toString();
+        }
+      }
       if (options.retainDocuments && obj.$__ != null) {
         const clonedDoc = obj.$clone();
         if (obj.__index != null) {
@@ -111,6 +122,13 @@ function clone(obj, options, isArrayChild) {
     return Decimal.fromString(obj.toString());
   }
 
+  if (obj instanceof UUID) {
+    if (options?.flattenUUIDs) {
+      return obj.toJSON();
+    }
+    return new UUID(obj.buffer);
+  }
+
   // object created with Object.create(null)
   if (!objConstructor && isObject(obj)) {
     return cloneObject(obj, options, isArrayChild);

package/lib/helpers/model/applyHooks.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { buildMiddlewareFilter } = require('../buildMiddlewareFilter');
+
 /*!
  * ignore
  */
@@ -84,7 +86,16 @@ function applyHooks(model, schema, options) {
   model._middleware = middleware;
 
   objToDecorate.$__init = middleware.
-    createWrapperSync('init', objToDecorate.$__init, null, kareemOptions);
+    createWrapperSync('init', objToDecorate.$__init, null, {
+      ...kareemOptions,
+      getOptions: (args) => {
+        const opts = args[1];
+        return {
+          pre: { filter: buildMiddlewareFilter(opts, 'pre') },
+          post: { filter: buildMiddlewareFilter(opts, 'post') }
+        };
+      }
+    });
 
   // Support hooks for custom methods
   const customMethods = Object.keys(schema.methods);

package/lib/helpers/query/castUpdate.js

@@ -41,7 +41,7 @@ const mongodbUpdateOperators = new Set([
  * @param {Schema} schema
  * @param {Object} obj
  * @param {Object} [options]
- * @param {Boolean|String} [options.strict] defaults to true
+ * @param {Boolean|'throw'} [options.strict] defaults to true
  * @param {Query} context passed to setters
  * @return {Boolean} true iff the update is non-empty
  * @api private
@@ -205,7 +205,7 @@ function castPipelineOperator(op, val) {
  * @param {Object} obj part of a query
  * @param {String} op the atomic operator ($pull, $set, etc)
  * @param {Object} [options]
- * @param {Boolean|String} [options.strict]
+ * @param {Boolean|'throw'} [options.strict]
  * @param {Query} context
  * @param {Object} filter
  * @param {String} pref path prefix (internal only)

package/lib/helpers/timestamps/setupTimestamps.js

@@ -2,7 +2,6 @@
 
 const applyTimestampsToChildren = require('../update/applyTimestampsToChildren');
 const applyTimestampsToUpdate = require('../update/applyTimestampsToUpdate');
-const get = require('../get');
 const handleTimestampOption = require('../schema/handleTimestampOption');
 const setDocumentTimestamps = require('./setDocumentTimestamps');
 const symbols = require('../../schema/symbols');
@@ -42,14 +41,7 @@ module.exports = function setupTimestamps(schema, timestamps) {
 
   schema.add(schemaAdditions);
 
-  schema.pre('save', function timestampsPreSave() {
-    const timestampOption = get(this, '$__.saveOptions.timestamps');
-    if (timestampOption === false) {
-      return;
-    }
-
-    setDocumentTimestamps(this, timestampOption, currentTime, createdAt, updatedAt);
-  });
+  schema.pre('save', timestampsPreSave);
 
   schema.methods.initializeTimestamps = function(timestampsOptions) {
     if (timestampsOptions === false) {
@@ -85,8 +77,6 @@ module.exports = function setupTimestamps(schema, timestamps) {
     return this;
   };
 
-  _setTimestampsOnUpdate[symbols.builtInMiddleware] = true;
-
   const opts = { query: true, model: false };
   schema.pre('findOneAndReplace', opts, _setTimestampsOnUpdate);
   schema.pre('findOneAndUpdate', opts, _setTimestampsOnUpdate);
@@ -94,23 +84,49 @@ module.exports = function setupTimestamps(schema, timestamps) {
   schema.pre('update', opts, _setTimestampsOnUpdate);
   schema.pre('updateOne', opts, _setTimestampsOnUpdate);
   schema.pre('updateMany', opts, _setTimestampsOnUpdate);
+};
 
-  function _setTimestampsOnUpdate() {
-    const now = currentTime != null ?
-      currentTime() :
-      this.model.base.now();
-    // Replacing with null update should still trigger timestamps
-    if (replaceOps.has(this.op) && this.getUpdate() == null) {
-      this.setUpdate({});
-    }
-    applyTimestampsToUpdate(
-      now,
-      createdAt,
-      updatedAt,
-      this.getUpdate(),
-      this._mongooseOptions,
-      replaceOps.has(this.op)
-    );
-    applyTimestampsToChildren(now, this.getUpdate(), this.model.schema);
+function timestampsPreSave() {
+  const timestampOption = this.$__?.saveOptions?.timestamps;
+  if (timestampOption === false) {
+    return;
   }
-};
+
+  const schema = this.$__schema;
+  const { createdAt, updatedAt } = schema.$timestamps;
+  const timestamps = schema.options.timestamps;
+  const currentTime = timestamps != null && Object.hasOwn(timestamps, 'currentTime') ?
+    timestamps.currentTime :
+    null;
+
+  setDocumentTimestamps(this, timestampOption, currentTime, createdAt, updatedAt);
+}
+
+function _setTimestampsOnUpdate() {
+  const schema = this.model.schema;
+  const { createdAt, updatedAt } = schema.$timestamps;
+  const timestamps = schema.options.timestamps;
+  const currentTime = timestamps != null && Object.hasOwn(timestamps, 'currentTime') ?
+    timestamps.currentTime :
+    null;
+
+  const now = currentTime != null ?
+    currentTime() :
+    this.model.base.now();
+  // Replacing with null update should still trigger timestamps
+  if (replaceOps.has(this.op) && this.getUpdate() == null) {
+    this.setUpdate({});
+  }
+  applyTimestampsToUpdate(
+    now,
+    createdAt,
+    updatedAt,
+    this.getUpdate(),
+    this._mongooseOptions,
+    replaceOps.has(this.op)
+  );
+  applyTimestampsToChildren(now, this.getUpdate(), this.model.schema);
+}
+
+timestampsPreSave[symbols.builtInMiddleware] = true;
+_setTimestampsOnUpdate[symbols.builtInMiddleware] = true;