Complex types with select & placeholderData

[jamesarosen]

Background

Recently, I came across some code that looked like this:

// some-other-file.ts
type ABigComplexType = {
  foo: { bar: string[] };
  baz: { qux: () => boolean };
  quux: { corge: number };
};

function fetchABigComplexType() {
  return fetch('/api/a-big-complex-type').then((res) => res.json()) as Promise<ABigComplexType>;
}

// my-component.tsx
function MyComponent() {
  const query = useQuery({
    queryKey: ['a-big-complex-type'],
    queryFn: () => fetchABigComplexType(),
    enabled: false,
  });

  useEffect(() => {
    if (someCondition) { void query.refetch(); }
  });

  const bar = useMemo(() => query.data?.foo.bar ?? [], [query.data]);

  <span>{bar.join(', ')}</span>;
}

The Goal

I realized I could simplify by replacing useMemo with a select and the useEffect with enabled: someCondition:

function MyComponent() {
  const query = useQuery({
    queryKey: ['a-big-complex-type'],
    queryFn: () => fetchABigComplexType(),
    enabled: someCondition,
    select: (data) => data?.foo.bar ?? [],
  });

  <span>{query.data.join(', ')}</span>;
}

Problem 1: Null-Pointer Exception

The types work out fine and everything compiles and runs. But there's a new bug. The select doesn't run on the empty initial data, so query.data is undefined, not []. I get a null-pointer exception on query.data.join.

I figure I can solve this "the TanStack Query way" by introducing placeholderData:

function MyComponent() {
  const query = useQuery({
    queryKey: ['a-big-complex-type'],
    queryFn: () => fetchABigComplexType(),
    enabled: someCondition,
    select: (data) => data?.foo.bar ?? [],
    placeholderData: { foo: { bar: [] } },
  });

  <span>{query.data.join(', ')}</span>;
}

Problem 2: Type Errors

But this causes a type error:

No overload matches this call.
  Overload 3 of 3, '(options: UseQueryOptions<ABigComplexType, Error, ABigComplexType, string[]>, queryClient?: QueryClient): UseQueryResult<...>', gave the following error.
    Type 'string[]' is missing the following properties from type 'ABigComplexType': foo, baz, quux
  Overload 3 of 3, '(options: UseQueryOptions<ABigComplexType, Error, ABigComplexType, string[]>, queryClient?: QueryClient): UseQueryResult<...>', gave the following error.
    Type '{ foo: { bar: undefined[]; }; }' is not assignable to type 'ABigComplexType | PlaceholderDataFunction<ABigComplexType, Error, ABigComplexType, string[]>'.
      Type '{ foo: { bar: undefined[]; }; }' is missing the following properties from type 'ABigComplexType': baz, quuxts(2769)

The type of placeholderData needs to be the same as the type of queryFn, but I don't want to have to fill in the rest of the QueryResult structure because it's huge and messy. So I try narrowing the type at the useQuery level:

cost query = useQuery<Pick<ABigComplexType, 'foo'>>(...);

But this introduces a new type error:

No overload matches this call.
  Overload 1 of 3, '(options: UndefinedInitialDataOptions<Pick<ABigComplexType, "foo">, Error, Pick<ABigComplexType, "foo">, QueryKey>, queryClient?: QueryClient): UseQueryResult<...>', gave the following error.
    Property 'foo' is missing in type 'string[]' but required in type 'Pick<ABigComplexType, "foo">'.
  Overload 2 of 3, '(options: DefinedInitialDataOptions<Pick<ABigComplexType, "foo">, Error, Pick<ABigComplexType, "foo">, QueryKey>, queryClient?: QueryClient): DefinedUseQueryResult<...>', gave the following error.
    Property 'foo' is missing in type 'string[]' but required in type 'Pick<ABigComplexType, "foo">'.
  Overload 3 of 3, '(options: UseQueryOptions<Pick<ABigComplexType, "foo">, Error, Pick<ABigComplexType, "foo">, QueryKey>, queryClient?: QueryClient): UseQueryResult<...>', gave the following error.
    Property 'foo' is missing in type 'string[]' but required in type 'Pick<ABigComplexType, "foo">'.ts(2769)

By default, TQueryFnData is unknown, so TData is also unknown, causing TypeScript to intuit it. But now that I've explicitly defined the type for queryFn and placeholderData, TypeScript is trying to use that type for the result of select.

Solutions

The first is to explicitly define both TQueryFnData and TData:

function MyComponent() {
  const query = useQuery<Pick<ABigComplexType, 'foo'>, DefaultError, ABigComplexType['foo']['bar']>({
    queryKey: ['a-big-complex-type'],
    queryFn: () => fetchABigComplexType(),
    enabled: someCondition,
    select: (data) => data?.foo.bar,
    placeholderData: { foo: { bar: [] } },
  });

  <span>{query.data ? 'Bar!' : 'Not bar'}</span>;
}

It's OK. I'd take it if it were the only option, but there's a lot of explicit type coupling that will make it hard to modify.

The second is to explicitly type TQueryFnData and explicitly not define TData:

function MyComponent() {
  const query = useQuery<Pick<ABigComplexType, 'foo'>, DefaultError, unknown>({
    queryKey: ['a-big-complex-type'],
    queryFn: () => fetchABigComplexType(),
    enabled: someCondition,
    select: (data) => data?.foo.bar,
    placeholderData: { foo: { bar: [] } },
  });

  <span>{query.data ? 'Bar!' : 'Not bar'}</span>;
}

That works because I'm forcing TypeScript to intuit TData. I like this about the same as the first option. It feels like I'm copying some semi-private aspects of the TanStack Query API into my code.

The third option is to put the type refinement on queryFn and not on useQuery:

function MyComponent() {
  const query = useQuery({
    queryKey: ['a-big-complex-type'],
    queryFn: () => fetchABigComplexType() as Promise<Pick<ABigComplexType, 'foo'>>,
    enabled: someCondition,
    placeholderData: { foo: { bar: [] } },
    select: (data) => data?.foo.bar,
  });

  <span>{query.data ? 'Bar!' : 'Not bar'}</span>;
}

Of the three options I found, I like this best. It seems the least likely to break due to changes in TanStack Query because I'm following the intent of the API.

Future Work

It looks like TanStack Query uses TQueryFnData as the argument for select. It would be lovely if it could further refine that as TQueryFnData & PlaceholderData so I'm guaranteed that select can run on both placeholder and real data without having to stub out the full type.

[TkDodo]

If you use placeholderData, your placeholderData needs to be the same type that the (unwrapped) queryFn produces. { foo: { bar: [] } } does not satisfy ABigComplexType, so TypeScript is correct. It would be valid to change your select to access data.quux.corge, and if you do that, you’d run into a runtime error because your placeholderData doesn’t provide quux.

All your type workarounds are just that - workarounds. Passing type parameters specifically to useQuery is the same thing that type inference will achieve if your values are setup correctly.

So what I would do is make placeholderData have the correct shape. However, you still might have query.data be potentially undefined, because placeholderData can’t do any type narrowing. The reason is it actually goes away at runtime if your query fails, you can read about that here: https://tkdodo.eu/blog/placeholder-and-initial-data-in-react-query

[jamesarosen]

You're not wrong, but making placeholderData have the correct shape in my real implementation (from @hey-api/client-fetch) is rather tedious and a bit of a waste of memory and CPU:

placeholderData: () => ({
  data: {},
  error: undefined,
  request: new Request('/nowhere'),
  response: new Response('no body'),
}),

I guess another option is to actually make queryFn return what I want:

queryFn: () => {
  return fetchABigComplexType().then(result => result.foo.bar)
}

But now this query function can't share the cache with anything else that uses fetchABigComplexType or their caches will conflict. That's the whole purpose of using select.