Merge branch 'Automattic:master' into docs-union-schema-type

Author: TechGenie-awake

docs/connections.md

@@ -208,15 +208,13 @@ for (let i = 0; i < 3; ++i) {
 }
 ```
 
-## Callback {#callback}
+## Using Promises and Async/Await {#promises-async-await}
 
-The `connect()` function also accepts a callback parameter and returns a
-[promise](promises.html).
+The `connect()` function returns a [promise](promises.html).
 
 ```javascript
-mongoose.connect(uri, options, function(error) {
-  // Check error in initial connection. There is no 2nd param to the callback.
-});
+// Using async/await. The `mongoose.connect()` promise resolves to mongoose instance.
+await mongoose.connect(uri, options);
 
 // Or using promises
 mongoose.connect(uri, options).then(

docs/faq.md

@@ -254,13 +254,13 @@ For more debugging options (streams, callbacks), see the ['debug' option under `
 
 <hr id="callback_never_executes" />
 
-<a class="anchor" href="#callback_never_executes">**Q**</a>. My `save()` callback never executes. What am I doing wrong?
+<a class="anchor" href="#callback_never_executes">**Q**</a>. My `save()` operation never completes. What am I doing wrong?
 
 **A**. All `collection` actions (insert, remove, queries, etc.) are queued
 until Mongoose successfully connects to MongoDB. It is likely you haven't called Mongoose's
 `connect()` or `createConnection()` function yet.
 
-In Mongoose 5.11, there is a `bufferTimeoutMS` option (set to 10000 by default) that configures how long
+Mongoose connections support a `bufferTimeoutMS` option (set to 10000 by default) that configures how long
 Mongoose will allow an operation to stay buffered before throwing an error.
 
 If you want to opt out of Mongoose's buffering mechanism across your entire
@@ -408,28 +408,28 @@ mind that populate() will execute a separate query for each document.
 
 <a class="anchor" href="#duplicate-query">**Q**</a>. My query/update seems to execute twice. Why is this happening?
 
-**A**. The most common cause of duplicate queries is **mixing callbacks and promises with queries**.
-That's because passing a callback to a query function, like `find()` or `updateOne()`,
-immediately executes the query, and calling [`then()`](https://masteringjs.io/tutorials/fundamentals/then)
-executes the query again.
-
-Mixing promises and callbacks can lead to duplicate entries in arrays.
-For example, the below code inserts 2 entries into the `tags` array, **not* just 1.
+**A**. The most common cause of duplicate queries is **executing the same query object twice**.
+Calling [`then()`](https://masteringjs.io/tutorials/fundamentals/then) or `await` on the same query object
+multiple times will execute the query multiple times.
 
 ```javascript
 const BlogPost = mongoose.model('BlogPost', new Schema({
   title: String,
   tags: [String]
 }));
 
-// Because there's both `await` **and** a callback, this `updateOne()` executes twice
-// and thus pushes the same string into `tags` twice.
-const update = { $push: { tags: ['javascript'] } };
-await BlogPost.updateOne({ title: 'Introduction to Promises' }, update, (err, res) => {
-  console.log(res);
-});
+// This will throw 'Query was already executed' error
+const query = BlogPost.findOne({ title: 'Introduction to Promises' });
+await query;
+await query; // Error! Query already executed
+
+// To execute the same query twice, use clone()
+await query.clone(); // Works
 ```
 
+Note: Mongoose v7+ no longer supports callbacks. If you're seeing duplicate queries in older code,
+it may be due to mixing callbacks and promises, which is no longer possible in current versions.
+
 <hr id="add_something" />
 
 **Something to add?**

docs/guide.md

@@ -1059,10 +1059,12 @@ schema.path('name').validate(function(value) {
 });
 const M = mongoose.model('Person', schema);
 const m = new M({ name: null });
-m.validate(function(err) {
+try {
+  await m.validate();
+} catch (err) {
   console.log(err); // Will tell you that null is not allowed.
-});
-m.save(); // Succeeds despite being invalid
+}
+await m.save(); // Succeeds despite being invalid
 ```
 
 ## option: versionKey {#versionKey}

docs/index.md

@@ -88,7 +88,7 @@ fluffy.speak(); // "Meow name is fluffy"
 ```
 
 We have talking kittens! But we still haven't saved anything to MongoDB.
-Each document can be saved to the database by calling its [save](api/model.html#model_Model-save) method. The first argument to the callback will be an error if any occurred.
+Each document can be saved to the database by calling its [save](api/model.html#model_Model-save) method.
 
 ```javascript
 await fluffy.save();
@@ -111,7 +111,7 @@ await Kitten.find({ name: /^fluff/ });
 ```
 
 This performs a search for all documents with a name property that begins
-with "fluff" and returns the result as an array of kittens to the callback.
+with "fluff" and returns the result as an array of kittens.
 
 ## Congratulations
 

docs/middleware.md

@@ -217,9 +217,11 @@ schema.pre('save', async function() {
 // later...
 
 // Changes will not be persisted to MongoDB because a pre hook errored out
-myDoc.save(function(err) {
+try {
+  await myDoc.save();
+} catch (err) {
   console.log(err.message); // something went wrong
-});
+}
 ```
 
 Calling `next()` multiple times is a no-op. If you call `next()` with an

docs/queries.md

@@ -20,11 +20,7 @@ Each of these functions returns a
 * [`Model.updateMany()`](api.html#model_Model-updateMany)
 * [`Model.updateOne()`](api.html#model_Model-updateOne)
 
-A mongoose query can be executed in one of two ways. First, if you
-pass in a `callback` function, Mongoose will execute the query asynchronously
-and pass the results to the `callback`.
-
-A query also has a `.then()` function, and thus can be used as a promise.
+Mongoose queries can be executed by using `await`, or by using `.then()` to handle the promise returned by the query.
 
 <ul class="toc">
   <li><a href="#executing">Executing</a></li>

lib/schema.js

@@ -1694,6 +1694,10 @@ Schema.prototype.interpretAsType = function(path, obj, options) {
           `\`${name}\` is not a valid type within the array \`${path}\`.` +
           'See https://bit.ly/mongoose-schematypes for a list of valid schema types.');
       }
+
+      if (name === 'Union' && typeof cast === 'object') {
+        cast.parentSchema = this;
+      }
     }
 
     return new MongooseTypes.Array(path, cast || MongooseTypes.Mixed, obj, options);

test/schema.union.test.js

@@ -134,4 +134,28 @@ describe('Union', function() {
     const doc2FromDb = await TestModel.collection.findOne({ _id: doc2._id });
     assert.strictEqual(doc2FromDb.test, 'bbb');
   });
+
+  it('handles arrays of unions (gh-15718)', async function() {
+    const schema = new Schema({
+      arr: [{
+        type: 'Union',
+        of: [Number, Date]
+      }]
+    });
+    const TestModel = db.model('Test', schema);
+
+    const numValue = 42;
+    const dateValue = new Date('2025-06-01');
+
+    const doc = new TestModel({
+      arr: [numValue, dateValue]
+    });
+
+    await doc.save();
+
+    const found = await TestModel.collection.findOne({ _id: doc._id });
+    assert.strictEqual(found.arr.length, 2);
+    assert.strictEqual(found.arr[0], numValue);
+    assert.strictEqual(new Date(found.arr[1]).valueOf(), dateValue.valueOf());
+  });
 });

types/models.d.ts

@@ -20,7 +20,7 @@ declare module 'mongoose' {
       name: string | number,
       schema: Schema<T, U>,
       value?: string | number | ObjectId | DiscriminatorOptions
-    ): U;
+    ): Model<U>;
   }
 
   export type MongooseBulkWriteResult = mongodb.BulkWriteResult & {