mongoose 8.7.2 → 8.8.0

package/lib/cast.js

@@ -28,6 +28,7 @@ const ALLOWED_GEOWITHIN_GEOJSON_TYPES = ['Polygon', 'MultiPolygon'];
  * @param {Object} [options] the query options
  * @param {Boolean|"throw"} [options.strict] Wheter to enable all strict options
  * @param {Boolean|"throw"} [options.strictQuery] Enable strict Queries
+ * @param {Boolean} [options.sanitizeFilter] avoid adding implict query selectors ($in)
  * @param {Boolean} [options.upsert]
  * @param {Query} [context] passed to setters
  * @api private
@@ -372,7 +373,7 @@ module.exports = function cast(schema, obj, options, context) {
 
           }
         }
-      } else if (Array.isArray(val) && ['Buffer', 'Array'].indexOf(schematype.instance) === -1) {
+      } else if (Array.isArray(val) && ['Buffer', 'Array'].indexOf(schematype.instance) === -1 && !options.sanitizeFilter) {
         const casted = [];
         const valuesArray = val;
 

package/lib/cursor/aggregationCursor.js

@@ -196,6 +196,37 @@ AggregationCursor.prototype.close = async function close() {
   this.emit('close');
 };
 
+/**
+ * Marks this cursor as destroyed. Will stop streaming and subsequent calls to
+ * `next()` will error.
+ *
+ * @return {this}
+ * @api private
+ * @method _destroy
+ */
+
+AggregationCursor.prototype._destroy = function _destroy(_err, callback) {
+  let waitForCursor = null;
+  if (!this.cursor) {
+    waitForCursor = new Promise((resolve) => {
+      this.once('cursor', resolve);
+    });
+  } else {
+    waitForCursor = Promise.resolve();
+  }
+
+  waitForCursor
+    .then(() => this.cursor.close())
+    .then(() => {
+      this._closed = true;
+      callback();
+    })
+    .catch(error => {
+      callback(error);
+    });
+  return this;
+};
+
 /**
  * Get the next document from this cursor. Will return `null` when there are
  * no documents left.

package/lib/cursor/queryCursor.js

@@ -238,6 +238,39 @@ QueryCursor.prototype.close = async function close() {
   }
 };
 
+/**
+ * Marks this cursor as destroyed. Will stop streaming and subsequent calls to
+ * `next()` will error.
+ *
+ * @return {this}
+ * @api private
+ * @method _destroy
+ */
+
+QueryCursor.prototype._destroy = function _destroy(_err, callback) {
+  let waitForCursor = null;
+  if (!this.cursor) {
+    waitForCursor = new Promise((resolve) => {
+      this.once('cursor', resolve);
+    });
+  } else {
+    waitForCursor = Promise.resolve();
+  }
+
+  waitForCursor
+    .then(() => {
+      this.cursor.close();
+    })
+    .then(() => {
+      this._closed = true;
+      callback();
+    })
+    .catch(error => {
+      callback(error);
+    });
+  return this;
+};
+
 /**
  * Rewind this cursor to its uninitialized state. Any options that are present on the cursor will
  * remain in effect. Iterating this cursor will cause new queries to be sent to the server, even

package/lib/helpers/document/applyTimestamps.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const handleTimestampOption = require('../schema/handleTimestampOption');
+const mpath = require('mpath');
+
+module.exports = applyTimestamps;
+
+/**
+ * Apply a given schema's timestamps to the given POJO
+ *
+ * @param {Schema} schema
+ * @param {Object} obj
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ */
+
+function applyTimestamps(schema, obj, options) {
+  if (obj == null) {
+    return obj;
+  }
+
+  applyTimestampsToChildren(schema, obj, options);
+  return applyTimestampsToDoc(schema, obj, options);
+}
+
+/**
+ * Apply timestamps to any subdocuments
+ *
+ * @param {Schema} schema subdocument schema
+ * @param {Object} res subdocument
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ */
+
+function applyTimestampsToChildren(schema, res, options) {
+  for (const childSchema of schema.childSchemas) {
+    const _path = childSchema.model.path;
+    const _schema = childSchema.schema;
+    if (!_path) {
+      continue;
+    }
+    const _obj = mpath.get(_path, res);
+    if (_obj == null || (Array.isArray(_obj) && _obj.flat(Infinity).length === 0)) {
+      continue;
+    }
+
+    applyTimestamps(_schema, _obj, options);
+  }
+}
+
+/**
+ * Apply timestamps to a given document. Does not apply timestamps to subdocuments: use `applyTimestampsToChildren` instead
+ *
+ * @param {Schema} schema
+ * @param {Object} obj
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ */
+
+function applyTimestampsToDoc(schema, obj, options) {
+  if (obj == null || typeof obj !== 'object') {
+    return;
+  }
+  if (Array.isArray(obj)) {
+    for (const el of obj) {
+      applyTimestampsToDoc(schema, el, options);
+    }
+    return;
+  }
+
+  if (schema.discriminators && Object.keys(schema.discriminators).length > 0) {
+    for (const discriminatorKey of Object.keys(schema.discriminators)) {
+      const discriminator = schema.discriminators[discriminatorKey];
+      const key = discriminator.discriminatorMapping.key;
+      const value = discriminator.discriminatorMapping.value;
+      if (obj[key] == value) {
+        schema = discriminator;
+        break;
+      }
+    }
+  }
+
+  const createdAt = handleTimestampOption(schema.options.timestamps, 'createdAt');
+  const updatedAt = handleTimestampOption(schema.options.timestamps, 'updatedAt');
+  const currentTime = options?.currentTime;
+
+  let ts = null;
+  if (currentTime != null) {
+    ts = currentTime();
+  } else if (schema.base?.now) {
+    ts = schema.base.now();
+  } else {
+    ts = new Date();
+  }
+
+  if (createdAt && obj[createdAt] == null && !options?.isUpdate) {
+    obj[createdAt] = ts;
+  }
+  if (updatedAt) {
+    obj[updatedAt] = ts;
+  }
+}

package/lib/model.js

@@ -10,6 +10,7 @@ const Document = require('./document');
 const DocumentNotFoundError = require('./error/notFound');
 const EventEmitter = require('events').EventEmitter;
 const Kareem = require('kareem');
+const { MongoBulkWriteError } = require('mongodb');
 const MongooseBulkWriteError = require('./error/bulkWriteError');
 const MongooseError = require('./error/index');
 const ObjectParameterError = require('./error/objectParameter');
@@ -30,6 +31,7 @@ const applyReadConcern = require('./helpers/schema/applyReadConcern');
 const applySchemaCollation = require('./helpers/indexes/applySchemaCollation');
 const applyStaticHooks = require('./helpers/model/applyStaticHooks');
 const applyStatics = require('./helpers/model/applyStatics');
+const applyTimestampsHelper = require('./helpers/document/applyTimestamps');
 const applyWriteConcern = require('./helpers/schema/applyWriteConcern');
 const applyVirtualsHelper = require('./helpers/document/applyVirtuals');
 const assignVals = require('./helpers/populate/assignVals');
@@ -1219,6 +1221,7 @@ Model.createCollection = async function createCollection(options) {
  *
  * @param {Object} [options] options to pass to `ensureIndexes()`
  * @param {Boolean} [options.background=null] if specified, overrides each index's `background` property
+ * @param {Boolean} [options.hideIndexes=false] set to `true` to hide indexes instead of dropping. Requires MongoDB server 4.4 or higher
  * @return {Promise}
  * @api public
  */
@@ -1439,8 +1442,10 @@ function getIndexesToDrop(schema, schemaIndexes, dbIndexes) {
  *
  * The returned promise resolves to a list of the dropped indexes' names as an array
  *
- * @param {Function} [callback] optional callback
- * @return {Promise|undefined} Returns `undefined` if callback is specified, returns a promise if no callback.
+ * @param {Object} [options]
+ * @param {Array<String>} [options.toDrop] if specified, contains a list of index names to drop
+ * @param {Boolean} [options.hideIndexes=false] set to `true` to hide indexes instead of dropping. Requires MongoDB server 4.4 or higher
+ * @return {Promise<String>} list of dropped or hidden index names
  * @api public
  */
 
@@ -1451,23 +1456,32 @@ Model.cleanIndexes = async function cleanIndexes(options) {
   }
   const model = this;
 
-  const collection = model.$__collection;
-
   if (Array.isArray(options && options.toDrop)) {
-    const res = await _dropIndexes(options.toDrop, collection);
+    const res = await _dropIndexes(options.toDrop, model, options);
     return res;
   }
 
   const res = await model.diffIndexes();
-  return await _dropIndexes(res.toDrop, collection);
+  return await _dropIndexes(res.toDrop, model, options);
 };
 
-async function _dropIndexes(toDrop, collection) {
+async function _dropIndexes(toDrop, model, options) {
   if (toDrop.length === 0) {
     return [];
   }
 
-  await Promise.all(toDrop.map(indexName => collection.dropIndex(indexName)));
+  const collection = model.$__collection;
+  if (options && options.hideIndexes) {
+    await Promise.all(toDrop.map(indexName => {
+      return model.db.db.command({
+        collMod: collection.collectionName,
+        index: { name: indexName, hidden: true }
+      });
+    }));
+  } else {
+    await Promise.all(toDrop.map(indexName => collection.dropIndex(indexName)));
+  }
+
   return toDrop;
 }
 
@@ -1653,7 +1667,24 @@ function _ensureIndexes(model, options, callback) {
       }
     }
 
-    model.collection.createIndex(indexFields, indexOptions).then(
+    // Just in case `createIndex()` throws a sync error
+    let promise = null;
+    try {
+      promise = model.collection.createIndex(indexFields, indexOptions);
+    } catch (err) {
+      if (!indexError) {
+        indexError = err;
+      }
+      if (!model.$caught) {
+        model.emit('error', err);
+      }
+
+      indexSingleDone(err, indexFields, indexOptions);
+      create();
+      return;
+    }
+
+    promise.then(
       name => {
         indexSingleDone(null, indexFields, indexOptions, name);
         create();
@@ -3417,6 +3448,11 @@ Model.bulkSave = async function bulkSave(documents, options) {
     (err) => ({ bulkWriteResult: null, bulkWriteError: err })
   );
 
+  // If not a MongoBulkWriteError, treat this as all documents failed to save.
+  if (bulkWriteError != null && !(bulkWriteError instanceof MongoBulkWriteError)) {
+    throw bulkWriteError;
+  }
+
   const matchedCount = bulkWriteResult?.matchedCount ?? 0;
   const insertedCount = bulkWriteResult?.insertedCount ?? 0;
   if (writeOperations.length > 0 && matchedCount + insertedCount < writeOperations.length && !bulkWriteError) {
@@ -3540,6 +3576,41 @@ Model.applyVirtuals = function applyVirtuals(obj, virtualsToApply) {
   return obj;
 };
 
+/**
+ * Apply this model's timestamps to a given POJO, including subdocument timestamps
+ *
+ * #### Example:
+ *
+ *     const userSchema = new Schema({ name: String }, { timestamps: true });
+ *     const User = mongoose.model('User', userSchema);
+ *
+ *     const obj = { name: 'John' };
+ *     User.applyTimestamps(obj);
+ *     obj.createdAt; // 2024-06-01T18:00:00.000Z
+ *     obj.updatedAt; // 2024-06-01T18:00:00.000Z
+ *
+ * @param {Object} obj object or document to apply virtuals on
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ * @returns {Object} obj
+ * @api public
+ */
+
+Model.applyTimestamps = function applyTimestamps(obj, options) {
+  if (obj == null) {
+    return obj;
+  }
+  // Nothing to do if this is already a hydrated document - it should already have timestamps
+  if (obj.$__ != null) {
+    return obj;
+  }
+
+  applyTimestampsHelper(this.schema, obj, options);
+
+  return obj;
+};
+
 /**
  * Cast the given POJO to the model's schema
  *

package/lib/query.js

@@ -1142,6 +1142,38 @@ Query.prototype.select = function select() {
   throw new TypeError('Invalid select() argument. Must be string or object.');
 };
 
+/**
+ * Enable or disable schema level projections for this query. Enabled by default.
+ * Set to `false` to include fields with `select: false` in the query result by default.
+ *
+ * #### Example:
+ *
+ *     const userSchema = new Schema({
+ *       email: { type: String, required: true },
+ *       passwordHash: { type: String, select: false, required: true }
+ *     });
+ *     const UserModel = mongoose.model('User', userSchema);
+ *
+ *     const doc = await UserModel.findOne().orFail().schemaLevelProjections(false);
+ *
+ *     // Contains password hash, because `schemaLevelProjections()` overrides `select: false`
+ *     doc.passwordHash;
+ *
+ * @method schemaLevelProjections
+ * @memberOf Query
+ * @instance
+ * @param {Boolean} value
+ * @return {Query} this
+ * @see SchemaTypeOptions https://mongoosejs.com/docs/schematypes.html#all-schema-types
+ * @api public
+ */
+
+Query.prototype.schemaLevelProjections = function schemaLevelProjections(value) {
+  this._mongooseOptions.schemaLevelProjections = value;
+
+  return this;
+};
+
 /**
  * Sets this query's `sanitizeProjection` option. If set, `sanitizeProjection` does
  * two things:
@@ -1689,6 +1721,10 @@ Query.prototype.setOptions = function(options, overwrite) {
     this._mongooseOptions.translateAliases = options.translateAliases;
     delete options.translateAliases;
   }
+  if ('schemaLevelProjections' in options) {
+    this._mongooseOptions.schemaLevelProjections = options.schemaLevelProjections;
+    delete options.schemaLevelProjections;
+  }
 
   if (options.lean == null && this.schema && 'lean' in this.schema.options) {
     this._mongooseOptions.lean = this.schema.options.lean;
@@ -2222,6 +2258,7 @@ Query.prototype._unsetCastError = function _unsetCastError() {
  * - `strict`: controls how Mongoose handles keys that aren't in the schema for updates. This option is `true` by default, which means Mongoose will silently strip any paths in the update that aren't in the schema. See the [`strict` mode docs](https://mongoosejs.com/docs/guide.html#strict) for more information.
  * - `strictQuery`: controls how Mongoose handles keys that aren't in the schema for the query `filter`. This option is `false` by default, which means Mongoose will allow `Model.find({ foo: 'bar' })` even if `foo` is not in the schema. See the [`strictQuery` docs](https://mongoosejs.com/docs/guide.html#strictQuery) for more information.
  * - `nearSphere`: use `$nearSphere` instead of `near()`. See the [`Query.prototype.nearSphere()` docs](https://mongoosejs.com/docs/api/query.html#Query.prototype.nearSphere())
+ * - `schemaLevelProjections`: if `false`, Mongoose will not apply schema-level `select: false` or `select: true` for this query
  *
  * Mongoose maintains a separate object for internal options because
  * Mongoose sends `Query.prototype.options` to the MongoDB server, and the
@@ -4863,6 +4900,9 @@ Query.prototype.cast = function(model, obj) {
       opts.strictQuery = this.options.strictQuery;
     }
   }
+  if ('sanitizeFilter' in this._mongooseOptions) {
+    opts.sanitizeFilter = this._mongooseOptions.sanitizeFilter;
+  }
 
   try {
     return cast(model.schema, obj, opts, this);
@@ -4946,7 +4986,11 @@ Query.prototype._applyPaths = function applyPaths() {
     sanitizeProjection = this._mongooseOptions.sanitizeProjection;
   }
 
-  helpers.applyPaths(this._fields, this.model.schema, sanitizeProjection);
+  const schemaLevelProjections = this._mongooseOptions.schemaLevelProjections ?? true;
+
+  if (schemaLevelProjections) {
+    helpers.applyPaths(this._fields, this.model.schema, sanitizeProjection);
+  }
 
   let _selectPopulatedPaths = true;
 

package/lib/schema/array.js

@@ -11,9 +11,12 @@ const SchemaArrayOptions = require('../options/schemaArrayOptions');
 const SchemaType = require('../schemaType');
 const CastError = SchemaType.CastError;
 const Mixed = require('./mixed');
+const VirtualOptions = require('../options/virtualOptions');
+const VirtualType = require('../virtualType');
 const arrayDepth = require('../helpers/arrayDepth');
 const cast = require('../cast');
 const clone = require('../helpers/clone');
+const getConstructorName = require('../helpers/getConstructorName');
 const isOperator = require('../helpers/query/isOperator');
 const util = require('util');
 const utils = require('../utils');
@@ -217,6 +220,12 @@ SchemaArray._checkRequired = SchemaType.prototype.checkRequired;
 
 SchemaArray.checkRequired = SchemaType.checkRequired;
 
+/*!
+ * Virtuals defined on this array itself.
+ */
+
+SchemaArray.prototype.virtuals = null;
+
 /**
  * Check if the given value satisfies the `required` validator.
  *
@@ -575,6 +584,32 @@ SchemaArray.prototype.castForQuery = function($conditional, val, context) {
   }
 };
 
+/**
+ * Add a virtual to this array. Specifically to this array, not the individual elements.
+ *
+ * @param {String} name
+ * @param {Object} [options]
+ * @api private
+ */
+
+SchemaArray.prototype.virtual = function virtual(name, options) {
+  if (name instanceof VirtualType || getConstructorName(name) === 'VirtualType') {
+    return this.virtual(name.path, name.options);
+  }
+  options = new VirtualOptions(options);
+
+  if (utils.hasUserDefinedProperty(options, ['ref', 'refPath'])) {
+    throw new MongooseError('Cannot set populate virtual as a property of an array');
+  }
+
+  const virtual = new VirtualType(options, name);
+  if (this.virtuals === null) {
+    this.virtuals = {};
+  }
+  this.virtuals[name] = virtual;
+  return virtual;
+};
+
 function cast$all(val, context) {
   if (!Array.isArray(val)) {
     val = [val];

package/lib/schema/documentArray.js

@@ -429,7 +429,7 @@ SchemaDocumentArray.prototype.cast = function(value, doc, init, prev, options) {
   // We need to create a new array, otherwise change tracking will
   // update the old doc (gh-4449)
   if (!options.skipDocumentArrayCast || utils.isMongooseDocumentArray(value)) {
-    value = new MongooseDocumentArray(value, path, doc);
+    value = new MongooseDocumentArray(value, path, doc, this);
   }
 
   if (prev != null) {

package/lib/schema.js

@@ -2304,6 +2304,7 @@ Schema.prototype.indexes = function() {
  * @param {Boolean} [options.count=false] Only works with populate virtuals. If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), this populate virtual will contain the number of documents rather than the documents themselves when you `populate()`.
  * @param {Function|null} [options.get=null] Adds a [getter](https://mongoosejs.com/docs/tutorials/getters-setters.html) to this virtual to transform the populated doc.
  * @param {Object|Function} [options.match=null] Apply a default [`match` option to populate](https://mongoosejs.com/docs/populate.html#match), adding an additional filter to the populate query.
+ * @param {Boolean} [options.applyToArray=false] If true and the given `name` is a direct child of an array, apply the virtual to the array rather than the elements.
  * @return {VirtualType}
  */
 
@@ -2416,6 +2417,15 @@ Schema.prototype.virtual = function(name, options) {
     return mem[part];
   }, this.tree);
 
+  if (options && options.applyToArray && parts.length > 1) {
+    const path = this.path(parts.slice(0, -1).join('.'));
+    if (path && path.$isMongooseArray) {
+      return path.virtual(parts[parts.length - 1], options);
+    } else {
+      throw new MongooseError(`Path "${path}" is not an array`);
+    }
+  }
+
   return virtuals[name];
 };
 

package/lib/types/array/index.js

@@ -90,6 +90,9 @@ function MongooseArray(values, path, doc, schematype) {
       if (mongooseArrayMethods.hasOwnProperty(prop)) {
         return mongooseArrayMethods[prop];
       }
+      if (schematype && schematype.virtuals && schematype.virtuals.hasOwnProperty(prop)) {
+        return schematype.virtuals[prop].applyGetters(undefined, target);
+      }
       if (typeof prop === 'string' && numberRE.test(prop) && schematype?.$embeddedSchemaType != null) {
         return schematype.$embeddedSchemaType.applyGetters(__array[prop], doc);
       }
@@ -101,6 +104,8 @@ function MongooseArray(values, path, doc, schematype) {
         mongooseArrayMethods.set.call(proxy, prop, value, false);
       } else if (internals.hasOwnProperty(prop)) {
         internals[prop] = value;
+      } else if (schematype && schematype.virtuals && schematype.virtuals.hasOwnProperty(prop)) {
+        schematype.virtuals[prop].applySetters(value, target);
       } else {
         __array[prop] = value;
       }

package/lib/types/documentArray/index.js

@@ -28,7 +28,7 @@ const numberRE = /^\d+$/;
  * @see https://bit.ly/f6CnZU
  */
 
-function MongooseDocumentArray(values, path, doc) {
+function MongooseDocumentArray(values, path, doc, schematype) {
   const __array = [];
 
   const internals = {
@@ -84,6 +84,9 @@ function MongooseDocumentArray(values, path, doc) {
       if (DocumentArrayMethods.hasOwnProperty(prop)) {
         return DocumentArrayMethods[prop];
       }
+      if (schematype && schematype.virtuals && schematype.virtuals.hasOwnProperty(prop)) {
+        return schematype.virtuals[prop].applyGetters(undefined, target);
+      }
       if (ArrayMethods.hasOwnProperty(prop)) {
         return ArrayMethods[prop];
       }
@@ -95,6 +98,8 @@ function MongooseDocumentArray(values, path, doc) {
         DocumentArrayMethods.set.call(proxy, prop, value, false);
       } else if (internals.hasOwnProperty(prop)) {
         internals[prop] = value;
+      } else if (schematype && schematype.virtuals && schematype.virtuals.hasOwnProperty(prop)) {
+        schematype.virtuals[prop].applySetters(value, target);
       } else {
         __array[prop] = value;
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "8.7.2",
+  "version": "8.8.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -21,7 +21,7 @@
   "dependencies": {
     "bson": "^6.7.0",
     "kareem": "2.6.3",
-    "mongodb": "6.9.0",
+    "mongodb": "~6.10.0",
     "mpath": "0.9.0",
     "mquery": "5.0.0",
     "ms": "2.1.3",

package/types/connection.d.ts

@@ -50,6 +50,12 @@ declare module 'mongoose' {
     autoIndex?: boolean;
     /** Set to `false` to disable Mongoose automatically calling `createCollection()` on every model created on this connection. */
     autoCreate?: boolean;
+    /**
+     * Sanitizes query filters against [query selector injection attacks](
+     * https://thecodebarbarian.com/2014/09/04/defending-against-query-selector-injection-attacks.html
+     * ) by wrapping any nested objects that have a property whose name starts with $ in a $eq.
+     */
+    sanitizeFilter?: boolean;
   }
 
   class Connection extends events.EventEmitter implements SessionStarter {

package/types/cursor.d.ts

@@ -26,6 +26,12 @@ declare module 'mongoose' {
      */
     close(): Promise<void>;
 
+    /**
+     * Destroy this cursor, closing the underlying cursor. Will stop streaming
+     * and subsequent calls to `next()` will error.
+     */
+    destroy(): this;
+
     /**
      * Rewind this cursor to its uninitialized state. Any options that are present on the cursor will
      * remain in effect. Iterating this cursor will cause new queries to be sent to the server, even

package/types/document.d.ts

@@ -256,10 +256,17 @@ declare module 'mongoose' {
     set(value: string | Record<string, any>): this;
 
     /** The return value of this method is used in calls to JSON.stringify(doc). */
-    toJSON(options?: ToObjectOptions & { flattenMaps?: true }): FlattenMaps<Require_id<DocType>>;
+    toJSON(options?: ToObjectOptions & { flattenMaps?: true, flattenObjectIds?: false }): FlattenMaps<Require_id<DocType>>;
+    toJSON(options: ToObjectOptions & { flattenObjectIds: false }): FlattenMaps<Require_id<DocType>>;
+    toJSON(options: ToObjectOptions & { flattenObjectIds: true }): ObjectIdToString<FlattenMaps<Require_id<DocType>>>;
     toJSON(options: ToObjectOptions & { flattenMaps: false }): Require_id<DocType>;
-    toJSON<T = Require_id<DocType>>(options?: ToObjectOptions & { flattenMaps?: true }): FlattenMaps<T>;
+    toJSON(options: ToObjectOptions & { flattenMaps: false; flattenObjectIds: true }): ObjectIdToString<Require_id<DocType>>;
+
+    toJSON<T = Require_id<DocType>>(options?: ToObjectOptions & { flattenMaps?: true, flattenObjectIds?: false }): FlattenMaps<T>;
+    toJSON<T = Require_id<DocType>>(options: ToObjectOptions & { flattenObjectIds: false }): FlattenMaps<T>;
+    toJSON<T = Require_id<DocType>>(options: ToObjectOptions & { flattenObjectIds: true }): ObjectIdToString<FlattenMaps<T>>;
     toJSON<T = Require_id<DocType>>(options: ToObjectOptions & { flattenMaps: false }): T;
+    toJSON<T = Require_id<DocType>>(options: ToObjectOptions & { flattenMaps: false; flattenObjectIds: true }): ObjectIdToString<T>;
 
     /** Converts this document into a plain-old JavaScript object ([POJO](https://masteringjs.io/tutorials/fundamentals/pojo)). */
     toObject(options?: ToObjectOptions): Require_id<DocType>;