Ref<T> property cant be filtered with string or ObjectId in v13

[angelhodar]

Versions

• System: Windows
• NodeJS: 24.10.0
• Typescript: 5.9.3
• Compiler / Transpiler: tsc / ts-node
• Typegoose(NPM): 13.0.0
• mongoose: 9.0.2

What is the Problem?

When upgrading to Typegoose 13 (which uses Mongoose 9), filtering by a Ref<T> field using a string, ObjectId, or even the _id property from a document causes a TypeScript compilation error. In previous versions, these types were accepted in filter queries.

The specific errors encountered are:

No overload matches this call.
  Overload 1 of 4, '(filter?: _QueryFilter<{ name: string; user: User; "user.name": never; "user.email": never; }> | undefined, projection?: ProjectionType<Campaign> | null | undefined, options?: (QueryOptions<...> & Abortable) | undefined): QueryWithHelpers<...>', gave the following error.
    Type 'ObjectId' is not assignable to type 'Condition<ApplyBasicQueryCasting<User>> | undefined'.
      Type 'ObjectId' is not assignable to type 'FilterOperators<User | User[] | null>'.
        Types of property 'id' are incompatible.
          Type 'Uint8Array<ArrayBufferLike>' is not assignable to type 'undefined'.
  Overload 2 of 4, '(filter?: Query<any, any, {}, unknown, "find", Record<string, never>> | undefined, projection?: ProjectionType<Campaign> | null | undefined, options?: (QueryOptions<...> & Abortable) | undefined): QueryWithHelpers<...>', gave the following error.
    Object literal may only specify known properties, and 'user' does not exist in type 'Query<any, any, {}, unknown, "find", Record<string, never>>'.

This breaks common patterns like filtering by IDs received from external APIs (as strings) or using standard ObjectId instances for querying.

Code Example

Full reproduction repository: https://github.com/angelhodar/typegoose-13-repro

Do you know why it happens?

It appears to be a combination of Typegoose 13's stricter Ref<T> type definition and Mongoose 9's transition to QueryFilter (which replaced FilterQuery). The Ref<T> type doesn't seem to include string or Types.ObjectId in its valid query values, even though Mongoose accepts these types correctly at runtime. This creates a mismatch between TypeScript's type checking and Mongoose's actual runtime behavior.

[hasezoey]

I could verify this and track it down to mongoose (Reproduction Repository & branch)

Issue at mongoose: Automattic/mongoose#15923

It appears to be a combination of Typegoose 13's stricter Ref type definition

Both in mongoose & typegoose, Ref did not change at all. This is entirely (AFAIK) a issue with the stricter QueryFilter.

Workarounds for now are to ignore the errors via a // @ts-expect-error or casting the whole filter as any.

[angelhodar]

Thank you! I think I will wait for more stability from the mongoose side before upgrading. I forgot to ask you if now that the id prop is added to the virtuals as string, do we need the base class with the id prop anymore?

[hasezoey]

I forgot to ask you if now that the id prop is added to the virtuals as string, do we need the base class with the id prop anymore?

I guess yes, it wouldnt be necessary anymore. Might remove in the future.
Though note that typegoose practically always applies the id: string virtual as it has no way of checking decorator settings (or model creation calls) and i have not added a way to control that yet.

[hasezoey]

The types bug has been fixed upstream and will be part of mongoose 9.1.3, which, if the release cadence is anything to go by, will be released within the next week.
Typegoose will likely not update the mongoose requirement until mongoose 9.2.0 (or mongoose does a breaking change in 9.1.x), but mongoose can be updated by your package manager (without typegoose requiring to update it).

I will let this issue stay open until typegoose upgrades the mongoose version.

[KeithGillette]

Has this issue been resolved? I'm getting TS2684 errors involving _QueryFilter (but also many other types) when attempting to upgrade from mongoose@8.19.4 & @typegoose/typegoose@12.20.0 to mongoose@9.1.5 & @typegoose/typegoose@13.1.0 and am not sure if it's related to this known issue or is a separate type incompatibility.

[hasezoey]

I'm getting TS2684 errors involving _QueryFilter (but also many other types)

Specifically, the _QueryFilter type issue is because mongoose 9.0 changed the names, which typegoose 13.0.0 already addressed.

Please open a new issue for your case. Though, first i would recommend to review your dependency tree of duplicate typegoose / mongoose installations (or plugin version dependencies, ex mongoose-paginate-v2). Also make sure you run the required typescript version (which as of typegoose 13 is 5.9.3)