mongoose 8.8.4 → 8.9.1

package/lib/cast/double.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const assert = require('assert');
+const BSON = require('bson');
+const isBsonType = require('../helpers/isBsonType');
+
+/**
+ * Given a value, cast it to a IEEE 754-2008 floating point, or throw an `Error` if the value
+ * cannot be casted. `null`, `undefined`, and `NaN` are considered valid inputs.
+ *
+ * @param {Any} value
+ * @return {Number}
+ * @throws {Error} if `value` does not represent a IEEE 754-2008 floating point. If casting from a string, see [BSON Double.fromString API documentation](https://mongodb.github.io/node-mongodb-native/Next/classes/BSON.Double.html#fromString)
+ * @api private
+ */
+
+module.exports = function castDouble(val) {
+  if (val == null || val === '') {
+    return null;
+  }
+
+  let coercedVal;
+  if (isBsonType(val, 'Long')) {
+    coercedVal = val.toNumber();
+  } else if (typeof val === 'string') {
+    try {
+      coercedVal = BSON.Double.fromString(val);
+      return coercedVal;
+    } catch {
+      assert.ok(false);
+    }
+  } else if (typeof val === 'object') {
+    const tempVal = val.valueOf() ?? val.toString();
+    // ex: { a: 'im an object, valueOf: () => 'helloworld' } // throw an error
+    if (typeof tempVal === 'string') {
+      try {
+        coercedVal = BSON.Double.fromString(val);
+        return coercedVal;
+      } catch {
+        assert.ok(false);
+      }
+    } else {
+      coercedVal = Number(tempVal);
+    }
+  } else {
+    coercedVal = Number(val);
+  }
+
+  return new BSON.Double(coercedVal);
+};

package/lib/cast/int32.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const isBsonType = require('../helpers/isBsonType');
+const assert = require('assert');
+
+/**
+ * Given a value, cast it to a Int32, or throw an `Error` if the value
+ * cannot be casted. `null` and `undefined` are considered valid.
+ *
+ * @param {Any} value
+ * @return {Number}
+ * @throws {Error} if `value` does not represent an integer, or is outside the bounds of an 32-bit integer.
+ * @api private
+ */
+
+module.exports = function castInt32(val) {
+  if (val == null) {
+    return val;
+  }
+  if (val === '') {
+    return null;
+  }
+
+  const coercedVal = isBsonType(val, 'Long') ? val.toNumber() : Number(val);
+
+  const INT32_MAX = 0x7FFFFFFF;
+  const INT32_MIN = -0x80000000;
+
+  if (coercedVal === (coercedVal | 0) &&
+      coercedVal >= INT32_MIN &&
+      coercedVal <= INT32_MAX
+  ) {
+    return coercedVal;
+  }
+  assert.ok(false);
+};

package/lib/connection.js

@@ -8,6 +8,7 @@ const ChangeStream = require('./cursor/changeStream');
 const EventEmitter = require('events').EventEmitter;
 const Schema = require('./schema');
 const STATES = require('./connectionState');
+const MongooseBulkWriteError = require('./error/bulkWriteError');
 const MongooseError = require('./error/index');
 const ServerSelectionError = require('./error/serverSelection');
 const SyncIndexesError = require('./error/syncIndexes');
@@ -15,9 +16,13 @@ const applyPlugins = require('./helpers/schema/applyPlugins');
 const clone = require('./helpers/clone');
 const driver = require('./driver');
 const get = require('./helpers/get');
+const getDefaultBulkwriteResult = require('./helpers/getDefaultBulkwriteResult');
 const immediate = require('./helpers/immediate');
 const utils = require('./utils');
 const CreateCollectionsError = require('./error/createCollectionsError');
+const castBulkWrite = require('./helpers/model/castBulkWrite');
+const { modelSymbol } = require('./helpers/symbols');
+const isPromise = require('./helpers/isPromise');
 
 const arrayAtomicsSymbol = require('./helpers/symbols').arrayAtomicsSymbol;
 const sessionNewDocuments = require('./helpers/symbols').sessionNewDocuments;
@@ -111,6 +116,9 @@ Object.defineProperty(Connection.prototype, 'readyState', {
     if (
       this._readyState === STATES.connected &&
       this._lastHeartbeatAt != null &&
+      // LoadBalanced topology (behind haproxy, including Atlas serverless instances) don't use heartbeats,
+      // so we can't use this check in that case.
+      this.client?.topology?.s?.description?.type !== 'LoadBalanced' &&
       typeof this.client?.topology?.s?.description?.heartbeatFrequencyMS === 'number' &&
       Date.now() - this._lastHeartbeatAt >= this.client.topology.s.description.heartbeatFrequencyMS * 2) {
       return STATES.disconnected;
@@ -150,7 +158,7 @@ Object.defineProperty(Connection.prototype, 'readyState', {
  * @api public
  */
 
-Connection.prototype.get = function(key) {
+Connection.prototype.get = function getOption(key) {
   if (this.config.hasOwnProperty(key)) {
     return this.config[key];
   }
@@ -178,7 +186,7 @@ Connection.prototype.get = function(key) {
  * @api public
  */
 
-Connection.prototype.set = function(key, val) {
+Connection.prototype.set = function setOption(key, val) {
   if (this.config.hasOwnProperty(key)) {
     this.config[key] = val;
     return val;
@@ -416,6 +424,178 @@ Connection.prototype.createCollection = async function createCollection(collecti
   return this.db.createCollection(collection, options);
 };
 
+/**
+ * _Requires MongoDB Server 8.0 or greater_. Executes bulk write operations across multiple models in a single operation.
+ * You must specify the `model` for each operation: Mongoose will use `model` for casting and validation, as well as
+ * determining which collection to apply the operation to.
+ *
+ * #### Example:
+ *     const Test = mongoose.model('Test', new Schema({ name: String }));
+ *
+ *     await db.bulkWrite([
+ *       { model: Test, name: 'insertOne', document: { name: 'test1' } }, // Can specify model as a Model class...
+ *       { model: 'Test', name: 'insertOne', document: { name: 'test2' } } // or as a model name
+ *     ], { ordered: false });
+ *
+ * @method bulkWrite
+ * @param {Array} ops
+ * @param {Object} [options]
+ * @param {Boolean} [options.ordered] If false, perform unordered operations. If true, perform ordered operations.
+ * @param {Session} [options.session] The session to use for the operation.
+ * @return {Promise}
+ * @see MongoDB https://www.mongodb.com/docs/manual/reference/command/bulkWrite/#mongodb-dbcommand-dbcmd.bulkWrite
+ * @api public
+ */
+
+
+Connection.prototype.bulkWrite = async function bulkWrite(ops, options) {
+  await this._waitForConnect();
+  options = options || {};
+
+  const ordered = options.ordered == null ? true : options.ordered;
+  const asyncLocalStorage = this.base.transactionAsyncLocalStorage?.getStore();
+  if ((!options || !options.hasOwnProperty('session')) && asyncLocalStorage?.session != null) {
+    options = { ...options, session: asyncLocalStorage.session };
+  }
+
+  const now = this.base.now();
+
+  let res = null;
+  if (ordered) {
+    const opsToSend = [];
+    for (const op of ops) {
+      if (typeof op.model !== 'string' && !op.model?.[modelSymbol]) {
+        throw new MongooseError('Must specify model in Connection.prototype.bulkWrite() operations');
+      }
+      const Model = op.model[modelSymbol] ? op.model : this.model(op.model);
+
+      if (op.name == null) {
+        throw new MongooseError('Must specify operation name in Connection.prototype.bulkWrite()');
+      }
+      if (!castBulkWrite.cast.hasOwnProperty(op.name)) {
+        throw new MongooseError(`Unrecognized bulkWrite() operation name ${op.name}`);
+      }
+
+      await castBulkWrite.cast[op.name](Model, op, options, now);
+      opsToSend.push({ ...op, namespace: Model.namespace() });
+    }
+
+    res = await this.client.bulkWrite(opsToSend, options);
+  } else {
+    const validOps = [];
+    const validOpIndexes = [];
+    let validationErrors = [];
+    const asyncValidations = [];
+    const results = [];
+    for (let i = 0; i < ops.length; ++i) {
+      const op = ops[i];
+      if (typeof op.model !== 'string' && !op.model?.[modelSymbol]) {
+        const error = new MongooseError('Must specify model in Connection.prototype.bulkWrite() operations');
+        validationErrors.push({ index: i, error: error });
+        results[i] = error;
+        continue;
+      }
+      let Model;
+      try {
+        Model = op.model[modelSymbol] ? op.model : this.model(op.model);
+      } catch (error) {
+        validationErrors.push({ index: i, error: error });
+        continue;
+      }
+      if (op.name == null) {
+        const error = new MongooseError('Must specify operation name in Connection.prototype.bulkWrite()');
+        validationErrors.push({ index: i, error: error });
+        results[i] = error;
+        continue;
+      }
+      if (!castBulkWrite.cast.hasOwnProperty(op.name)) {
+        const error = new MongooseError(`Unrecognized bulkWrite() operation name ${op.name}`);
+        validationErrors.push({ index: i, error: error });
+        results[i] = error;
+        continue;
+      }
+
+      let maybePromise = null;
+      try {
+        maybePromise = castBulkWrite.cast[op.name](Model, op, options, now);
+      } catch (error) {
+        validationErrors.push({ index: i, error: error });
+        results[i] = error;
+        continue;
+      }
+      if (isPromise(maybePromise)) {
+        asyncValidations.push(
+          maybePromise.then(
+            () => {
+              validOps.push({ ...op, namespace: Model.namespace() });
+              validOpIndexes.push(i);
+            },
+            error => {
+              validationErrors.push({ index: i, error: error });
+              results[i] = error;
+            }
+          )
+        );
+      } else {
+        validOps.push({ ...op, namespace: Model.namespace() });
+        validOpIndexes.push(i);
+      }
+    }
+
+    if (asyncValidations.length > 0) {
+      await Promise.all(asyncValidations);
+    }
+
+    validationErrors = validationErrors.
+      sort((v1, v2) => v1.index - v2.index).
+      map(v => v.error);
+
+    if (validOps.length === 0) {
+      if (options.throwOnValidationError && validationErrors.length) {
+        throw new MongooseBulkWriteError(
+          validationErrors,
+          results,
+          res,
+          'bulkWrite'
+        );
+      }
+      return getDefaultBulkwriteResult();
+    }
+
+    let error;
+    [res, error] = await this.client.bulkWrite(validOps, options).
+      then(res => ([res, null])).
+      catch(err => ([null, err]));
+
+    if (error) {
+      if (validationErrors.length > 0) {
+        error.mongoose = error.mongoose || {};
+        error.mongoose.validationErrors = validationErrors;
+      }
+    }
+
+    for (let i = 0; i < validOpIndexes.length; ++i) {
+      results[validOpIndexes[i]] = null;
+    }
+    if (validationErrors.length > 0) {
+      if (options.throwOnValidationError) {
+        throw new MongooseBulkWriteError(
+          validationErrors,
+          results,
+          res,
+          'bulkWrite'
+        );
+      } else {
+        res.mongoose = res.mongoose || {};
+        res.mongoose.validationErrors = validationErrors;
+        res.mongoose.results = results;
+      }
+    }
+  }
+
+  return res;
+};
+
 /**
  * Calls `createCollection()` on a models in a series.
  *
@@ -745,7 +925,7 @@ Connection.prototype._shouldBufferCommands = function _shouldBufferCommands() {
  * @api private
  */
 
-Connection.prototype.error = function(err, callback) {
+Connection.prototype.error = function error(err, callback) {
   if (callback) {
     callback(err);
     return null;
@@ -759,6 +939,7 @@ Connection.prototype.error = function(err, callback) {
 /**
  * Called when the connection is opened
  *
+ * @emits "open"
  * @api private
  */
 
@@ -863,11 +1044,21 @@ Connection.prototype.openUri = async function openUri(uri, options) {
   return this;
 };
 
-/*!
- * Treat `on('error')` handlers as handling the initialConnection promise
- * to avoid uncaught exceptions when using `on('error')`. See gh-14377.
+/**
+ * Listen to events in the Connection
+ *
+ * @param {String} event The event to listen on
+ * @param {Function} callback
+ * @see Connection#readyState https://mongoosejs.com/docs/api/connection.html#Connection.prototype.readyState
+ *
+ * @method on
+ * @instance
+ * @memberOf Connection
+ * @api public
  */
 
+// Treat `on('error')` handlers as handling the initialConnection promise
+// to avoid uncaught exceptions when using `on('error')`. See gh-14377.
 Connection.prototype.on = function on(event, callback) {
   if (event === 'error' && this.$initialConnection) {
     this.$initialConnection.catch(() => {});
@@ -875,11 +1066,21 @@ Connection.prototype.on = function on(event, callback) {
   return EventEmitter.prototype.on.call(this, event, callback);
 };
 
-/*!
- * Treat `once('error')` handlers as handling the initialConnection promise
- * to avoid uncaught exceptions when using `on('error')`. See gh-14377.
+/**
+ * Listen to a event once in the Connection
+ *
+ * @param {String} event The event to listen on
+ * @param {Function} callback
+ * @see Connection#readyState https://mongoosejs.com/docs/api/connection.html#Connection.prototype.readyState
+ *
+ * @method once
+ * @instance
+ * @memberOf Connection
+ * @api public
  */
 
+// Treat `on('error')` handlers as handling the initialConnection promise
+// to avoid uncaught exceptions when using `on('error')`. See gh-14377.
 Connection.prototype.once = function on(event, callback) {
   if (event === 'error' && this.$initialConnection) {
     this.$initialConnection.catch(() => {});
@@ -1040,17 +1241,18 @@ Connection.prototype._close = async function _close(force, destroy) {
  * @api private
  */
 
-Connection.prototype.doClose = function() {
+Connection.prototype.doClose = function doClose() {
   throw new Error('Connection#doClose unimplemented by driver');
 };
 
 /**
  * Called when the connection closes
  *
+ * @emits "close"
  * @api private
  */
 
-Connection.prototype.onClose = function(force) {
+Connection.prototype.onClose = function onClose(force) {
   this.readyState = STATES.disconnected;
 
   // avoid having the collection subscribe to our event emitter
@@ -1154,7 +1356,7 @@ Connection.prototype.plugin = function(fn, opts) {
  * @api public
  */
 
-Connection.prototype.model = function(name, schema, collection, options) {
+Connection.prototype.model = function model(name, schema, collection, options) {
   if (!(this instanceof Connection)) {
     throw new MongooseError('`connection.model()` should not be run with ' +
       '`new`. If you are doing `new db.model(foo)(bar)`, use ' +
@@ -1274,7 +1476,7 @@ Connection.prototype.model = function(name, schema, collection, options) {
  * @return {Connection} this
  */
 
-Connection.prototype.deleteModel = function(name) {
+Connection.prototype.deleteModel = function deleteModel(name) {
   if (typeof name === 'string') {
     const model = this.model(name);
     if (model == null) {
@@ -1330,7 +1532,7 @@ Connection.prototype.deleteModel = function(name) {
  * @return {ChangeStream} mongoose-specific change stream wrapper, inherits from EventEmitter
  */
 
-Connection.prototype.watch = function(pipeline, options) {
+Connection.prototype.watch = function watch(pipeline, options) {
   const changeStreamThunk = cb => {
     immediate(() => {
       if (this.readyState === STATES.connecting) {
@@ -1379,7 +1581,7 @@ Connection.prototype.asPromise = async function asPromise() {
  * @return {String[]}
  */
 
-Connection.prototype.modelNames = function() {
+Connection.prototype.modelNames = function modelNames() {
   return Object.keys(this.models);
 };
 
@@ -1391,7 +1593,7 @@ Connection.prototype.modelNames = function() {
  * @api private
  * @return {Boolean} true if the connection should be authenticated after it is opened, otherwise false.
  */
-Connection.prototype.shouldAuthenticate = function() {
+Connection.prototype.shouldAuthenticate = function shouldAuthenticate() {
   return this.user != null &&
     (this.pass != null || this.authMechanismDoesNotRequirePassword());
 };
@@ -1404,7 +1606,7 @@ Connection.prototype.shouldAuthenticate = function() {
  * @return {Boolean} true if the authentication mechanism specified in the options object requires
  *  a password, otherwise false.
  */
-Connection.prototype.authMechanismDoesNotRequirePassword = function() {
+Connection.prototype.authMechanismDoesNotRequirePassword = function authMechanismDoesNotRequirePassword() {
   if (this.options && this.options.auth) {
     return noPasswordAuthMechanisms.indexOf(this.options.auth.authMechanism) >= 0;
   }
@@ -1422,7 +1624,7 @@ Connection.prototype.authMechanismDoesNotRequirePassword = function() {
  * @return {Boolean} true if the provided options object provides enough data to authenticate with,
  *   otherwise false.
  */
-Connection.prototype.optionsProvideAuthenticationData = function(options) {
+Connection.prototype.optionsProvideAuthenticationData = function optionsProvideAuthenticationData(options) {
   return (options) &&
       (options.user) &&
       ((options.pass) || this.authMechanismDoesNotRequirePassword());

package/lib/cursor/aggregationCursor.js

@@ -175,11 +175,10 @@ AggregationCursor.prototype._markError = function(error) {
  * Marks this cursor as closed. Will stop streaming and subsequent calls to
  * `next()` will error.
  *
- * @param {Function} callback
  * @return {Promise}
  * @api public
  * @method close
- * @emits close
+ * @emits "close"
  * @see AggregationCursor.close https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html#close
  */
 

package/lib/document.js

@@ -624,16 +624,17 @@ Document.prototype.toBSON = function() {
 };
 
 /**
- * Initializes the document without setters or marking anything modified.
+ * Hydrates this document with the data in `doc`. Does not run setters or mark any paths modified.
  *
- * Called internally after a document is returned from mongodb. Normally,
+ * Called internally after a document is returned from MongoDB. Normally,
  * you do **not** need to call this function on your own.
  *
  * This function triggers `init` [middleware](https://mongoosejs.com/docs/middleware.html).
  * Note that `init` hooks are [synchronous](https://mongoosejs.com/docs/middleware.html#synchronous).
  *
- * @param {Object} doc document returned by mongo
+ * @param {Object} doc raw document returned by mongo
  * @param {Object} [opts]
+ * @param {Boolean} [opts.hydratedPopulatedDocs=false] If true, hydrate and mark as populated any paths that are populated in the raw document
  * @param {Function} [fn]
  * @api public
  * @memberOf Document
@@ -805,6 +806,14 @@ function init(self, obj, doc, opts, prefix) {
               reason: e
             }));
           }
+        } else if (opts.hydratedPopulatedDocs) {
+          doc[i] = schemaType.cast(value, self, true);
+
+          if (doc[i] && doc[i].$__ && doc[i].$__.wasPopulated) {
+            self.$populated(path, doc[i].$__.wasPopulated.value, doc[i].$__.wasPopulated.options);
+          } else if (Array.isArray(doc[i]) && doc[i].length && doc[i][0]?.$__?.wasPopulated) {
+            self.$populated(path, doc[i].map(populatedDoc => populatedDoc?.$__?.wasPopulated?.value).filter(val => val != null), doc[i][0].$__.wasPopulated.options);
+          }
         } else {
           doc[i] = value;
         }
@@ -822,7 +831,7 @@ function init(self, obj, doc, opts, prefix) {
  *
  * #### Example:
  *
- *     weirdCar.updateOne({$inc: {wheels:1}}, { w: 1 }, callback);
+ *     weirdCar.updateOne({$inc: {wheels:1}}, { w: 1 });
  *
  * #### Valid options:
  *
@@ -834,7 +843,6 @@ function init(self, obj, doc, opts, prefix) {
  * @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} [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 {Function} [callback]
  * @return {Query}
  * @api public
  * @memberOf Document
@@ -1768,6 +1776,11 @@ Document.prototype.$__set = function(pathToMark, path, options, constructing, pa
  */
 
 Document.prototype.$__getValue = function(path) {
+  if (typeof path !== 'string' && !Array.isArray(path)) {
+    throw new TypeError(
+      `Invalid \`path\`. Must be either string or array. Got "${path}" (type ${typeof path})`
+    );
+  }
   return utils.getValue(path, this._doc);
 };
 
@@ -3430,12 +3443,11 @@ 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 {Function} [fn] optional callback
  * @method save
  * @memberOf Document
  * @instance
  * @throws {DocumentNotFoundError} if this [save updates an existing document](https://mongoosejs.com/docs/api/document.html#Document.prototype.isNew()) but the document doesn't exist in the database. For example, you will get this error if the document is [deleted between when you retrieved the document and when you saved it](documents.html#updating).
- * @return {Promise|undefined} Returns undefined if used with callback or a Promise otherwise.
+ * @return {Promise}
  * @api public
  * @see middleware https://mongoosejs.com/docs/middleware.html
  */

package/lib/drivers/node-mongodb-native/collection.js

@@ -454,7 +454,6 @@ function format(obj, sub, color, shell) {
 /**
  * Retrieves information about this collections indexes.
  *
- * @param {Function} callback
  * @method getIndexes
  * @api public
  */

package/lib/drivers/node-mongodb-native/connection.js

@@ -426,9 +426,6 @@ function _setClient(conn, client, options, dbName) {
   }
 
   conn.onOpen();
-  if (client.topology?.s?.state === 'connected') {
-    conn._lastHeartbeatAt = Date.now();
-  }
 
   for (const i in conn.collections) {
     if (utils.object.hasOwnProperty(conn.collections, i)) {
@@ -437,7 +434,6 @@ function _setClient(conn, client, options, dbName) {
   }
 }
 
-
 /*!
  * Module exports.
  */

package/lib/helpers/clone.js

@@ -11,6 +11,7 @@ const isObject = require('./isObject');
 const isPOJO = require('./isPOJO');
 const symbols = require('./symbols');
 const trustedSymbol = require('./query/trusted').trustedSymbol;
+const BSON = require('bson');
 
 /**
  * Object clone with Mongoose natives support.
@@ -30,6 +31,10 @@ function clone(obj, options, isArrayChild) {
   if (obj == null) {
     return obj;
   }
+
+  if (isBsonType(obj, 'Double')) {
+    return new BSON.Double(obj.value);
+  }
   if (typeof obj === 'number' || typeof obj === 'string' || typeof obj === 'boolean' || typeof obj === 'bigint') {
     return obj;
   }