useInfiniteQuery types are unsafe: required pagination options (e.g. getNextPageParam) not enforced due to recursive types

[minchodang]

openapi-react-query version

0.5.0

Description

Summary
useInfiniteQuery has a type-safety hole: due to recursive/overly-broad types, required pagination options (notably getNextPageParam) are not enforced by TypeScript. Calls compile successfully even when getNextPageParam is omitted, leading to runtime breakage and loss of inference for page params.

Package version
openapi-react-query: 0.5.0
TypeScript: 5.x
@tanstack/react-query: 5.x

Reproduction

Reproduction

// Minimal example (shape representative; any endpoint works)
type Page = { items: string[]; nextCursor?: string }

const q = api.examples.list.useInfiniteQuery(
{ limit: 10 },
{
initialPageParam: undefined,
// ❌ getNextPageParam is omitted but compiles fine
// expected: TS error requiring getNextPageParam
}
)

Alternatively, using the generator’s raw hook:

useInfiniteQuery({
queryKey: ['examples'],
queryFn: ({ pageParam }) => fetchPage(pageParam),
initialPageParam: undefined,
// ❌ getNextPageParam missing; still no TS error
})

Actual behavior
• The call type-checks without getNextPageParam.
• pageParam/pagination inference degrades (often widens to unknown/any).
• Runtime pagination helpers (fetchNextPage) can break due to the missing extractor.

Expected result

Expected behavior
• TypeScript should require getNextPageParam (and, where applicable, a compatible initialPageParam) for useInfiniteQuery.
• Correct inference for TPageParam/page types should be preserved.

Root cause (analysis)
The exported types for useInfiniteQuery/its options use recursive/conditional composition that widens option shapes. In practice, the recursion (and/or distributive conditionals) makes getNextPageParam effectively optional even when it should be required, and it weakens generic inference for TPageParam.

Proposed fix
• Break the recursion and require pagination options explicitly at the top level, e.g.:
• Define a non-recursive InfiniteOptionsRequired<TPageParam, TData, TError> and intersect it with the base options, or
• Provide an overload where getNextPageParam is Required<...> when useInfiniteQuery is selected, or
• Apply a RequiredBy<Options, 'getNextPageParam'> after composing the options to avoid conditional widening.
• Add tsd (or equivalent) tests asserting a compile-time error when getNextPageParam is omitted.

Status
I have a patch locally and will open a PR shortly.

Additional context
The goal is to match TanStack’s infinite-query semantics while preserving strict typing for pageParam and preventing silent runtime failures.

Extra

• I’m willing to open a PR (see CONTRIBUTING.md)