Schema.create() for TypeScript type inference

[vkarpov15]

Summary

The key idea behind fixing #14954 and related issues is to infer the raw document type and hydrated document type directly from the schema definition, rather than attempting to infer the hydrated document type from the raw document type. The new Schema.create() function does just that.

We did some work attempting to pull this logic into new Schema() directly in 9.0...vkarpov15/gh-14954-scratch-2, but unfortunately that would require shifting around the generic params to new Schema() significantly - we would have to make TSchemaDefinition the first generic param, which would break anyone who is using new Schema<RawDoc>().

@hasezoey can you try out Schema.create() in Typegoose and see what happens?

Examples

[Copilot]

Pull Request Overview

This PR introduces a static Schema.create() method for clearer TypeScript type inference by directly inferring the raw and hydrated document types from the schema definition.

• Updated test cases to reflect the inclusion of _id: Types.ObjectId in the inferred document types.
• Added the Schema.create() method in lib/schema.js with supporting documentation.

Reviewed Changes

Copilot reviewed 3 out of 9 changed files in this pull request and generated no comments.

File	Description
test/types/schema.test.ts	Updated expected type to include _id property in the RawDocType inference.
test/types/inferrawdoctype.test.ts	Updated expected type to include _id property in the inferred raw document type.
lib/schema.js	Introduced Schema.create() with detailed JSDoc for improved TypeScript inference.

Comments suppressed due to low confidence (1)

lib/schema.js:376

• Consider updating the documentation to explicitly mention that Schema.create() infers _id: Types.ObjectId by default, which affects the resulting document types.

 * Creates a new schema with the given definition and options. Equivalent to `new Schema(definition, options)`.