docs: add detailed loadClass() TypeScript usage guide and new loadcla…

docs/typescript/statics-and-methods.md

@@ -80,3 +80,203 @@ const doc = new User({ name: 'test' });
 // Compiles correctly
 doc.updateName('foo');
 ```
+
+# Using `loadClass()` with TypeScript
+
+Mongoose supports applying ES6 classes to a schema using [`schema.loadClass()`](../api/schema.html#Schema.prototype.loadClass()).
+When using TypeScript, there are a few important typing details to understand.
+
+## Basic Usage
+
+`loadClass()` copies static methods, instance methods, and ES getters/setters from the class onto the schema.
+
+```ts
+class MyClass {
+  myMethod() {
+    return 42;
+  }
+
+  static myStatic() {
+    return 42;
+  }
+
+  get myVirtual() {
+    return 42;
+  }
+}
+
+const schema = new Schema({ property1: String });
+schema.loadClass(MyClass);
+```
+
+Mongoose does not automatically update TypeScript types for class members. To get full type support, you must manually define types using Mongoose's [Model](../api/model.html) and [HydratedDocument](../typescript.html) generics.
+
+```ts
+// 1. Define an interface for the raw document data
+interface RawDocType {
+  property1: string;
+}
+
+// 2. Define the Model type
+// This includes the raw data, query helpers, instance methods, virtuals, and statics.
+type MyCombinedModel = Model<
+  RawDocType, 
+  {}, 
+  Pick<MyClass, 'myMethod'>, 
+  Pick<MyClass, 'myVirtual'> 
+> & Pick<typeof MyClass, 'myStatic'>; 
+
+// 3. Define the Document type
+type MyCombinedDocument = HydratedDocument<
+  RawDocType,
+  Pick<MyClass, 'myMethod'>, 
+  {}, 
+  Pick<MyClass, 'myVirtual'> 
+>;
+
+// 4. Create the Mongoose model
+const MyModel = model<RawDocType, MyCombinedModel>(
+  'MyClass',
+  schema
+);
+
+MyModel.myStatic();
+const doc = new MyModel();
+doc.myMethod();
+doc.myVirtual;
+doc.property1;     
+```
+
+## Typing `this` Inside Methods
+
+You can annotate `this` in methods to enable full safety, using the [Model](../api/model.html) and [HydratedDocument](../typescript.html) types you defined.
+Note that this must be done for **each method individually**; it is not possible to set a `this` type for the entire class at once.
+
+```ts
+class MyClass {
+  // Instance method typed with correct `this` type
+  myMethod(this: MyCombinedDocument) {
+    return this.property1;
+  }
+
+  // Static method typed with correct `this` type
+  static myStatic(this: MyCombinedModel) {
+    return 42;
+  }
+}
+```
+
+### Getters / Setters Limitation
+
+TypeScript currently does **not** allow `this` parameters on getters/setters:
+
+```ts
+class MyClass {
+  // error TS2784: 'this' parameters are not allowed in getters
+  get myVirtual(this: MyCombinedDocument) {
+    return this.property1;
+  }
+}
+```
+
+This is a TypeScript limitation. See: [TypeScript issue #52923](https://github.com/microsoft/TypeScript/issues/52923)
+
+As a workaround, you can cast `this` to the document type inside your getter:
+
+```ts
+get myVirtual() {
+  // Workaround: cast 'this' to your document type
+  const self = this as MyCombinedDocument;
+  return `Name: ${self.property1}`;
+}
+```
+
+## `toObject()` / `toJSON()`
+
+When using the correct [Model](../api/model.html) and [HydratedDocument](../typescript.html) generics (as shown above), Mongoose's types for `toObject()` and `toJSON()` work as expected. They will correctly return a type that includes **only the raw data** (e.g., `RawDocType`), not the methods or virtuals.
+
+This is a feature, as it accurately reflects the plain object returned at runtime and prevents you from trying to access methods that don't exist.
+
+```ts
+const doc = new MyModel({ property1: 'test' });
+const pojo = doc.toObject();
+
+// This now correctly causes a TypeScript error!
+// pojo.myMethod(); // Property 'myMethod' does not exist on type 'RawDocType'.
+```
+
+## Limitations
+
+| Behavior                                       | Supported |
+| ---------------------------------------------- | --------- |
+| Copy instance / static methods                 | ✅         |
+| Copy getters/setters                           | ✅         |
+| Automatic TS merging                           | ❌         |
+| `this` typing in methods                       | ✅         |
+| `this` typing in getters/setters               | ❌         |
+| Methods preserved in `toObject()` / `toJSON()` | ❌         |
+| Methods preserved with `.lean()`               | ❌         |
+
+## Full Example Code
+
+```ts
+import { Model, Schema, model, HydratedDocument } from 'mongoose';
+
+interface RawDocType {
+  property1: string;
+}
+
+class MyClass {
+  myMethod(this: MyCombinedDocument) {
+    return this.property1;
+  }
+
+  static myStatic() {
+    return 42;
+  }
+
+  get myVirtual() {
+    const self = this as MyCombinedDocument;
+    return `Hello ${self.property1}`;
+  }
+}
+
+const schema = new Schema<RawDocType>({ property1: String });
+schema.loadClass(MyClass);
+
+type MyCombinedModel = Model<
+  RawDocType,
+  {},
+  Pick<MyClass, 'myMethod'>,
+  Pick<MyClass, 'myVirtual'>
+> & Pick<typeof MyClass, 'myStatic'>;
+
+type MyCombinedDocument = HydratedDocument<
+  RawDocType,
+  Pick<MyClass, 'myMethod'>,
+  {},
+  Pick<MyClass, 'myVirtual'>
+>;
+
+const MyModel = model<RawDocType, MyCombinedModel>(
+  'MyClass',
+  schema
+);
+
+const doc = new MyModel({ property1: 'world' });
+doc.myMethod(); 
+MyModel.myStatic(); 
+console.log(doc.myVirtual); 
+```
+
+## When Should I Use `loadClass()`?
+
+`loadClass()` is useful when organizing logic in ES6 classes.
+
+However:
+
+* ✅ works fine
+* ⚠ requires manual TS merging
+* ⚠ methods lost in `toObject()` / `toJSON()` / `lean()`
+
+If you want better type inference, [`methods`](../guide.html#methods) & [`statics`](../guide.html#statics) on schema are recommended.

test/types/loadclass.test.ts

@@ -0,0 +1,177 @@
+import { Schema, model, Document, Model, Types } from 'mongoose';
+import { expectType, expectError } from 'tsd';
+
+
+// Basic usage of `loadClass` with TypeScript
+function basicLoadClassPattern() {
+  class MyClass {
+    myMethod() { return 42; }
+    static myStatic() { return 42; }
+    get myVirtual() { return 42; }
+  }
+
+  const schema = new Schema({ property1: String });
+  schema.loadClass(MyClass);
+
+  interface MySchema {
+    property1: string;
+  }
+
+
+  // `loadClass()` does NOT update TS types automatically.
+  // So we must manually combine schema fields + class members.
+  type MyCombined = MySchema & MyClass;
+
+  // The model type must include statics from the class
+  type MyCombinedModel = Model<MyCombined> & typeof MyClass;
+
+  // A document must combine Mongoose Document + class + schema
+  type MyCombinedDocument = Document & MyCombined;
+
+  // Cast schema to satisfy TypeScript
+  const MyModel = model<MyCombinedDocument, MyCombinedModel>('MyClass', schema as any);
+
+  // Static function should work
+  expectType<number>(MyModel.myStatic());
+
+  // Instance method should work
+  const doc = new MyModel();
+  expectType<number>(doc.myMethod());
+
+  // Getter should work
+  expectType<number>(doc.myVirtual);
+
+  // Schema property should be typed
+  expectType<string>(doc.property1);
+}
+
+
+// Using `this` typing in class methods
+
+function thisParameterPattern() {
+  interface MySchema {
+    property1: string;
+  }
+
+  class MyClass {
+    // Instance method typed with correct `this` type
+    myMethod(this: MyCombinedDocument) {
+      return this.property1;
+    }
+
+    // Static method typed with correct `this` type
+    static myStatic(this: MyCombinedModel) {
+      return 42;
+    }
+
+
+    // TypeScript does NOT allow `this` parameters in getters/setters.
+    // So we show an example error here.
+    get myVirtual() {
+      expectError(this.property1);
+      // @ts-expect-error: getter does not support `this` typing
+      return this.property1;
+    }
+  }
+
+  const schema = new Schema<MySchema>({ property1: String });
+  schema.loadClass(MyClass);
+
+  type MyCombined = MySchema & MyClass;
+  type MyCombinedModel = Model<MyCombined> & typeof MyClass;
+  type MyCombinedDocument = Document & MyCombined;
+
+  const MyModel = model<MyCombinedDocument, MyCombinedModel>('MyClass2', schema as any);
+
+  // Test static
+  expectType<number>(MyModel.myStatic());
+
+  const doc = new MyModel({ property1: 'test' });
+
+  // Instance method returns string
+  expectType<string>(doc.myMethod());
+
+  // Schema field is typed correctly
+  expectType<string>(doc.property1);
+
+
+  // Getter works at runtime, but TypeScript can't type `this` in getters.
+  // So we accept `any`.
+  const virtual = doc.myVirtual;
+  expectType<any>(virtual);
+}
+
+
+// ----------------------------------------------------------
+// Test that `toObject()` / `toJSON()` lose class behavior.
+// But TypeScript does NOT warn you about this.
+//
+// This matches the behavior described in issue #12813:
+// > doc.toObject().myMethod() compiles but fails at runtime
+// ----------------------------------------------------------
+function toObjectToJSONTest() {
+  class MyClass {
+    myMethod() { return 42; }
+    static myStatic() { return 42; }
+    get myVirtual() { return 42; }
+  }
+
+  const schema = new Schema({ property1: String });
+  schema.loadClass(MyClass);
+
+  interface MySchema {
+    property1: string;
+  }
+
+  type MyCombined = MySchema & MyClass;
+  type MyCombinedModel = Model<MyCombined> & typeof MyClass;
+  type MyCombinedDocument = Document & MyCombined;
+
+  const MyModel = model<MyCombinedDocument, MyCombinedModel>('MyClass3', schema as any);
+
+  const doc = new MyModel({ property1: 'test' });
+
+
+  // toObject():
+  //  returns plain object
+  //  loses methods at runtime
+  //  TypeScript still thinks methods exist
+  const pojo = doc.toObject();
+
+  // Schema property is still typed
+  expectType<string>(pojo.property1);
+
+  // TS still thinks class method exists (wrong at runtime)
+  expectType<() => number>(pojo.myMethod);
+
+  // Same caveat applies to toJSON()
+  const json = doc.toJSON();
+
+  expectType<() => number>(json.myMethod);
+  expectType<string>(json.property1);
+}
+
+
+// Getter limitation example
+// TypeScript does not allow `this` param on getters
+
+function getterLimitationTest() {
+  interface MySchema {
+    name: string;
+  }
+
+  class TestGetter {
+    name: string;
+
+    // TS errors if you try `this` in getter
+    // @ts-expect-error TS2784: 'this' parameters are not allowed in getters
+    get test(this: TestDoc): string {
+      return this.name;
+    }
+  }
+
+  interface TestDoc extends TestGetter, Omit<Document, '_id'> {
+    _id: Types.ObjectId;
+  }
+}
+