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

docs/typescript/statics-and-methods.md

@@ -80,3 +80,186 @@ 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 merge types.
+
+```ts
+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
+);
+
+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.
+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
+  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()` Caveat
+
+`loadClass()` attaches methods at runtime.
+However, `toObject()` and `toJSON()` return **plain JavaScript objects** without these methods.
+
+```ts
+const doc = new MyModel({ property1: 'test' });
+const pojo = doc.toObject();
+```
+
+Runtime:
+
+```ts
+pojo.myMethod(); // runtime error
+```
+
+TypeScript:
+
+```ts
+pojo.myMethod; // compiles (unsafe)
+```
+
+This is a known limitation:
+TS cannot detect when class methods are dropped.
+
+## 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
+interface MySchema {
+  property1: string;
+}
+
+class MyClass {
+  myMethod(this: MyCombinedDocument) {
+    return this.property1;
+  }
+  static myStatic(this: MyCombinedModel) {
+    return 42;
+  }
+}
+
+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>(
+  'MyClass',
+  schema as any
+);
+```
+
+## 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 } 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 the #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;
+  }
+}
+