Merge branch 'master' into 8.1

Author: vkarpov15

.github/workflows/benchmark.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 16
 

.github/workflows/codeql.yml

@@ -25,7 +25,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
            config-file: ./.github/codeql/codeql-config.yml
         # Override language selection by uncommenting this and choosing your languages
@@ -44,4 +44,4 @@ jobs:
       #     make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3

.github/workflows/documentation.yml

@@ -31,7 +31,7 @@ jobs:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 16
 
@@ -52,7 +52,7 @@ jobs:
       - run: git fetch --depth=1 --tags # download all tags for documentation
 
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 16
 

.github/workflows/stale.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: stale
-        uses: actions/stale@v8
+        uses: actions/stale@v9
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           stale-issue-message: 'This issue is stale because it has been open 14 days with no activity. Remove stale label or comment or this will be closed in 5 days'

.github/workflows/test.yml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 18
 
@@ -61,7 +61,7 @@ jobs:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: ${{ matrix.node }}
 
@@ -80,7 +80,7 @@ jobs:
         run: npm run test-coverage
         if: matrix.coverage == true
       - name: Archive code coverage results
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: matrix.coverage == true
         with:
           name: coverage
@@ -96,7 +96,7 @@ jobs:
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 16
       - name: Load MongoDB binary cache
@@ -124,7 +124,7 @@ jobs:
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 16
       - run: npm install

.github/workflows/tidelift-alignment.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 16
       - name: Alignment

.github/workflows/tsd.yml

@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 18
 
@@ -41,7 +41,7 @@ jobs:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
       - name: Setup node
-        uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
         with:
           node-version: 14
 

CHANGELOG.md

@@ -1,3 +1,39 @@
+8.0.4 / 2024-01-08
+==================
+ * fix(update): set CastError path to full path if casting update fails #14161 #14114
+ * fix: cast error when there is an elemMatch in the and clause #14171 [tosaka-n](https://github.com/tosaka-n)
+ * fix: allow defining index on base model that applies to all discriminators #14176 [peplin](https://github.com/peplin)
+ * fix(model): deep clone bulkWrite() updateOne arguments to avoid mutating documents in update #14197 #14164
+ * fix(populate): handle deselecting _id with array of fields in populate() #14242 #14231
+ * types(model+query): use stricter typings for updateX(), replaceOne(),deleteX() Model functions #14228 #14204
+ * types: fix return types for findByIdAndDelete overrides #14196 #14190
+ * types(schema): add missing omit() method #14235 [amitbeck](https://github.com/amitbeck)
+ * types(model): add missing strict property to bulkWrite() top level options #14239
+ * docs(compatibility): add note that Mongoose 5.13 is fully compatible with MongoDB server 5 #14230 #14149
+ * docs: add shared schemas guide #14211
+ * docs: update TLS/SSL guide for Mongoose v8 - MongoDB v6 driver deprecations #14170 [andylwelch](https://github.com/andylwelch)
+ * docs: update findOneAndUpdate tutorial to use includeResultMetadata #14208 #14207
+ * docs: clarify disabling _id on subdocs #14195 #14194
+
+7.6.8 / 2024-01-08
+==================
+ * perf(schema): remove unnecessary lookahead in numeric subpath check
+ * fix(discriminator): handle reusing schema with embedded discriminators defined using Schema.prototype.discriminator #14202 #14162
+ * fix(ChangeStream): avoid suppressing errors in closed change stream #14206 #14177
+
+6.12.5 / 2024-01-03
+===================
+ * perf(schema): remove unnecessary lookahead in numeric subpath check
+ * fix(document): allow setting nested path to null #14226
+ * fix(document): avoid flattening dotted paths in mixed path underneath nested path #14198 #14178
+ * fix: add ignoreAtomics option to isModified() for better backwards compatibility with Mongoose 5 #14213
+
+6.12.4 / 2023-12-27
+===================
+ * fix: upgrade mongodb driver -> 4.17.2
+ * fix(document): avoid treating nested projection as inclusive when applying defaults #14173 #14115
+ * fix: account for null values when assigning isNew property #14172 #13883
+
 8.0.3 / 2023-12-07
 ==================
  * fix(schema): avoid creating unnecessary clone of schematype in nested array so nested document arrays use correct constructor #14128 #14101

docs/compatibility.md

@@ -20,7 +20,7 @@ Below are the [semver](http://semver.org/) ranges representing which versions of
 | :------------: | :-------------------------------------: |
 |     `7.x`      |            `^7.4.0 \| ^8.0.0`           |
 |     `6.x`      |      `^6.5.0 \| ^7.0.0 \| ^8.0.0`       |
-|     `5.x`      |      `^6.0.0 \| ^7.0.0 \| ^8.0.0`       |
+|     `5.x`      | `^5.13.0` | `^6.0.0 \| ^7.0.0 \| ^8.0.0`|
 |    `4.4.x`     | `^5.10.0 \| ^6.0.0 \| ^7.0.0 \| ^8.0.0` |
 |    `4.2.x`     | `^5.7.0 \| ^6.0.0 \| ^7.0.0 \| ^8.0.0`  |
 |    `4.0.x`     | `^5.2.0 \| ^6.0.0 \| ^7.0.0 \| ^8.0.0`  |

docs/guide.md

@@ -109,9 +109,7 @@ const schema = new Schema();
 schema.path('_id'); // ObjectId { ... }
 ```
 
-When you create a new document with the automatically added
-`_id` property, Mongoose creates a new [`_id` of type ObjectId](https://masteringjs.io/tutorials/mongoose/objectid)
-to your document.
+When you create a new document with the automatically added `_id` property, Mongoose creates a new [`_id` of type ObjectId](https://masteringjs.io/tutorials/mongoose/objectid) to your document.
 
 ```javascript
 const Model = mongoose.model('Test', schema);
@@ -120,13 +118,13 @@ const doc = new Model();
 doc._id instanceof mongoose.Types.ObjectId; // true
 ```
 
-You can also overwrite Mongoose's default `_id` with your
-own `_id`. Just be careful: Mongoose will refuse to save a
-document that doesn't have an `_id`, so you're responsible
-for setting `_id` if you define your own `_id` path.
+You can also overwrite Mongoose's default `_id` with your own `_id`.
+Just be careful: Mongoose will refuse to save a top-level document that doesn't have an `_id`, so you're responsible for setting `_id` if you define your own `_id` path.
 
 ```javascript
-const schema = new Schema({ _id: Number });
+const schema = new Schema({
+  _id: Number // <-- overwrite Mongoose's default `_id`
+});
 const Model = mongoose.model('Test', schema);
 
 const doc = new Model();
@@ -136,6 +134,37 @@ doc._id = 1;
 await doc.save(); // works
 ```
 
+Mongoose also adds an `_id` property to subdocuments.
+You can disable the `_id` property on your subdocuments as follows.
+Mongoose does allow saving subdocuments without an `_id` property.
+
+```javascript
+const nestedSchema = new Schema(
+  { name: String },
+  { _id: false } // <-- disable `_id`
+);
+const schema = new Schema({
+  subdoc: nestedSchema,
+  docArray: [nestedSchema]
+});
+const Test = mongoose.model('Test', schema);
+
+// Neither `subdoc` nor `docArray.0` will have an `_id`
+await Test.create({
+  subdoc: { name: 'test 1' },
+  docArray: [{ name: 'test 2' }]
+});
+```
+
+Alternatively, you can disable `_id` using the following syntax:
+
+```javascript
+const nestedSchema = new Schema({
+  _id: false, // <-- disable _id
+  name: String
+});
+```
+
 <h2 id="methods"><a href="#methods">Instance methods</a></h2>
 
 Instances of `Models` are [documents](documents.html). Documents have

docs/guides.md

@@ -29,6 +29,7 @@ integrating Mongoose with external tools and frameworks.
 * [Custom Casting For Built-in Types](tutorials/custom-casting.html)
 * [Custom SchemaTypes](customschematypes.html)
 * [Advanced Schemas](advanced_schemas.html)
+* [Sharing Schemas Between Mongoose Projects](shared-schemas.html)
 
 ## Integrations
 
@@ -41,7 +42,7 @@ integrating Mongoose with external tools and frameworks.
 * [Transactions](transactions.html)
 * [MongoDB Driver Deprecation Warnings](deprecations.html)
 * [Testing with Jest](jest.html)
-* [SSL Connections](tutorials/ssl.html)
+* [TLS/SSL Connections](tutorials/ssl.html)
 * [MongoDB Client Side Field Level Encryption](field-level-encryption.html)
 
 ## Other Guides

docs/layout.pug

@@ -62,7 +62,7 @@ html(lang='en')
                     - if ([`${versions.versionedPath}/docs/connections`, `${versions.versionedPath}/docs/tutorials/ssl`].some(path => outputUrl.startsWith(path)))
                       ul.pure-menu-list
                         li.pure-menu-item.sub-item
-                          a.pure-menu-link(href=`${versions.versionedPath}/docs/tutorials/ssl.html`, class=outputUrl === `${versions.versionedPath}/docs/tutorials/ssl.html` ? 'selected' : '') SSL Connections
+                          a.pure-menu-link(href=`${versions.versionedPath}/docs/tutorials/ssl.html`, class=outputUrl === `${versions.versionedPath}/docs/tutorials/ssl.html` ? 'selected' : '') TLS/SSL Connections
                   li.pure-menu-item.sub-item
                     a.pure-menu-link(href=`${versions.versionedPath}/docs/models.html`, class=outputUrl === `${versions.versionedPath}/docs/models.html` ? 'selected' : '') Models
                     - if ([`${versions.versionedPath}/docs/models`, `${versions.versionedPath}/docs/change-streams`].some(path => outputUrl.startsWith(path)))

docs/migrating_to_8.md

@@ -71,6 +71,16 @@ 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.
 
+1. Deprecated SSL options have been removed
+
+   * `sslCA` -> `tlsCAFile`
+   * `sslCRL` -> `tlsCRLFile`
+   * `sslCert` -> `tlsCertificateKeyFile`
+   * `sslKey` -> `tlsCertificateKeyFile`
+   * `sslPass` -> `tlsCertificateKeyFilePassword`
+   * `sslValidate` -> `tlsAllowInvalidCertificates`
+   * `tlsCertificateFile` -> `tlsCertificateKeyFile`
+
 <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.

docs/shared-schemas.md

@@ -0,0 +1,73 @@
+# Sharing Schemas Between Mongoose Projects
+
+In larger organizations, it is common to have a project that contains schemas which are shared between multiple projects.
+For example, suppose your company has an `@initech/shared-schemas` private npm package, and `npm list` looks like the following:
+
+```sh
+@initech/web-app1@1.0.0
+├── @initech/shared-schemas@1.0.0
+├── mongoose@8.0.1
+```
+
+In the above output, `@initech/web-app1` is a *client project* and `@initech/shared-schemas` is the *shared library*.
+
+## Put Mongoose as a Peer Dependency
+
+First, and most importantly, we recommend that `@initech/shared-schemas` list Mongoose in [your shared-schema's `peerDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies), **not** as a top-level dependency.
+For example, `@initech/shared-schemas`'s `package.json` should look like the following.
+
+```javascript
+{
+  "name": "@initech/shared-schemas",
+  "peerDependencies": {
+    "mongoose": "8.x"
+  }
+}
+```
+
+We recommend this approach for the following reasons:
+
+1. Easier to upgrade. For example, suppose `@initech/shared-schemas` has a dependency on Mongoose 8, and `@initech/web-app1` works fine with Mongoose 8; but `@initech/web-app2` cannot upgrade from Mongoose 7. Peer dependencies makes it easier for the projects that rely on your shared schemas to determine which version of Mongoose they want, without risking having conflicting versions of the Mongoose module.
+2. Reduce risk of Mongoose module duplicates. Using Mongoose schemas and models from one version of Mongoose with another version is not supported.
+
+## Export Schemas, Not Models
+
+We recommend that `@initech/shared-schemas` export Mongoose schemas, **not** models.
+This approach is more flexible and allows client projects to instantiate models using their preferred patterns.
+In particular, if `@initech/shared-schemas` exports a model that is registered using `mongoose.model()`, there is no way to transfer that model to a different connection.
+
+```javascript
+// `userSchema.js` in `@initech/shared-schemas`
+const userSchema = new mongoose.Schema({ name: String });
+
+// Do this:
+module.exports = userSchema;
+
+// Not this:
+module.exports = mongoose.model('User', userSchema);
+```
+
+## Workaround: Export a POJO
+
+Sometimes, existing shared libraries don't follow the above best practices.
+If you find yourself with a shared library that depends on an old version of Mongoose, a helpful workaround is to export a [POJO](https://masteringjs.io/tutorials/fundamentals/pojo) rather than a schema or model.
+This will remove any conflicts between the shared library's version of Mongoose and the client project's version of Mongoose.
+
+```javascript
+// Replace this:
+module.exports = new mongoose.Schema({ name: String });
+
+// With this:
+module.exports = { name: String };
+```
+
+And update your client project to do the following:
+
+```javascript
+// Replace this:
+const { userSchema } = require('@initech/shared-schemas');
+
+// With this:
+const { userSchemaDefinition } = require('@initech/shared-schemas');
+const userSchema = new mongoose.Schema(userSchemaDefinition);
+```

docs/source/index.js

@@ -81,6 +81,7 @@ docs['docs/compatibility.md'] = {
   guide: true,
   markdown: true
 };
+docs['docs/shared-schemas.md'] = { guide: true, title: 'Sharing Schemas Between Mongoose Projects', markdown: true };
 docs['docs/field-level-encryption.md'] = { guide: true, title: 'Field Level Encryption', markdown: true };
 docs['docs/timestamps.md'] = { title: 'Mongoose Timestamps', markdown: true };
 docs['docs/search.pug'] = { title: 'Search' };

docs/tutorials/findoneandupdate.md

@@ -6,7 +6,7 @@ However, there are some cases where you need to use [`findOneAndUpdate()`](https
 * [Getting Started](#getting-started)
 * [Atomic Updates](#atomic-updates)
 * [Upsert](#upsert)
-* [The `rawResult` Option](#raw-result)
+* [The `includeResultMetadata` Option](#includeresultmetadata)
 
 ## Getting Started
 
@@ -51,17 +51,17 @@ Using the `upsert` option, you can use `findOneAndUpdate()` as a find-and-[upser
 [require:Tutorial.*findOneAndUpdate.*upsert]
 ```
 
-<h2 id="raw-result">The `rawResult` Option</h2>
+<h2 id="includeresultmetadata">The <code>includeResultMetadata</code> Option<h2 id="rawresult"></h2></h2>
 
 Mongoose transforms the result of `findOneAndUpdate()` by default: it
 returns the updated document. That makes it difficult to check whether
 a document was upserted or not. In order to get the updated document
 and check whether MongoDB upserted a new document in the same operation,
-you can set the `rawResult` flag to make Mongoose return the raw result
+you can set the `includeResultMetadata` flag to make Mongoose return the raw result
 from MongoDB.
 
 ```acquit
-[require:Tutorial.*findOneAndUpdate.*rawResult$]
+[require:Tutorial.*findOneAndUpdate.*includeResultMetadata$]
 ```
 
 Here's what the `res` object from the above example looks like: