TypeScript `this` Context Error When Calling Static Method on Schema Using `timestamps` and `SchemaOptions.virtuals`

[xGeekoo]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Mongoose version

9.2.2

Node.js version

24.13.1

MongoDB server version

8.2

Typescript version (if applicable)

5.9.3

Description

A TypeScript error occurs when calling a static method on a Mongoose model whose schema includes:

• timestamps: true
• a virtual populate defined via SchemaOptions.virtuals
• statics defined inside SchemaOptions.statics

The following TypeScript error occurs when calling a static method.
The error originates from an incompatibility in the inferred this context of the static method.

The 'this' context of type
'Model<
  { placeholder?: unknown } & DefaultTimestampProps,
  {},
  {},
  { votes: unknown } & { id: string },
  Document<
    unknown,
    {},
    { placeholder?: unknown } & DefaultTimestampProps,
    { votes: unknown } & { id: string }
  >
>'
is not assignable to method's 'this' of type
'Model<
  { placeholder?: string | null | undefined },
  {},
  {},
  { votes: unknown },
  Document<
    unknown,
    {},
    { placeholder?: string | null | undefined },
    { votes: unknown } & { id: string },
    DefaultSchemaOptions
  >
>'.

The types of 'castObject(...).placeholder' are incompatible between these types.

Type 'unknown' is not assignable to type 'string | null | undefined'.

Steps to Reproduce

import mongoose from 'mongoose';

const issueOneSchema = new mongoose.Schema(
  { placeholder: String },
  {
    timestamps: true,
    virtuals: {
      votes: {
        options: {
          ref: 'IssueTwo',
          localField: '_id',
          foreignField: 'issueOneId'
        }
      }
    },
    statics: {
      myStaticMethod: function () {
        console.log('placeholder');
      }
    }
  }
);

const IssueOne = mongoose.model('IssueOne', issueOneSchema);

IssueOne.myStaticMethod();

[vkarpov15]

As a workaround, use Schema.create() instead of new Schema() - Schema.create() is equivalent at runtime but has more robust TypeScript inference. The following compiles fine. We're investigating to see what we can do to fix new Schema() inference.

import mongoose from 'mongoose';

const issueOneSchema = mongoose.Schema.create(
  { placeholder: String },
  {
    timestamps: true,
    virtuals: {
      votes: {
        options: {
          ref: 'IssueTwo',
          localField: '_id',
          foreignField: 'issueOneId'
        }
      }
    },
    statics: {
      myStaticMethod: function () {
        console.log('placeholder');
      }
    }
  }
);

const IssueOne = mongoose.model('IssueOne', issueOneSchema);

IssueOne.myStaticMethod();

```import mongoose from 'mongoose';

const issueOneSchema = mongoose.Schema.create(
  { placeholder: String },
  {
    timestamps: true,
    virtuals: {
      votes: {
        options: {
          ref: 'IssueTwo',
          localField: '_id',
          foreignField: 'issueOneId'
        }
      }
    },
    statics: {
      myStaticMethod: function () {
        console.log('placeholder');
      }
    }
  }
);

const IssueOne = mongoose.model('IssueOne', issueOneSchema);

IssueOne.myStaticMethod();

This is a data point for #16050.

[vkarpov15]

I fixed the issue for new Schema() path by making it so that SchemaOptionsVirtualsPropertyType takes in THydratedDocumentType and relies on that primarily for context, rather than attempting to reconstruct the hydrated document type. This breaks the circular reference that's causing TypeScript to infer DocType as unknown.

I'm currently working on a related issue with context mismatch in Schema.create() when timestamps, virtuals, methods, and statics are all set in schema options.

[drag0n-app]

@vkarpov15 Setting versionKey: false also triggers this issue. #15798

import mongoose, { Schema } from "mongoose";

const MySchema = new Schema({
  name: { type: String, required: true },
}, {
  statics: {
    testMe: function() {
      console.log(`I'm a static method`);
    }
  },
  versionKey: false,
})

const MyModel = mongoose.model("MyModel", MySchema);

// this triggers a type error
MyModel.testMe();