Implement better and intuitive type definitions for Typescript

[SleepWalker]

I want to propose a different way of defining Model/Document types. Currently the Model class id defined as two interfaces:

• Model holds all the static props of Model class
• Document holds all other props of Model class

If we correctly define Model as class type, we will get an ability to define mongoose models as a classes, e.g.:

class MyModel extends mongoose.Model {
  // declare model fields. Alternatively we can use a generic, but declare looks less hacky
  declare _id: ObjectId;
  declare name: string;

  static async staticMethod() {
    const item = await this.findOne({...});
  }

  async publicMethod() {
    console.log(this.name);
  }
}

In the example above all the methods and properties are correctly typed and the most important thing is that this code is 100% understandable for any developer.

To use current type definitions with classes the only way I found is to cast Model (because it's value is exported without generic). But even with this hack type coverage is not the best possible:

interface UserProps {
  // Document's generic is useless,
  // because it declared as `_id?: T` (notice question mark)
  _id: mongoose.ObjectId;
  name: string;
}

type UserDocument = UserProps & mongoose.Document<mongoose.ObjectId>;

const BaseModel: mongoose.Model<UserDocument> = mongoose.Model as any;

class User extends BaseModel {
  static async testStatic() {
    const isModel: mongoose.Model<any> = this; // fine

    const item = await this.findOne();

    if (item) {
      const id: mongoose.ObjectId = item._id; // fine
      const name: string = item.name; // fine

      const isDoc: mongoose.Document = item; // fine
      // why item is `Document` instead of `this`?
      const isUser: User = item; // ⚠️ ERROR
      item.testPublic(); // ⚠️ ERROR
    }
  }

  async testPublic() {
    this._id;
    this.name;

    // default generic value is useless
    const json = this.toJSON();
    json._id; // ⚠️ ERROR
    json.name; // ⚠️ ERROR

    const json2 = this.toJSON<UserProps>();
    json2._id; // fine
    json2.name; // fine

    const user: User = await this.save(); // fine
  }
}

const user = new User();

User.testStatic(); // fine

const id: mongoose.ObjectId = user._id; // fine
const name: string = user.name; // fine
user.testPublic(); // fine

async () => {
  const item: User | null = await User.findOne(); // ⚠️ ERROR
  const item2: User | null = await user.save(); // fine
};

[vkarpov15]

I agree that class MyModel extends mongoose.Model { ... } looks syntactically neat, but the problem is that Mongoose needs to do some work in order to properly create a model class: compile the schema, attach a connection, register listeners, etc. Which is why, instead of using extends mongoose.Model { ... }, you need to call mongoose.model(). So, while it would be nice to support this syntax, it wouldn't work as written.

[SleepWalker]

actually I'm using this syntax more than two years on production 😅

You can pass class to the mongoose.model, e.g.:

const schema = new mongoose.Schema({
  // ...
});

class User extends mongoose.Model {}

export default mongoose.model(User, schema);

The problem is that earlier, when there was no official support for ts, I've just copied @types/mongoose and fixed type definitions to be usable. The major issue is that Model and Document are defined as two interfaces instead of class. You can not completely define class behavior using only interfaces in ts.

Now, when types are included in mongoose package you can not fix them without dirty hacks. There is also no complete guide about how to use official type definitions. Looks like you should cast types/use generics all the time to be able to use them or it's not really intuitive for me how to get them work.

[vkarpov15]

Your mongoose.model(User, schema); approach should work fine actually, although it's equivalent to mongoose.model('User', schema); The problem is that you need to call mongoose.model(), can't just use classes.

[SleepWalker]

@vkarpov15 I think it's not a problem to call mongoose.model. The problem is that currently Model and Document are separate interfaces which does not allow to use them as a single class.

If we type Model as a class (this means to declare all model methods as static and merge all methods from Document as a regular methods) it should allow the pattern, I've described above. If such approach is acceptable for mongoose I can submit a PR with requested changes. I just don't want to implement the features that 100% won't ever be merged

[vkarpov15]

In theory I'd love to have our TypeScript definitions line up with how Mongoose is actually implemented - internally, Model is a class that extends Document. But we've had no end to trouble figuring out how to get mongoose.model() to return a custom class.

If you can make Model a class without backwards breaking changes, we'd likely merge the PR into v6.0 👍

[SleepWalker]

Great 🔥
I'll try to prepare a PR