Why is there a type issue when using useQuery with a UseQueryOptions object spread?

[yilinsim]

Hi all,

I've been trying to better understand why I'm seeing a typescript error after migrating from react-query v3 to v4. Sorry if this has been answered before but would greatly appreciate any insights on this! :)

Issue

Doing something like this:

const useCustomQuery = (
  options?: Omit<UseQueryOptions<IQueryFnData>, "queryKey" | "queryFn">
) => {
  return useQuery({
    ...options,
    queryKey: ["todos-key"], // Error: 'queryKey' does not exist in type 'readonly unknown[]
    queryFn: () =>
      Promise.resolve({
        name: "Todos List",
        description: "List of things to do :)"
      } as IQueryFnData)
  });
};

Returns a type error:

No overload matches this call.
  The last overload gave the following error.
    Argument of type '{ queryKey: string[]; queryFn: () => Promise<IQueryFnData>; context?: React.Context<QueryClient | undefined> | undefined; enabled?: boolean | undefined; ... 31 more ...; meta?: QueryMeta | undefined; }' is not assignable to parameter of type 'QueryKey'.
      Object literal may only specify known properties, and 'queryKey' does not exist in type 'readonly unknown[]'.

The Problem

If the generics are not specified in UseQueryOptions, we end up falling back to the default where TQueryKey = QueryKey, which is readonly unknown[].

Potential Solutions

The recommended approach is to not use UseQueryOptions but only providing those that you want consumers to override. However, as part of this migration, I'll be working on a large number of files. Re-creating the types may not be feasible for me. Hence, I'm investigating if other approaches could fit my use case. Some options I found:

1. Specify all generics in UseQueryOptions only (specify TQueryKey as string[])

const useCustomQueryFix2 = (
  options?: Omit<
    UseQueryOptions<IQueryFnData, unknown, IQueryFnData, string[]>,
    "queryKey" | "queryFn"
  >
) => { ... }

2. Specify only first generic in both UseQueryOptions and useQuery

const useCustomQueryFix3 = (
  options?: Omit<UseQueryOptions<IQueryFnData>, "queryKey" | "queryFn">
) => {
  return useQuery<IQueryFnData>({ ... });
};

3. Explicitly type ["todos-key"] as QueryKey

const useCustomQueryFix4 = (
  options?: Omit<UseQueryOptions<IQueryFnData>, "queryKey" | "queryFn">
) => {
  return useQuery({
    ...options,
    queryKey: ["todos-key"] as QueryKey,
    ...
  });
};

Questions

1. Why is a hardcoded queryKey not assignable to QueryKey? Can't we cast string[] as unknown[]?
   From Types no longer inferred correctly #2753 (comment):
   
2. Why does passing the first generic to useQuery work as a potential fix without needing to specify TQueryKey generic in UseQueryOptions (See fix 2 above)? Does specifying first generic for useQuery effectively casts ["todos-key"] as QueryKey?
3. For all these solutions, what issue does this cause to 'select' - would it be a typing issue detected at compile time? Can I just explicitly change the type of the 3rd generic based on the 'select' passed into options (if used)? Alternatively, if 'select' is omitted from the UseQueryOptions, is this fine?

Code Sandbox

https://codesandbox.io/s/goofy-gates-84llxt?file=/src/index.tsx

References

• Advice to not create abstractions: How to create a custom useQuery hook with optional configuration options (useQueryOption)❓ #3227
• Fix 2 and fix 3: UseQueryOptions<TQueryFnData, TError> Defaults & Type Error  #2795 (comment)
• Problem and fix 1: Types no longer inferred correctly #2753 (comment)
• Twiter post to 'never pass generics to useQuery'❓: https://twitter.com/TkDodo/status/1491451529165176835?s=20
• Post about 4 generics and how 'select' works: https://tkdodo.eu/blog/react-query-and-type-script#the-four-generics

[TkDodo]

The problem is more tricky than it initially seems. In v5, we've removed the overloads, and none of your solutions (except solution1, because it doesn't use UseQueryOptions) will actually work (see this playground)

The all have the same type error:

Type 'IQueryFnData | InitialDataFunction<IQueryFnData> | undefined' is not assignable to type 'IQueryFnData | (() => IQueryFnData)'.(2769)

My best guess is because we have one overload left in v5, which is initialData. initialData can be used to change the type of the returned data to be always defined, if you provide initialData.

One quick fix that makes all solutions work is to also omit initialData from the QueryOptions (playground here). Even the initial, non-working example works fine with that.

I think it might be that we are missing another overload here that has an implementation for UseQueryOptions. I'll look into that.

[TkDodo]

I think I have a fix here, see this test:

query/packages/react-query/src/__tests__/useQuery.types.test.tsx

Lines 103 to 124 in 8aee98f

	describe('custom hook', () => {
	it('should allow custom hooks using UseQueryOptions', () => {
	doNotExecute(() => {
	type Data = string
	const useCustomQuery = (
	options?: Omit<UseQueryOptions<Data>, 'queryKey' | 'queryFn'>,
	) => {
	return useQuery({
	...options,
	queryKey: ['todos-key'],
	queryFn: () => Promise.resolve('data'),
	})
	}
	const { data } = useCustomQuery()
	const result: Expect<Equal<Data | undefined, typeof data>> = true
	return result
	})
	})
	})

it's in this PR:

• Feature/usequeryoptions types #5803

[yilinsim]

Thank you so much for the quick reply and fix! 😄

@TkDodo Just have a follow up question. For now since I'm migrating to v4, I'm thinking of using overloads in useQuery for a temporary fix for the typing error (customQueryFix3 in this sandbox). Wanted to check with you, would that be okay? If select causes a typing issue, could I just specify the 3rd generic for TData?

Then, when migrating from v4 to v5 in the future, I could just remove the overloads altogether.

[TkDodo]

If select causes a typing issue, could I just specify the 3rd generic for TData?

you need the 3rd generic for select mainly, yes. Even in v5 it will be needed. What I did in the test:

options?: Omit<UseQueryOptions<Data>, 'queryKey' | 'queryFn'>, 

is not what I'd personally do in user-land :)

[yilinsim]

Got it, and in user-land, you would recommend doing something like customQueryFix1 instead?

(options?: {
  onSuccess: (data: IQueryFnData) => void;
  onError: (error: Error) => void;
}),

[TkDodo]

yes. (except that onError and onSuccess are deprecated)