Why findById returns (User & { _id: Schema.Types.ObjectId; }) | null they User | null

This is my first time using typescript and mongoose. Here’s my code

type

export interface User extends Document {
  _id: ObjectId;
  lastName: string;
}

Schema

const userSchema = new Schema<User>({
  lastName: { type: String, required: true, trim: true },
});

model

const User = model<User>('user', UserSchema, 'users');

request

const user = await User.findById(userId).exec();

I expect the user variable to be of type User | null.but i get (User & {_id: Schema.Types.ObjectId;}) | null. If I don’t declare _id: ObjectId; then I get ( User & { _id: any; }) | null. I do not know if this is some kind of mistake or it should be like this

[vkarpov15]

@drewkht 's comment https://github.com/Automattic/mongoose/issues/10987#issuecomment-996170399 is correct. We added a note about the Schema.Types.ObjectId vs Types.ObjectId distinction in #10949

[drewkht]

I’ve the same code except that _id is any in the interface, the return type of a findOne is:

const user: IUser & {
    _id: any;
}

I think it should be IUser, where this & comes from?

The return type comes from the internal types used by mongoose.model() to create the User model.

Mongoose’s HydratedDocument<T> type is used for all documents created/queried by a model of type Model<T>. It’s explained further in the linked Mongoose docs.

Because the User interface extends Document, HydratedDocument<User> resolves to the Mongoose internal type Require_id<User>, which simply creates a type ~union~ intersection User & { _id: User['_id'] } (to, I assume, ensure that the _id property is non-nullable - as the _id property on Mongoose’s Document type is nullable).

User & { _id: Schema.Types.ObjectId } is a functionally identical type to User, because User already contains the property _id: Schema.Types.ObjectId. It definitely looks weird if you’re not familiar with what’s going on behind the scenes or with TypeScript ~unions~ intersections, though.

@Darfion - I believe if you just change the _id property in the User interface to Types.ObjectId instead you’ll get the proper results (i.e. const user will be of type HydratedDocument<User, ...> | null). Types.Schema.ObjectId is only intended to be used within schema definitions, from what I understand.

Also, a couple potential issues in the provided examples:

export interface User extends Document { ... }
const User = model<User>('user', UserSchema, 'users');

At least in my VS Code with my tsconfig.json, this causes a naming conflict between the User interface and const User, resulting in the latter resolving to any. Either renaming the interface to something like IUser or const User to something like const UserModel would solve this problem.

const userSchema = new Schema<User>({ ... });
const User = model<User>('user', UserSchema, 'users');

In the above, userSchema is used to create the schema, but then UserSchema (with an uppercase U) is passed to the model function. Because you’re passing User as a type parameter to the model call (which isn’t necessary if you’re passing the type to Schema already) you’ll still get a correctly typed Model from it, but I’m not sure what other issues might arise from not providing an actual Schema to the function.

I rewrote the example like this and it works as expected in my testing:

import { Types, model, Document, Schema } from 'mongoose';

export interface IUser extends Document {
  _id: Types.ObjectId;
  lastName: string;
}

const userSchema = new Schema<IUser>({
  lastName: { type: String, required: true, trim: true },
});

const User = model('user', userSchema, 'users');

const user = await User.findById(userId).exec();   // user: HydratedDocument<IUser, {}, {}> | null
if (user) user._id;   // user._id: Types.ObjectId