Improve TypeScript support for dynamic queryKey with union types

[onyedikachi23]

Describe the bug

Indexing a query factory with a union type (UserType = "company" | "club" | "player" | "supporter") causes TypeScript type mismatches in useQuery, ensureQueryData, getQueryData, and so on. The issue arises because entityProfileQueries[userType] returns a union of query options with distinct queryKey types (e.g., { userType: "player" } vs. { userType: "supporter" }), while these utilities expect a single type.

The player and supporter queries share ServerPlayerResponse and a select function, but the error occurs for all UserType values due to the queryKey union.

Your minimal, reproducible example

https://stackblitz.com/edit/vitejs-vite-yzi9yarp?file=src%2Floader.ts

Steps to reproduce

In the MRE, the error arises from this line in src/loader.ts:

const data = await queryClient.ensureQueryData(queryOptions);

queryOptions is underlined with an error, and typeof data is incorrectly resolving to ServerPlayerResponse.

Expected behavior

The returned data from queryClient.ensureQueryData(queryOptions) should be a union of:

type TData = CompanyProfileData | ClubProfileData | PlayerProfileData

Noting that userType - player and supporter, share exactly the same TQueryFnData and TData from the select option, but queryKey differ by { userType: "player" } vs. { userType: "supporter" }

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

• OS: all
• browser: all
• version: latest

Tanstack Query adapter

react-query

TanStack Query version

latest

TypeScript version

latest

Additional context

Affects useQuery, ensureQueryData, getQueryData, and so on.

[onyedikachi23]

Please an immediate possible workaround is what I need for now.

[cseas]

Please an immediate possible workaround is what I need for now.

You can workaround this by providing an explicit type cast.

From your reproducible example:

import type { EnsureQueryDataOptions } from '@tanstack/react-query';
...
const data = await queryClient.ensureQueryData(queryOptions as EnsureQueryDataOptions);

For figuring out where the type mismatch is happening, you might need to add explicit type definitions to the entityProfileQueries object and work your way backwards to pinpoint the type mismatch.

The all: () => ['entity-profile'] as const, part of the object is likely making the inferred type of the object complicated as its different than the rest of the object entries.

[onyedikachi23]

as EnsureQueryDataOptions will remove the original correct types. Also, having to write explicit type definitions for that query factory will introduce complexities in managing the types.

[chekrd]

I've created a repository with a simplified, minimalistic example demonstrating how we added full type safety to queryClient imperative methods.
https://github.com/chekrd/rq-typed-client-demo/
This approach could be implemented directly into React Query if the library adopts some opinionated constraints on key structure. Check out the updateContentType.ts module and experiment with the updater implementation on line 23.

[chekrd]

I think RQ can implement it through registering not only QueryKey but query key to cache model type map.