modern useQuery: dataState includes "partial" for complex TVariables even when returnPartialData is false

[oceandrama]

Issue Description

With modern hook signatures (TypeOverrides.signatureStyle: "modern"), useQuery incorrectly includes dataState: "partial" (and therefore DeepPartial<TData> for data) when TVariables is a large / complex input object — even if returnPartialData is omitted or set to the literal false.

With a small TVariables type, the same call correctly yields "complete" | "empty" | "streaming" only.

This matches the docs expectation that "partial" / DeepPartial should only appear when returnPartialData is enabled:
https://www.apollographql.com/docs/react/data/typescript#type-narrowing-data-with-datastate

Link to Reproduction

CodeSandbox (node template, @apollo/client@4.2.6): https://codesandbox.io/p/sandbox/fp82hz

Gist: https://gist.github.com/oceandrama/436975fa619df9b807195dcbae4f0894

npm i
npm run typecheck

simpleVars typechecks; complexVars fails with dataState including "partial" despite returnPartialData: false.

Note: TypeScript Playground ATA often fails to acquire @apollo/client types (complex package exports / peers), so prefer CodeSandbox/gist above.

Reproduction Steps

1. Enable modern signatures via TypeOverrides.signatureStyle: "modern".
2. Call useQuery with a TypedDocumentNode whose variables include a large optional input object (many nested optional fields), similar to a real GraphQL INPUT_OBJECT.
3. Inspect dataState (e.g. with satisfies).
4. Observe that "partial" is present even with returnPartialData: false.
5. Compare with the same setup using a small variables type — "partial" is absent.

Suspected cause

In useQuery.ResultForOptions, "partial" is included unless:

OptionWithFallback<TOptions, DefaultOptions, "returnPartialData"> extends false

With complex TVariables, TypeScript appears to fail to keep a narrow inferred TOptions and falls back toward the full useQuery.Options constraint, where returnPartialData?: boolean. Then boolean extends false is false, so "partial" is always added.

Relevant sources (@apollo/client@4.2.6):

• react/hooks/useQuery.d.ts — ResultForOptions / modern overload with circular TOptions extends Options & VariablesOption<...>
• utilities/internal/types/OptionWithFallback.d.ts

A more default-safe check would be closer to extends true ? "partial" : never (only add "partial" when the option is known to be true). Tradeoff: a dynamic boolean flag would then be typed optimistically.

This is not specific to gql.tada / codegen — the same happens with a hand-written TypedDocumentNode and a large variables type.

@apollo/client version

4.2.6

[oceandrama]

Related: #13285 — same area (modern signatures + OptionWithFallback / inferred TOptions), different symptom (error widens when a complex optimisticResponse is present). Both look like inference falling back toward a wider options type so the conditional no longer sees a concrete default (false / "none").

[jerelmiller]

Hey @oceandrama 👋

It looks like its less to do with a large object and more to do with a constant string in the variables type. I can reproduce with the following minimal setup as well:

type Data = {
  dam: {
    directories: string[]
  }
};
type Vars = { join: "AND" };
declare const QUERY: TypedDocumentNode<Data, Vars>;

const { data, dataState } = useQuery(QUERY, {
  variables: { join: "AND" },
  // Even an explicit literal false does not remove "partial" in this case:
  returnPartialData: false,
});

// ❌ Actual: includes "partial"
// ✅ Expected: "complete" | "empty" | "streaming"
dataState satisfies "complete" | "empty" | "streaming";

// ❌ data remains DeepPartial-ish; nested fields become optional
if (data) {
  data.dam.directories satisfies string[];
}

(link to see for yourself: https://tsplay.dev/mbJ4Bm)

I'll dig in a bit further to see why that is tripping everything up. Replacing that constant "AND" with string works as intended 🤷‍♂️. I'll see if I can find a fix that works here. Thanks!

[jerelmiller]

I've got a fix in a PR specifically for useQuery that should handle this. Looks like we might have this issue for other hooks as well as other options that might affect the data state (errorPolicy, etc). I'd like to take it to the team before committing to this direction, but in the meantime if you'd like to try it, you can install the PR build:

npm i https://pkg.pr.new/@apollo/client@13352

If you wouldn't mind trying that out, I'd be grateful to make sure you don't see any other regressions with useQuery with this direction 🙏. Thanks!

[oceandrama]

Confirmed on our app with signatureStyle: "modern":

• @apollo/client@4.2.7 — typecheck fails with DeepPartial / possibly 'undefined' on nested useQuery / useSuspenseQuery data (same as this issue)
• https://pkg.pr.new/@apollo/client@13352 — typecheck passes cleanly with modern signatures enabled

So the fix in #13352 looks good for our real queries (complex variables / input objects). Thanks!

[jerelmiller]

Great to know! Thanks!