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)`.

[hasezoey]

Mostly looks good to me, though the types (as others that already exist) seem to be quite complex and hard to parse, so some in-line documentation would be great.

I have noticed this PR is targeting branch 9.0, but the base commit is 8.16.0, maybe it should be rebased onto 9.0 to confirm it is actually working in there?

---

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

When running this PR (in its current state targeting 8.16.0) without typegoose modification, the builds and type-tests are fine.
This is likely because typegoose (the actual assembly of the schema) works generically over a schema, with mostly everything either default or filled to any.
As for the other parts where typegoose assembled the type, this PR does not really affect that to my knowledge.

Because of this, i think typegoose does not really have a use-case for Schema.create due to the above regarding working over a schema generically.

Though when i replace the usage of new Schema(def, options) with Schema.create(def, options) without further modification, i get a error that the options are incompatible.

Full type error for this options incompatibility

Argument of type 'SchemaOptions<unknown, {}, {}, {}, {}, Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }>' is not assignable to parameter of type 'SchemaOptions<{ [x: string]: any; } & Required<{ _id: unknown; }>, {}, {}, {}, {}, Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<...> & { ...; }>'.
  Types of property 'toJSON' are incompatible.
    Type 'ToObjectOptions<Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }> | undefined' is not assignable to type 'ToObjectOptions<Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<{ _id: unknown; }> & { __v: number; }> | undefined'.
      Type 'ToObjectOptions<Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }>' is not assignable to type 'ToObjectOptions<Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<{ _id: unknown; }> & { __v: number; }>'.
        Types of property 'transform' are incompatible.
          Type 'boolean | ((doc: Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }, ret: Record<string, any>, options: ToObjectOptions<Document<unknown, {}, unknown, {}> & { ...; } & { ...; }>) => any) | undefined' is not assignable to type 'boolean | ((doc: Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<{ _id: unknown; }> & { __v: number; }, ret: Record<string, any>, options: ToObjectOptions<...>) => any) | undefined'.
            Type '(doc: Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }, ret: Record<string, any>, options: ToObjectOptions<Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { ...; }>) => any' is not assignable to type 'boolean | ((doc: Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<{ _id: unknown; }> & { __v: number; }, ret: Record<string, any>, options: ToObjectOptions<...>) => any) | undefined'.
              Type '(doc: Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }, ret: Record<string, any>, options: ToObjectOptions<Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { ...; }>) => any' is not assignable to type '(doc: Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<{ _id: unknown; }> & { __v: number; }, ret: Record<string, any>, options: ToObjectOptions<...>) => any'.
                Types of parameters 'doc' and 'doc' are incompatible.
                  Type 'Document<unknown, {}, { [x: string]: any; } & Required<{ _id: unknown; }>, {}> & { [x: string]: any; } & Required<{ _id: unknown; }> & { __v: number; }' is not assignable to type 'Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }'.ts(2345)

[vkarpov15]

@hasezoey can you please let me know what changes you made in Typegoose to cause that error? I'd like to troubleshoot.

If Typegoose sets most schema generics, then Typegoose doesn't have much use for Schema.create(). I'm thinking Schema.create() should be used for automatic schema inference in cases where new Schema() isn't producing the right result.

[hasezoey]

Now looks good to me.

---

can you please let me know what changes you made in Typegoose to cause that error? I'd like to troubleshoot.

The error is slightly different (i dont know what caused that exact error anymore, may have been fixed by another PR), but here is basically what i described:

new Schema(def, options) -> Schema.create(def, options)

diff --git a/src/internal/schema.ts b/src/internal/schema.ts
index daa2e8ac..2eefab13 100644
--- a/src/internal/schema.ts
+++ b/src/internal/schema.ts
@@ -67,7 +67,7 @@ export function _buildSchema<U extends AnyParamConstructor<any>>(
     const schemaReflectTarget = getCachedSchema(cl);
 
     if (!(origSch instanceof Schema)) {
-      sch = new Schema(schemaReflectTarget, schemaOptions);
+      sch = Schema.create(schemaReflectTarget, schemaOptions);
     } else {
       sch = origSch.clone();
       sch.add(schemaReflectTarget);

On-top of typegoose branch feature/13.0, or 9cedc31ae5394e815dcf50782f731f1ec02c46d5.

Alternatively, the exact error can be gotten in the following minimal example:

function test() {
  const schemaoptions = {} as mongoose.SchemaOptions;
  const definition = {} as Record<string, any>; // or "{ [key: string]: any; }" directly

  const schema = mongoose.Schema.create(definition, schemaoptions);
}

Error:

Argument of type 'SchemaOptions<unknown, {}, {}, {}, {}, Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }>' is not assignable to parameter of type 'SchemaOptions<{ [x: string]: unknown; } & Required<{ _id: unknown; }>, {}, {}, {}, {}, Document<unknown, {}, { [x: string]: unknown; } & Required<{ _id: unknown; }>, {}> & { [x: string]: unknown; } & Required<{ _id: unknown; }> & { ...; }>'.
  Types of property 'toJSON' are incompatible.
    Type 'ToObjectOptions<unknown, Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }> | undefined' is not assignable to type 'ToObjectOptions<{ [x: string]: unknown; } & Required<{ _id: unknown; }>, Document<unknown, {}, { [x: string]: unknown; } & Required<{ _id: unknown; }>, {}> & { [x: string]: unknown; } & Required<{ _id: unknown; }> & { ...; }> | undefined'.
      Type 'ToObjectOptions<unknown, Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }>' is not assignable to type 'ToObjectOptions<{ [x: string]: unknown; } & Required<{ _id: unknown; }>, Document<unknown, {}, { [x: string]: unknown; } & Required<{ _id: unknown; }>, {}> & { [x: string]: unknown; } & Required<{ _id: unknown; }> & { ...; }>'.
        Type 'Document<unknown, {}, { [x: string]: unknown; } & Required<{ _id: unknown; }>, {}> & { [x: string]: unknown; } & Required<{ _id: unknown; }> & { __v: number; }' is not assignable to type 'Document<unknown, {}, unknown, {}> & { _id: ObjectId; } & { __v: number; }'.
          Type 'Document<unknown, {}, { [x: string]: unknown; } & Required<{ _id: unknown; }>, {}> & { [x: string]: unknown; } & Required<{ _id: unknown; }> & { __v: number; }' is not assignable to type '{ _id: ObjectId; }'.
            Types of property '_id' are incompatible.
              Type 'unknown' is not assignable to type 'ObjectId'.ts(2345)

But like i said earlier, typegoose does not really have a use-case for Schema.create's type inference and i dont know if this is worth investigating too much.

[vkarpov15]

@hasezoey you're right, that pattern is explicitly what Schema.create() does not want to support. The idea of Schema.create() is to infer from definition and schemaOptions, but if definition is explicitly typed as Record<string, any> then Schema.create() can't infer anything about the schema.

To get the code you wrote to compile, you would have to do const schemaoptions = {} as SchemaOptions<any>. But then you'd end up with a schema whose RawDocType is { [x: string]: unknown; } & Required<{ _id: unknown; }, which isn't very useful.