Add a `dataState` enum to `ApolloQueryResult` #12350

jerelmiller · 2025-02-06T22:16:06Z

Adds a new dataState enum returned from ApolloQueryResult that describes the state of the data property. ApolloQueryResult is now a discriminated union that better describes the value of data when in a particular state which provides additional type safety.

This new enum is now able to track whether the is waiting for additional chunks when used with @defer which can be useful to determine whether the full result has streamed in or not.

changeset-bot · 2025-02-06T22:16:09Z

🦋 Changeset detected

Latest commit: 219d890

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@apollo/client	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

svc-apollo-docs · 2025-02-06T22:16:10Z

⚠️ Docs preview not attached to branch

The preview was not built because the PR's base branch release-4.0 is not in the list of sources.

An Apollo team member can comment one of the following commands to dictate which branch to attach the preview to:

!docs set-base-branch version-2.6
!docs set-base-branch main

Build ID: 221b2b08d1fed19c8ab7bee8

pkg-pr-new · 2025-02-06T22:17:05Z

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

commit: 5f6b041

jerelmiller · 2025-02-06T22:17:04Z

src/core/types.ts

+       *  - `complete`: `data` is a fully satisfied query result fulfilled
+       *  either from the cache or network.
+       */
+      dataState: "complete";


Let the bike shedding commence!

netlify · 2025-02-06T22:17:15Z

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	`5f6b041`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/67d34f50984d820008951f1b
😎 Deploy Preview	https://deploy-preview-12350--apollo-client-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2025-02-06T22:17:22Z

size-limit report 📦

Path	Size
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (CJS)	42.24 KB (+0.18% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (production) (CJS)	37.73 KB (+0.23% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client"	32.68 KB (+0.19% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (production)	28.19 KB (+0.24% 🔺)
import { ApolloProvider } from "@apollo/client/react"	5.08 KB (0%)
import { ApolloProvider } from "@apollo/client/react" (production)	965 B (0%)
import { useQuery } from "@apollo/client/react"	7.19 KB (+0.17% 🔺)
import { useQuery } from "@apollo/client/react" (production)	3.07 KB (+0.29% 🔺)
import { useLazyQuery } from "@apollo/client/react"	6.3 KB (+0.19% 🔺)
import { useLazyQuery } from "@apollo/client/react" (production)	2.18 KB (+0.27% 🔺)
import { useMutation } from "@apollo/client/react"	6.37 KB (0%)
import { useMutation } from "@apollo/client/react" (production)	2.22 KB (0%)
import { useSubscription } from "@apollo/client/react"	6.77 KB (0%)
import { useSubscription } from "@apollo/client/react" (production)	2.63 KB (0%)
import { useSuspenseQuery } from "@apollo/client/react"	8.23 KB (0%)
import { useSuspenseQuery } from "@apollo/client/react" (production)	4.12 KB (-0.17% 🔽)
import { useBackgroundQuery } from "@apollo/client/react"	8.07 KB (0%)
import { useBackgroundQuery } from "@apollo/client/react" (production)	3.96 KB (0%)
import { useLoadableQuery } from "@apollo/client/react"	8.12 KB (0%)
import { useLoadableQuery } from "@apollo/client/react" (production)	4.02 KB (0%)
import { useReadQuery } from "@apollo/client/react"	5.74 KB (0%)
import { useReadQuery } from "@apollo/client/react" (production)	1.58 KB (0%)
import { useFragment } from "@apollo/client/react"	5.77 KB (0%)
import { useFragment } from "@apollo/client/react" (production)	1.63 KB (0%)

jerelmiller · 2025-02-06T22:18:37Z

src/core/types.ts

+  | {
+      // Defer to the passed in type to properly type the `@defer` fields.
+      data: T;
+      dataState: "hasNext";


I'm not super in love with this name, but its been difficult to come up with something that doesn't sound the same as partial. The difference here is that partial is meant to describe a partial cache hit where some fields are missing, where hasNext is a @defer query that hasn't fully streamed in the full data set.

Other options considered:

streaming

pending

Maybe deferring ? otherwise streaming would work, but it's slightly harder to make the mental connection to @defer

Hmmm ya this one is tough. Eventually this will need to work with @stream so I suppose streaming fits with that.

waitingForChunks maybe? Really not sure. streaming seems better than deferring to me, pending is often just used synonymous to loading, so I'd avoid that.

jerelmiller · 2025-02-06T22:21:15Z

src/core/types.ts

+    }
+  | {
+      // Defer to the passed in type to properly type the `@defer` fields.
+      data: T;


In the case of hasNext, I've left the T type alone. GraphQL Codegen will generate a type which includes a union on all deferred fields that handles the "missing" holes in the type.

The biggest downside to this is that the complete case also returns the type as-is which means the user will still have to check the deferred fields to ensure they are there to satisfy TypeScript. Ideally we could unwrap that type a bit, but this may prove to be challenging.

I welcome any thoughts here.

Let's wait how this shapes out on the codegen side. This seems fine for now.

jerelmiller · 2025-02-06T22:28:19Z

src/__tests__/dataMasking.ts

+    // Even though `data` didn't change, the `dataStatus` is updated to reflect
+    // that the full result has been stremed in so we expect another render
+    // value.
+    await expect(stream).toEmitApolloQueryResult({


Now that we are reporting the dataStatus enum with a proper value, I think it is necessary to emit another value that reports the dataStatus as complete, even though the data property itself didn't change since the deferred fragment was masked.

jerelmiller · 2025-02-07T21:46:13Z

src/react/hooks/useQuery.ts

@@ -734,9 +736,9 @@ export function toQueryResult<TData, TVariables extends OperationVariables>(
  observable: ObservableQuery<TData, TVariables>,
  client: ApolloClient<object>
 ): InternalQueryResult<TData, TVariables> {
-  const { data, partial, ...resultWithoutPartial } = result;
+  const { data, partial, dataState, ...resultWithoutPartial } = result;


We will expose this property in a separate PR so we can add support for it to all hooks.

phryneas

Generally this looks good, but I'm a bit concerned that we have some code paths that will end up with a hasNext while others will end up with a partial for the same situation, depending if things come from a direct network request or from the cache while a network request is pending nonetheless.

It might even be a good idea to omit the hasNext case until we can guarantee consistency there, what are your thoughts?

phryneas · 2025-03-13T13:15:36Z

src/core/types.ts

+      /**
+       * Describes the completeness of `data`.
+       * - `none`: No data could be fulfilled from the cache or the result is
+       *   incomplete. `data` is `undefined`.
+       * - `partial`: Some data could be fulfilled from the cache but `data` is
+       *   incomplete. This is only possible when `returnPartialData` is `true`.
+       * - `hasNext`: `data` is incomplete as a result of a deferred query and
+       *   the result is still streaming in.
+       *  - `complete`: `data` is a fully satisfied query result fulfilled
+       *  either from the cache or network.
+       */


Use @inheritDoc for the docblock so we have it on all four variants :)

phryneas · 2025-03-13T13:16:35Z

src/core/types.ts

+    }
+  | {
+      // Defer to the passed in type to properly type the `@defer` fields.
+      data: T;


Let's wait how this shapes out on the codegen side. This seems fine for now.

phryneas · 2025-03-13T13:32:31Z

src/core/types.ts

+  | {
+      // Defer to the passed in type to properly type the `@defer` fields.
+      data: T;
+      dataState: "hasNext";


waitingForChunks maybe? Really not sure. streaming seems better than deferring to me, pending is often just used synonymous to loading, so I'd avoid that.

phryneas · 2025-03-13T13:33:37Z

src/core/QueryManager.ts

@@ -823,15 +823,16 @@ export class QueryManager<TStore> {
    return this.fetchQuery<TData, TVars>(queryId, { ...options, query })
      .then(
        (result) =>
-          result && {
+          result &&


Is this truthyness test still necessary?

phryneas · 2025-03-13T13:39:25Z

src/core/QueryManager.ts

-          data: data as TData | undefined,
+        const result = {
+          data,
+          dataState:


This means that streaming (or whatever we'll call it) will be kinda non-deterministic, depending on if this ObservableQuery triggered the query or if it's currently being read & updated from the cache.
Should we add a streaming status at all given that context or wait until we can get this 100% accurate?

This is part of the reason I wanted to add a source property at some point because I think this becomes more obvious what that state. streaming will only ever be emitted from the link observable and that code path doesn't go through fromData/resultsFromCache. This observable value is always the first one emitted, so the link observable will ensure that the proper dataState is set from that point forward.

That said, perhaps I'm misunderstand what you're referring to as non-deterministic?

jerelmiller · 2025-03-13T21:35:32Z

I got this rebased, though I think I want to think this through a bit more before we merge it. I think there is more opportunity for optimization here. For example, client.query(...) should never have a streaming or partial result, so we are unnecessarily forcing end users to perform a check against dataState before that data is usable.

jerelmiller commented Feb 6, 2025

View reviewed changes

jerelmiller requested a review from phryneas February 6, 2025 22:28

jerelmiller marked this pull request as ready for review February 6, 2025 22:29

jerelmiller force-pushed the jerel/status-enum branch from d04f0bf to e05d975 Compare February 7, 2025 21:43

jerelmiller commented Feb 7, 2025

View reviewed changes

jerelmiller mentioned this pull request Mar 6, 2025

Deprecate partial and ensure its correctness. Fix type of data in ApolloQueryResult #12333

Merged

phryneas reviewed Mar 13, 2025

View reviewed changes

jerelmiller added 15 commits March 13, 2025 13:57

Make ApolloQueryResult a union with a dataStatus enum.

e4a3a21

Add dataState to result returned from fetchQueryByPolicy

f81bb3e

Mark dataState from result in link

f6e2ebd

Remove union for now

e0da506

Remove anys

32d7f0b

Set dataState in getCurrentResult

26e02c8

Update all ObservableQuery tests to check for dataState

9b67244

Fix bugs related to incorrect behavior found in updated tests

c2d4a20

Update ApolloClient/general tests to check for dataState

98c747b

Fix dataState with cache-only and partial data

c86610e

Check for dataState in multiple-results tests

7fce831

Check for dataState in fetchMore tests

f404e49

Update client tests to check for dataState

e6fbc3e

Update refetchQueries tests to check for dataState

7a3cd7b

Update local-state tests to check for dataState

30eeb24

jerelmiller added 13 commits March 13, 2025 14:41

Update type of ApolloQueryResult back to union

862223d

Update fetchMore tests to assert on dataState

f17837b

Update ApolloClient type tests to check dataState and data

acacf2b

Use invariant to check for dataState in dataMasking tests

2954ed2

Check for dataState in mutationResults

3bebda3

Update type tests in useBackgroundQuery to check for data state

eb39c95

Use some necessary type casts

ea130d2

Update type tests for useLazyQuery

f046290

Update type tests for useSuspenseQuery

abfad14

Add some necessary type casts

9844cbd

Minor type manipulation

ab29302

Update behavior in data masking test

3d62c47

Add changeset

f4d6f53

jerelmiller force-pushed the jerel/status-enum branch from e05d975 to f4d6f53 Compare March 13, 2025 20:51

jerelmiller added 15 commits March 13, 2025 14:53

Update remaining client tests after rebase

8a2e923

Update remaining dataMasking tests after rebase

69416af

Add dataState to initial result in ObservableQuery

0ad8a80

Add dataState to remaining local-state/general tests after rebase

02f134c

Add dataState to remaining refetchQueries tests after rebase

d303032

Add type cast

38feb75

Update remaining ApolloClient/general tests after rebase

efb668e

Update multiple-results tests after rebase

82152de

Update fetchPolicies tests after rebase

8452608

Update useLazyQuery after rebase

b06a7df

Fix ts issues in useLazyQuery

290b933

Rerun api report

a9c6e6c

Update size limits

219d890

Rename hasNext to streaming

75d54ee

Remove unneeded optional chaining

5f6b041

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a `dataState` enum to `ApolloQueryResult` #12350

Add a `dataState` enum to `ApolloQueryResult` #12350

jerelmiller commented Feb 6, 2025 •

edited

Loading

changeset-bot bot commented Feb 6, 2025 •

edited

Loading

svc-apollo-docs commented Feb 6, 2025 •

edited

Loading

pkg-pr-new bot commented Feb 6, 2025 •

edited

Loading

jerelmiller Feb 6, 2025

netlify bot commented Feb 6, 2025 •

edited

Loading

github-actions bot commented Feb 6, 2025 •

edited

Loading

jerelmiller Feb 6, 2025

PowerKiKi Mar 7, 2025

jerelmiller Mar 7, 2025

phryneas Mar 13, 2025

jerelmiller Feb 6, 2025

phryneas Mar 13, 2025

jerelmiller Feb 6, 2025

jerelmiller Feb 7, 2025

phryneas left a comment

phryneas Mar 13, 2025

phryneas Mar 13, 2025

phryneas Mar 13, 2025

phryneas Mar 13, 2025

phryneas Mar 13, 2025

jerelmiller Mar 13, 2025

jerelmiller commented Mar 13, 2025

Add a dataState enum to ApolloQueryResult #12350

Are you sure you want to change the base?

Add a dataState enum to ApolloQueryResult #12350

Conversation

jerelmiller commented Feb 6, 2025 • edited Loading

changeset-bot bot commented Feb 6, 2025 • edited Loading

🦋 Changeset detected

svc-apollo-docs commented Feb 6, 2025 • edited Loading

⚠️ Docs preview not attached to branch

pkg-pr-new bot commented Feb 6, 2025 • edited Loading

Choose a reason for hiding this comment

netlify bot commented Feb 6, 2025 • edited Loading

✅ Deploy Preview for apollo-client-docs ready!

github-actions bot commented Feb 6, 2025 • edited Loading

size-limit report 📦

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phryneas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jerelmiller commented Mar 13, 2025

Add a `dataState` enum to `ApolloQueryResult` #12350

Add a `dataState` enum to `ApolloQueryResult` #12350

jerelmiller commented Feb 6, 2025 •

edited

Loading

changeset-bot bot commented Feb 6, 2025 •

edited

Loading

svc-apollo-docs commented Feb 6, 2025 •

edited

Loading

pkg-pr-new bot commented Feb 6, 2025 •

edited

Loading

netlify bot commented Feb 6, 2025 •

edited

Loading

github-actions bot commented Feb 6, 2025 •

edited

Loading