docs: add documentation for Union Schema Type

[TechGenie-awake]

Closes #15719

• Added Union to SchemaTypes list
• Added Union example in main schema example
• Added comprehensive Union section covering:
  • Basic usage and syntax
  • Casting behavior details
  • Error handling
  • Options support for individual types
  • Query and update behavior

Summary

This PR adds documentation for the Union Schema Type feature that was introduced in Mongoose 8.18. The Union type was missing documentation as reported in issue #15719, making it difficult for users to discover and use this feature.

The Union SchemaType allows developers to define fields that can accept multiple types (e.g., a field that can be either a String or a Number), with automatic type casting. This is useful for flexible schemas where a field's type may vary based on the data source or use case.

Examples

The documentation includes comprehensive examples covering:

1. Basic Usage:

const schema = new Schema({
  value: {
    type: Schema.Types.Union,
    of: [String, Number]
  }
});

2. Casting Behavior:

const doc1 = new Model({ value: 42 }); // Number
const doc2 = new Model({ value: '42' }); // Casts to Number
const doc3 = new Model({ value: 'hello' }); // String

3. With Type Options:

const schema = new Schema({
  value: {
    type: Schema.Types.Union,
    of: [
      Number,
      { type: String, trim: true }
    ]
  }
});

4. Query and Update Support:

await Model.findOne({ value: '42' }); // Casts query filter
await Model.findOneAndUpdate({ value: 42 }, { value: 'hello' });

All examples are based on the test cases in test/schema.union.test.js and the implementation in lib/schema/union.js.

[timheerwagen]

It's hard to review because of all the formatting changes made by the editor, but LGTM!

In my opinion, the Array of Unions should be added directly here after the merge of #15720.

[TechGenie-awake]

Thank you! Yes, I can add documentation for Array of Unions in a follow-up PR after this is merged. Should I open a new issue for it or just create the PR directly?

[vkarpov15]

The Union type docs are good, but can you please undo all the unnecessary formatting changes? I can do that as well, but I would need to create a new PR for that.

[Copilot]

Pull Request Overview

This PR adds documentation for the new Union SchemaType in Mongoose, which allows a schema path to accept multiple types with automatic casting.

• Adds Union to the list of available SchemaTypes
• Documents usage examples showing how to define union types with the of array
• Explains casting behavior, error handling, options support, and query/update behavior

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vkarpov15]

This one is incorrect because of the "exact match" rule - since String is one of the valid types, Mongoose will leave '42' as a string.