Suggestion: improve ergonomics of *InfiniteOptions types

[OliverJAsh]

Describe the bug

The docs suggest using infiniteQueryOptions to abstract infinite query options. For example:

import { infiniteQueryOptions } from '@tanstack/react-query';

export const queryOptions = infiniteQueryOptions({
  queryKey: ['foo'],
  queryFn: ({ pageParam }) => Promise.resolve({ foo: 'bar' }),
  initialPageParam: 1,
  getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam + 1,
});

However, when using TypeScript's isolated declarations (isolatedDeclarations), all module exports must have type annotations. For this reason it would be preferable to use a type annotation rather than the infiniteQueryOptions type constructor.

The problem with this, however, is it's very verbose:

import type {
  DefaultError,
  InfiniteData,
  QueryKey,
  UnusedSkipTokenInfiniteOptions,
} from '@tanstack/react-query';

type MyResponse = {
  foo: string;
};

export const queryOptions: UnusedSkipTokenInfiniteOptions<
  MyResponse,
  DefaultError,
  InfiniteData<MyResponse, number>,
  QueryKey,
  number
> = {
  queryKey: ['foo'],
  queryFn: ({ pageParam }) => Promise.resolve({ foo: 'bar' }),
  initialPageParam: 1,
  getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam + 1,
};

Except for the first and last type parameters provided to UnusedSkipTokenInfiniteOptions, all the others could theoretically just use the defaults. However, we're forced to provide them because we need to provide TPageParam (the last type parameter), otherwise it would default to unknown.

Given more TypeScript users will likely be looking to enable isolated declarations in the future and thus be required to add type annotations, I wonder if we could make these types more ergonomic.

One idea would be to move the position of the TPageParam type parameter in the *InfiniteOptions types, so we can benefit from defaults. For example, if it was moved from last to second position then the example above would look much better:

import type {
  DefaultError,
  InfiniteData,
  QueryKey,
  UnusedSkipTokenInfiniteOptions,
} from '@tanstack/react-query';

type MyResponse = {
  foo: string;
};

export const queryOptions: UnusedSkipTokenInfiniteOptions<
  MyResponse,
  number
> = {
  queryKey: ['foo'],
  queryFn: ({ pageParam }) => Promise.resolve({ foo: 'bar' }),
  initialPageParam: 1,
  getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam + 1,
};

-type UnusedSkipTokenInfiniteOptions<TQueryFnData, TError = DefaultError, TData = InfiniteData<TQueryFnData>, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> = OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey, TPageParam>, 'queryFn'> & {
    queryFn?: Exclude<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey, TPageParam>['queryFn'], SkipToken | undefined>;
};
+type UnusedSkipTokenInfiniteOptions<TQueryFnData, TPageParam = unknown, TError = DefaultError, TData = InfiniteData<TQueryFnData, TPageParam>, TQueryKey extends QueryKey = QueryKey> = OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey, TPageParam>, 'queryFn'> & {
    queryFn?: Exclude<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey, TPageParam>['queryFn'], SkipToken | undefined>;
};

Your minimal, reproducible example

N/A

Steps to reproduce

N/A

Expected behavior

N/A

How often does this bug happen?

None

Screenshots or Videos

No response

Platform

N/A

Tanstack Query adapter

None

TanStack Query version

N/A

TypeScript version

No response

Additional context

No response

[TkDodo]

using the defaults doesn’t really help much because using them will make features where type inference is necessary, like select, not work.

We use isolatedModules without explicitly giving everything a return type annotation, so I’m not really sure why inference can’t be used. We also can’t change the type param order because that would be a breaking change.

Moving to a discussion.

[OliverJAsh]

Sorry, I was talking about isolatedDeclarations, not isolatedModules. Hopefully that clarifies things?

[samhh]

Such inference is incompatible with isolated declarations: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#isolated-declarations

There is already some early-stage tooling such as oxc-transform that leverages this feature, dramatically speeding up typechecking in large projects by essentially eliminating the time taken to perform declaration emit.

This is still quite immature in the ecosystem but it's the direction of travel.

[karlshea]

Hijacking this a bit because I'm having a similar problem but even passing the types isn't helping. I'm trying to convert a component to TypeScript and I cannot get type generics to work with useInfiniteQuery. I've trimmed this down to as minimal of an example as I can:

import React, { ReactNode } from 'react';
import {
  DefaultError,
  InfiniteData,
  infiniteQueryOptions,
  QueryKey,
  useInfiniteQuery,
} from '@tanstack/react-query';

type TestPageParams = {};

export interface InfiniteScrollProps<T, P extends TestPageParams> {
  children: (data: InfiniteData<T, P> | undefined) => ReactNode;
  queryFn: (pageParam: P) => Promise<T>;
  queryKey: QueryKey;
  initialPageParam: P;
}

export const InfiniteScroll = <T, P extends TestPageParams>({
  children,
  queryFn,
  queryKey,
  initialPageParam,
}: InfiniteScrollProps<T, P>) => {
  const { data } = useInfiniteQuery(
    infiniteQueryOptions({
      queryKey: [...queryKey, initialPageParam],
      queryFn: ({ pageParam }) => queryFn(pageParam),
      initialPageParam,
      getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam,
    })
  );

  return <>{children(data)}</>;
};

I'm getting "TS2345: Argument of type unknown is not assignable to parameter of type P. P could be instantiated with an arbitrary type which could be unrelated to unknown" on the pageParam argument to queryFn, and hovering over useInfiniteQuery is giving me this inferred type signature:

export function useInfiniteQuery<T, Error, InfiniteData<T, unknown>, unknown[], P>(
  options: UndefinedInitialDataInfiniteOptions<T, Error, InfiniteData<T, unknown>, unknown[], P>, 
  queryClient?: QueryClient,
): UseInfiniteQueryResult<...>

Changing the code to useInfiniteQuery<T, DefaultError, InfiniteData<T, P>, QueryKey, P> is giving me an absolutely massive error about what infiniteQueryOptions is returning (no overload matches this call) about QueryKey. Changing that back to unknown[] just gets me right back to the original pageParam unknown problem.

What am I missing here? It feels like TPageParam isn't getting passed all the way through somewhere.

Edit: tried using OP's method and having the same issue:

const queryOptions: UnusedSkipTokenInfiniteOptions<T, P> = {
  queryKey: queryKey,
  queryFn: ({ pageParam }) => queryFn(pageParam),
  initialPageParam,
  getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam,
};

[karlshea]

Is distributivity not desired for this type? I'm a little hazy on it, but in the playground from @Andarist if I change the type to this (removing the square brackets) I do get the right type on pageParam:

type QueryFunctionContext<TPageParam = never> = TPageParam extends never
  ? { pageParam?: unknown }
  : { pageParam: TPageParam };

[Andarist]

type Test<T> = T extends never ? 1 : 0
type Result = Test<never>
//   ^? type Result = never

A distributive conditional type is applied separately to all union constituents. Then the results are put "back" into a union. never is an empty union (in a sense) so conditional type applied to never... just gives u never back. So yeah, a distributive conditional can't be used here while preserving the original intent

[karlshea]

So it would be breaking something somewhere else, just not this thing in particular?

[karlshea]

And then I guess do you have any suggestions on how I can solve this?

[TkDodo]

I'd have to know more about your use case. Could you wrap it in a self-isolated TS playground that would not depend on React Query types?

I extended your simplified playground a bit to show both useInfiniteQuery and useQuery:

TS Playground

Basically, we have two function: useQuery and useInfiniteQuery. Both have a queryKey and a queryFn, but only the infinite version does some more things with pageParams and the TPageParam type parameter. But they both have a queryFn that receives a context - that context has different values at runtime.

There is nothing to discriminate though, so we tried to infer the correct type of the context by checking the TPageParam type parameter with [TPageParam] extends [never]. You can see that useQuery doesn’t pass the TPageParam type parameter to the QueryFunction type, so the never default is used.