8.0

.eslintrc.js

@@ -23,6 +23,9 @@ module.exports = {
         '**/*.md/*.ts',
         '**/*.md/*.typescript'
       ],
+      parserOptions: {
+        project: './tsconfig.json'
+      },
       extends: [
         'plugin:@typescript-eslint/eslint-recommended',
         'plugin:@typescript-eslint/recommended'

.github/workflows/test.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d # v3.8.1
         with:
-          node-version: 14
+          node-version: 18
 
       - run: npm install
 
@@ -39,7 +39,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: [14, 16, 18, 20]
+        node: [16, 18, 20]
         os: [ubuntu-20.04, ubuntu-22.04]
         mongodb: [4.4.18, 5.0.14, 6.0.4]
         include:
@@ -108,7 +108,7 @@ jobs:
       - name: Setup Deno
         uses: denoland/setup-deno@v1
         with:
-          deno-version: v1.34.x
+          deno-version: v1.36.x
       - run: deno --version
       - run: npm install
       - name: Run Deno tests

.github/workflows/tsd.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d # v3.8.1
         with:
-          node-version: 14
+          node-version: 18
 
       - run: npm install
 

CHANGELOG.md

@@ -1,3 +1,20 @@
+8.0.0-rc0 / 2023-10-24
+======================
+ * BREAKING CHANGE: use MongoDB node driver 6, drop support for rawResult option and findOneAndRemove() #13753
+ * BREAKING CHANGE: apply minimize by default when updating document #13843
+ * BREAKING CHANGE: remove `id` setter #13784
+ * BREAKING CHANGE: remove overwrite option for updateOne(), findOneAndUpdate(), etc. #13989 #13578
+ * BREAKING CHANGE: make model.prototype.deleteOne() return query, not promise #13660 #13369
+ * BREAKING CHANGE: remove `Model.count()`, `Query.prototype.count()` #13618 #13598
+ * BREAKING CHANGE: allow null values for string enum #13620 #3044
+ * BREAKING CHANGE: make base schema paths come before discriminator schema paths when running setters, validators, etc. #13846 #13794
+ * BREAKING CHANGE: make Model.validate() use Model.castObject() to cast, and return casted copy of object instead of modifying in place #13287 #12668
+ * BREAKING CHANGE: make internal file names all camelCase #13950 #13909 #13308
+ * BREAKING CHANGE: make create() wait for all documents to finish inserting or error out before throwing an error if ordered = false #13621 #4628
+ * BREAKING CHANGE: refactor out `mongoose/lib/mongoose.js` file to allow importing Mongoose without MongoDB driver #13905
+ * BREAKING CHANGE(types): allow `null` for optional fields #13901
+ * BREAKING CHANGE(types): infer return types types for Model.distinct and Query.distinct #13836 [kaulshashank](https://github.com/kaulshashank)
+
 7.6.3 / 2023-10-17
 ==================
  * fix(populate): handle multiple spaces when specifying paths to populate using space-delimited paths #13984 #13951

docs/middleware.md

@@ -48,7 +48,6 @@ In query middleware functions, `this` refers to the query.
 * [find](api/query.html#query_Query-find)
 * [findOne](api/query.html#query_Query-findOne)
 * [findOneAndDelete](api/query.html#query_Query-findOneAndDelete)
-* [findOneAndRemove](api/query.html#query_Query-findOneAndRemove)
 * [findOneAndReplace](api/query.html#query_Query-findOneAndReplace)
 * [findOneAndUpdate](api/query.html#query_Query-findOneAndUpdate)
 * [remove](api/model.html#model_Model-remove)
@@ -81,7 +80,6 @@ Here are the possible strings that can be passed to `pre()`
 * find
 * findOne
 * findOneAndDelete
-* findOneAndRemove
 * findOneAndReplace
 * findOneAndUpdate
 * init

docs/migrating_to_8.md

@@ -0,0 +1,300 @@
+# Migrating from 7.x to 8.x
+
+<style>
+  ul > li {
+    padding: 4px 0px;
+  }
+</style>
+
+There are several backwards-breaking changes
+you should be aware of when migrating from Mongoose 7.x to Mongoose 8.x.
+
+If you're still on Mongoose 6.x or earlier, please read the [Mongoose 6.x to 7.x migration guide](migrating_to_7.html) and upgrade to Mongoose 7.x first before upgrading to Mongoose 8.
+
+* [Removed `rawResult` option for `findOneAndUpdate()`](#removed-rawresult-option-for-findoneandupdate)
+* [`Document.prototype.deleteOne()` now returns a query](#document-prototype-deleteone-now-returns-a-query)
+* [MongoDB Node Driver 6.0](#mongodb-node-driver-6)
+* [Removed `findOneAndRemove()`](#removed-findoneandremove)
+* [Removed `count()`](#removed-count)
+* [Removed id Setter](#removed-id-setter)
+* [`null` is valid for non-required string enums](#null-is-valid-for-non-required-string-enums)
+* [Apply minimize when `save()` updates an existing document](#apply-minimize-when-save-updates-an-existing-document)
+* [Apply base schema paths before discriminator paths](#apply-base-schema-paths-before-discriminator-paths)
+* [Removed `overwrite` option for `findOneAndUpdate()`](#removed-overwrite-option-for-findoneandupdate)
+* [Changed behavior for `findOneAndUpdate()` with `orFail()` and upsert](#changed-behavior-for-findoneandupdate-with-orfail-and-upsert)
+* [`create()` waits until all saves are done before throwing any error](#create-waits-until-all-saves-are-done-before-throwing-any-error)
+* [`Model.validate()` returns copy of object](#model-validate-returns-copy-of-object)
+* [Allow `null` For Optional Fields in TypeScript](#allow-null-for-optional-fields-in-typescript)
+* [Model constructor properties are all optional in TypeScript](#model-constructor-properties-are-all-optional-in-typescript)
+* [Infer `distinct()` return types from schema](#infer-distinct-return-types-from-schema)
+
+<h2 id="removed-rawresult-option-for-findoneandupdate"><a href="#removed-rawresult-option-for-findoneandupdate">Removed <code>rawResult</code> option for <code>findOneAndUpdate()</code></a></h2>
+
+The `rawResult` option for `findOneAndUpdate()`, `findOneAndReplace()`, and `findOneAndDelete()` has been replaced by the `includeResultMetadata` option.
+
+```javascript
+const filter = { name: 'Will Riker' };
+const update = { age: 29 };
+
+const res = await Character.findOneAndUpdate(filter, update, {
+  new: true,
+  upsert: true,
+  // Replace `rawResult: true` with `includeResultMetadata: true`
+  includeResultMetadata: true
+});
+```
+
+`includeResultMetadata` in Mongoose 8 behaves identically to `rawResult`.
+
+<h2 id="document-prototype-deleteone-now-returns-a-query"><a href="#document-prototype-deleteone-now-returns-a-query"><code>Document.prototype.deleteOne</code> now returns a query</a></h2>
+
+In Mongoose 7, `doc.deleteOne()` returned a promise that resolved to `doc`.
+In Mongoose 8, `doc.deleteOne()` returns a query for easier chaining, as well as consistency with `doc.updateOne()`.
+
+```javascript
+const numberOne = await Character.findOne({ name: 'Will Riker' });
+
+// In Mongoose 7, q is a Promise that resolves to `numberOne`
+// In Mongoose 8, q is a Query.
+const q = numberOne.deleteOne();
+
+// In Mongoose 7, `res === numberOne`
+// In Mongoose 8, `res` is a `DeleteResult`.
+const res = await q;
+```
+
+<h2 id="mongodb-node-driver-6"><a href="#mongodb-node-driver-6">MongoDB Node Driver 6</a></h2>
+
+Mongoose 8 uses [v6.x of the MongoDB Node driver](https://github.com/mongodb/node-mongodb-native/blob/main/HISTORY.md#600-2023-08-28).
+There's a few noteable changes in MongoDB Node driver v6 that affect Mongoose:
+
+1. The `ObjectId` constructor no longer accepts strings of length 12. In Mongoose 7, `new mongoose.Types.ObjectId('12charstring')` was perfectly valid. In Mongoose 8, `new mongoose.Types.ObjectId('12charstring')` throws an error.
+
+<h2 id="removed-findoneandremove"><a href="#removed-findoneandremove">Removed <code>findOneAndRemove()</code></a></h2>
+
+In Mongoose 7, `findOneAndRemove()` was an alias for `findOneAndDelete()` that Mongoose supported for backwards compatibility.
+Mongoose 8 no longer supports `findOneAndRemove()`.
+Use `findOneAndDelete()` instead.
+
+<h2 id="removed-count"><a href="#removed-count">Removed <code>count()</code></a></h2>
+
+`Model.count()` and `Query.prototype.count()` were removed in Mongoose 8. Use `Model.countDocuments()` and `Query.prototype.countDocuments()` instead.
+
+<h2 id="removed-id-setter"><a href="#removed-id-setter">Removed id Setter</a></h2>
+
+In Mongoose 7.4, Mongoose introduced an `id` setter that made `doc.id = '0'.repeat(24)` equivalent to `doc._id = '0'.repeat(24)`.
+In Mongoose 8, that setter is now removed.
+
+<h2 id="null-is-valid-for-non-required-string-enums"><a href="#null-is-valid-for-non-required-string-enums"><code>null</code> is valid for non-required string enums</a></h2>
+
+Before Mongoose 8, setting a string path with an `enum` to `null` would lead to a validation error, even if that path wasn't `required`.
+In Mongoose 8, it is valid to set a string path to `null` if `required` is not set, even with `enum`.
+
+```javascript
+const schema = new Schema({
+  status: {
+    type: String,
+    enum: ['on', 'off']
+  }
+});
+const Test = mongoose.model('Test', schema);
+
+// Works fine in Mongoose 8
+// Throws a `ValidationError` in Mongoose 7
+await Test.create({ status: null });
+```
+
+<h2 id="apply-minimize-when-save-updates-an-existing-document"><a href="#apply-minimize-when-save-updates-an-existing-document">Apply minimize when <code>save()</code> updates an existing document</a></h2>
+
+In Mongoose 7, Mongoose would only apply minimize when saving a new document, not when updating an existing document.
+
+```javascript
+const schema = new Schema({
+  nested: {
+    field1: Number
+  }
+});
+const Test = mongoose.model('Test', schema);
+
+// Both Mongoose 7 and Mongoose 8 strip out empty objects when saving
+// a new document in MongoDB by default
+const { _id } = await Test.create({ nested: {} });
+let rawDoc = await Test.findById(_id).lean();
+rawDoc.nested; // undefined
+
+// Mongoose 8 will also strip out empty objects when saving an
+// existing document in MongoDB
+const doc = await Test.findById(_id);
+doc.nested = {};
+doc.markModified('nested');
+await doc.save();
+
+let rawDoc = await Test.findById(_id).lean();
+rawDoc.nested; // undefined in Mongoose 8, {} in Mongoose 7
+```
+
+<h2 id="apply-base-schema-paths-before-discriminator-paths"><a href="#apply-base-schema-paths-before-discriminator-paths">Apply base schema paths before discriminator paths</a></h2>
+
+This means that, in Mongoose 8, getters and setters on discriminator paths run *after* getters and setters on base paths.
+In Mongoose 7, getters and setters on discriminator paths ran *before* getters and setters on base paths.
+
+```javascript
+
+const schema = new Schema({
+  name: {
+    type: String,
+    get(v) {
+      console.log('Base schema getter');
+      return v;
+    }
+  }
+});
+
+const Test = mongoose.model('Test', schema);
+const D = Test.discriminator('D', new Schema({
+  otherProp: {
+    type: String,
+    get(v) {
+      console.log('Discriminator schema getter');
+      return v;
+    }
+  }
+}));
+
+const doc = new D({ name: 'test', otherProp: 'test' });
+// In Mongoose 8, prints "Base schema getter" followed by "Discriminator schema getter"
+// In Mongoose 7, prints "Discriminator schema getter" followed by "Base schema getter"
+console.log(doc.toObject({ getters: true }));
+```
+
+<h2 id="removed-overwrite-option-for-findoneandupdate"><a href="#removed-overwrite-option-for-findoneandupdate">Removed <code>overwrite</code> option for <code>findOneAndUpdate()</code></a></h2>
+
+Mongoose 7 and earlier supported an `overwrite` option for `findOneAndUpdate()`, `updateOne()`, and `update()`.
+Before Mongoose 7, `overwrite` would skip wrapping the `update` parameter in `$set`, which meant that `findOneAndUpdate()` and `update()` would overwrite the matched document.
+In Mongoose 7, setting `overwrite` would convert `findOneAndUpdate()` to `findOneAndReplace()` and `updateOne()` to `replaceOne()` to retain backwards compatibility.
+
+In Mongoose 8, the `overwrite` option is no longer supported.
+If you want to overwrite the entire document, use `findOneAndReplace()` or `replaceOne()`.
+
+<h2 id="changed-behavior-for-findoneandupdate-with-orfail-and-upsert"><a href="#changed-behavior-for-findoneandupdate-with-orfail-and-upsert">Changed behavior for <code>findOneAndUpdate()</code> with <code>orFail()</code> and upsert</a></h2>
+
+In Mongoose 7, `findOneAndUpdate(filter, update, { upsert: true }).orFail()` would throw a `DocumentNotFoundError` if a new document was upserted.
+In other words, `findOneAndUpdate().orFail()` always threw an error if no document was found, even if a new document was upserted.
+
+In Mongoose 8, `findOneAndUpdate(filter, update, { upsert: true }).orFail()` always succeeds.
+`findOneAndUpdate().orFail()` now throws a `DocumentNotFoundError` if there's no document returned, rather than if no document was found.
+
+<h2 id="create-waits-until-all-saves-are-done-before-throwing-any-error"><a href="#create-waits-until-all-saves-are-done-before-throwing-any-error"><code>create()</code> waits until all saves are done before throwing any error</a></h2>
+
+In Mongoose 7, `create()` would immediately throw if any `save()` threw an error by default.
+Mongoose 8 instead waits for all `save()` calls to finish before throwing the first error that occurred.
+So `create()` will throw the same error in both Mongoose 7 and Mongoose 8, Mongoose 8 just may take longer to throw the error.
+
+```javascript
+const schema = new Schema({
+  name: {
+    type: String,
+    enum: ['Badger', 'Mushroom']
+  }
+});
+schema.pre('save', async function() {
+  await new Promise(resolve => setTimeout(resolve, 1000));
+});
+const Test = mongoose.model('Test', schema);
+
+const err = await Test.create([
+  { name: 'Badger' },
+  { name: 'Mushroom' },
+  { name: 'Cow' }
+]).then(() => null, err => err);
+err; // ValidationError
+
+// In Mongoose 7, there would be 0 documents, because `Test.create()`
+// would throw before 'Badger' and 'Mushroom' are inserted
+// In Mongoose 8, there will be 2 documents. `Test.create()` waits until
+// 'Badger' and 'Mushroom' are inserted before throwing.
+await Test.countDocuments();
+```
+
+<h2 id="model-validate-returns-copy-of-object"><a href="#model-validate-returns-copy-of-object"><code>Model.validate()</code> returns copy of object</a></h2>
+
+In Mongoose 7, `Model.validate()` would potentially modify the passed in object.
+Mongoose 8 instead copies the passed in object first.
+
+```javascript
+const schema = new Schema({ answer: Number });
+const Test = mongoose.model('Test', schema);
+
+const obj = { answer: '42' };
+const res = Test.validate(obj);
+
+typeof obj.answer; // 'string' in Mongoose 8, 'number' in Mongoose 7 
+typeof res.answer; // 'number' in both Mongoose 7 and Mongoose 8
+```
+
+<h2 id="allow-null-for-optional-fields-in-typescript"><a href="#allow-null-for-optional-fields-in-typescript">Allow <code>null</code> For Optional Fields in TypeScript</a></h2>
+
+In Mongoose 8, automatically inferred schema types in TypeScript allow `null` for optional fields.
+In Mongoose 7, optional fields only allowed `undefined`, not `null`.
+
+```typescript
+const schema = new Schema({ name: String });
+const TestModel = model('Test', schema);
+
+const doc = new TestModel();
+
+// In Mongoose 8, this type is `string | null | undefined`.
+// In Mongoose 7, this type is `string | undefined`
+doc.name;
+```
+
+<h2 id="model-constructor-properties-are-all-optional-in-typescript"><a href="#model-constructor-properties-are-all-optional-in-typescript">Model constructor properties are all optional in TypeScript</a></h2>
+
+In Mongoose 8, no properties are required on model constructors by default.
+
+```ts
+import {Schema, model, Model} from 'mongoose';
+
+interface IDocument {
+  name: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const documentSchema = new Schema<IDocument>(
+  { name: { type: String, required: true } },
+  { timestamps: true }
+);
+
+const TestModel = model<IDocument>('Document', documentSchema);
+
+// Would throw a compile error in Mongoose 7, compiles in Mongoose 8
+const newDoc = new TestModel({
+  name: 'Foo'
+});
+
+// Explicitly pass generic param to constructor to specify the expected
+// type of the model constructor param. The following will cause TS
+// to complain about missing `createdAt` and `updatedAt` in Mongoose 8.
+const newDoc2 = new TestModel<IDocument>({
+  name: 'Foo'
+});
+```
+
+<h2 id="infer-distinct-return-types-from-schema"><a href="#infer-distinct-return-types-from-schema">Infer <code>distinct()</code> return types from schema</a></h2>
+
+```ts
+interface User {
+  name: string;
+  email: string;
+  avatar?: string;
+}
+const schema = new Schema<User>({
+  name: { type: String, required: true },
+  email: { type: String, required: true },
+  avatar: String
+});
+
+// Works in Mongoose 8. Compile error in Mongoose 7.
+const names: string[] = await MyModel.distinct('name');
+```

docs/models.md

@@ -193,7 +193,7 @@ If you attempt to `save()` a document from a View, you will get an error from th
 
 ## Yet more
 
-The [API docs](api/model.html#model_Model) cover many additional methods available like [count](api/model.html#model_Model-count), [mapReduce](api/model.html#model_Model-mapReduce), [aggregate](api/model.html#model_Model-aggregate), and [more](api/model.html#model_Model-findOneAndRemove).
+The [API docs](api/model.html#model_Model) cover many additional methods available like [count](api/model.html#model_Model-count), [mapReduce](api/model.html#model_Model-mapReduce), [aggregate](api/model.html#model_Model-aggregate), and more.
 
 ## Next Up