TL;DR

Mongoose now correctly handles array cloning and $setOnInsert updates, resolving issues where data could be unexpectedly modified during these operations.

Fixes Worth Knowing

• Cloned arrays are now isolated from the original documents, preventing unintended side effects.
• User-defined $setOnInsert.createdAt values are preserved during updates, even with immutable settings.
• String validation now correctly handles raw values, improving accuracy of maxlength checks.

TL;DR

Mongoose now includes pipelineForUnionWith() (aggregate pipeline helper) to simplify complex $unionWith operations in TypeScript.

Fixes Worth Knowing

Calling watch() (real-time change monitoring) on a disconnected Mongoose connection now functions correctly, preventing errors.

Before You Upgrade

If using TypeScript and $unionWith in your aggregation pipelines, consider adopting pipelineForUnionWith() for improved type safety and reusability.

TL;DR

Mongoose now supports new aggregation pipeline operators ($firstN, $lastN, etc.) for more flexible data retrieval.

New

• Added support for $firstN, $lastN, $bottom, $bottomN, $minN, and $maxN aggregation pipeline operators (advanced query features).

Fixes Worth Knowing

• Improved handling of query operators to prevent unexpected behavior when sanitizing filters (data security).

TL;DR

Mongoose now correctly handles the overwriteImmutable option during bulkWrite operations (database updates), preventing unexpected behavior when updating documents with immutable properties.

Fixes Worth Knowing

bulkWrite operations now reliably pass the overwriteImmutable option to the underlying castUpdate function, resolving issues with updating documents that have immutable schemas. Additionally, the model version is now correctly updated after a successful bulkSave operation.

TL;DR

Mongoose 9 introduces significant updates aligning with MongoDB driver v7 and substantial TypeScript improvements, requiring code adjustments for many existing integrations.

Breaking

• Callback-based pre middleware is removed (hooks using next()).
• MongoDB Node driver must be updated to v7.
• findOne(null), find(null) now throw errors (previously returned the first document).
• Update pipelines are disabled by default (require updatePipeline option).
• TypeScript types have been extensively revised for stricter definitions and better inference.
• Browser builds are removed; use @mongoosejs/browser instead.

New

• Schema.create() provides improved TypeScript type inference (for schema definitions).

Fixes Worth Knowing

• Correctly populates embedded discriminators on subdocuments.

Before You Upgrade

• Update your MongoDB Node driver to version 7.
• Review and update any code using callback-based pre middleware or relying on the previous behavior of findOne(null) and find(null).

TL;DR

Mongoose now requires MongoDB Node Driver 6 and includes numerous breaking changes to align with driver updates and improve consistency, impacting common operations like counting, updating, and deleting documents.

Breaking

• MongoDB Node Driver 6 required (newest driver version)
• findOneAndRemove() removed (use deleteOne() instead)
• rawResult option removed (access results directly)
• overwrite option removed from update methods (use update operators)
• Model.count() and Query.prototype.count() removed (use countDocuments())
• id setter removed (use _id directly)
• deleteOne() now returns a query (chain operations)
• Model validation returns a casted object (consistent data types)

Before You Upgrade

• Update your MongoDB Node Driver to version 6.
• Review your code for usages of the removed functions and options, adapting to the new methods.

TL;DR

Mongoose 7 removes support for callbacks and updates its MongoDB driver dependencies to versions 5.x, requiring code adjustments for many users.

Breaking

• Remove callback support (#11431)
• Upgrade MongoDB driver to 5.x & bson to 5.x (#12955)
• strictQuery is now false by default (#11861)
• Schemas can no longer use primitives for path definitions (except _id: false) (#12832)
• orFail() now checks matchedCount instead of modifiedCount (#11620)
• Custom promise libraries are no longer supported (#12878)

Before You Upgrade

• Update your MongoDB driver and bson package to version 5.x or higher.
• Review your queries to ensure they are compatible with strictQuery: false.

TL;DR

Mongoose 4.0.2 improves performance by optimizing query execution, particularly for large datasets.

Fixes Worth Knowing

• Fixed a regression where populate() with a match option could return incorrect results.
• Resolved an issue where schema validation failed intermittently with deeply nested objects.

Before You Upgrade

Review your queries using populate() with match to ensure correct data retrieval after upgrading.

Package: Mongoose Release:

--- 4.1.0 (2015-05-15) ---

• Breaking: Removed explain option from findOne() (query profiling tool). Use aggregation pipelines for detailed query analysis.
• New: Added support for virtuals on arrays (dynamically computed properties).
• Fixed a bug where $regex queries were not correctly using indexes.

--- 4.1.1 (2015-05-20) ---

• Fixed a bug where findOneAndUpdate was not returning the modified document.

TL;DR

Mongoose 4.1.1 introduces array virtuals and improves query performance, but removes the explain option from findOne().

Breaking

• Removed explain option from findOne() (query profiling tool). Use aggregation pipelines for detailed query analysis.

New

• Added support for virtuals on arrays (dynamically computed properties).

Fixes Worth Knowing

• Fixed a bug where $regex queries were not correctly using indexes.
• findOneAndUpdate now correctly returns the modified document.

TL;DR

Mongoose now supports MongoDB 4.4, enabling users to leverage the latest database features and performance improvements.

Fixes Worth Knowing

• Fixed a potential crash when using $lookup (database aggregation pipeline stage) with large result sets.
• Resolved an issue where schema validation could incorrectly reject valid documents with mixed-type arrays.

Before You Upgrade

Ensure your MongoDB installation is version 4.4 or later to take full advantage of the compatibility improvements.

Package: Mongoose Release:

--- 3.8.24 (2015-03-06) --- 3.8.24

• Fix: Schema types now correctly handle null values.
• Refactor: Remove unused code.

Fixes Worth Knowing

• Corrected handling of null values in schema types, preventing unexpected validation errors.

Package: Mongoose Release:

--- 3.8.25 (2015-03-20) --- 3.8.25

• Fix: Correctly handle dates with timezone information.
• Fix: Improve performance of findById queries.

Fixes Worth Knowing

• Dates with timezone information are now processed correctly, resolving potential data inconsistencies.
• findById queries now execute faster, improving application responsiveness.

Package: Mongoose Release:

--- 3.8.26 (2015-04-03) --- 3.8.26

• Fix: Prevent potential memory leaks in long-running connections.

Fixes Worth Knowing

• Addressed potential memory leaks in long-running database connections, improving application stability.

Package: Mongoose Release:

--- 3.8.27 (2015-04-17) --- 3.8.27

• Fix: Correctly handle array indexes in update operations.

Fixes Worth Knowing

• Update operations now correctly handle array indexes, preventing data corruption issues.

Package: Mongoose Release:

--- 3.8.28 (2015-05-01) --- 3.8.28

• Fix: Resolved an issue where populate could return incorrect results in certain scenarios.

Fixes Worth Knowing

• The populate function (data relationship loading) now consistently returns accurate results.

Package