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: e05d975

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: 24473761fccaba737abe8ceb

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

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

commit: e05d975

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	`e05d975`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/67a67e9ec9f42000086081b8
😎 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
dist/apollo-client.min.cjs	33.55 KB (+0.22% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	41.51 KB (+0.2% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	38.81 KB (+0.2% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	36.24 KB (+0.24% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	33.64 KB (+0.23% 🔺)
import { ApolloProvider } from "dist/react/index.js"	1.26 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.24 KB (0%)
import { useQuery } from "dist/react/index.js"	5.18 KB (+0.86% 🔺)
import { useQuery } from "dist/react/index.js" (production)	4.26 KB (+0.86% 🔺)
import { useLazyQuery } from "dist/react/index.js"	5.65 KB (+0.54% 🔺)
import { useLazyQuery } from "dist/react/index.js" (production)	4.73 KB (+0.71% 🔺)
import { useMutation } from "dist/react/index.js"	3.62 KB (0%)
import { useMutation } from "dist/react/index.js" (production)	2.84 KB (0%)
import { useSubscription } from "dist/react/index.js"	4.45 KB (+0.23% 🔺)
import { useSubscription } from "dist/react/index.js" (production)	3.5 KB (+0.37% 🔺)
import { useSuspenseQuery } from "dist/react/index.js"	5.52 KB (-0.08% 🔽)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.18 KB (-0.08% 🔽)
import { useBackgroundQuery } from "dist/react/index.js"	5 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js" (production)	3.65 KB (0%)
import { useLoadableQuery } from "dist/react/index.js"	5.08 KB (0%)
import { useLoadableQuery } from "dist/react/index.js" (production)	3.73 KB (0%)
import { useReadQuery } from "dist/react/index.js"	3.4 KB (0%)
import { useReadQuery } from "dist/react/index.js" (production)	3.35 KB (0%)
import { useFragment } from "dist/react/index.js"	2.01 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	1.95 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

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.

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.

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 added 19 commits February 7, 2025 14:41

Make ApolloQueryResult a union with a dataStatus enum.

1b53b61

Add dataState to result returned from fetchQueryByPolicy

cc414e9

Mark dataState from result in link

3a9a40f

Remove union for now

8514df9

Remove anys

f750adc

Set dataState in getCurrentResult

7108f7e

Update all ObservableQuery tests to check for dataState

0e6d661

Fix bugs related to incorrect behavior found in updated tests

5e5b00f

Update ApolloClient/general tests to check for dataState

cbed014

Fix dataState with cache-only and partial data

13d4428

Check for dataState in multiple-results tests

e1fad85

Check for dataState in fetchMore tests

15d9bd2

Update client tests to check for dataState

653975f

Update refetchQueries tests to check for dataState

0fba6a3

Update local-state tests to check for dataState

4b9b041

Update subscribeToMore tests to check for dataState

86effde

Update updated APIs in a data masking test

d02ac92

Update fetchPolicies tests to check for dataState

f02c996

Update cache tests to check for dataState

5f621ff

jerelmiller added 16 commits February 7, 2025 14:41

Don't set dataState in useQuery

bd702d2

Update react tests to check for dataState

185cc25

Update type of ApolloQueryResult back to union

dfa5cc4

Update fetchMore tests to assert on dataState

9a5c843

Update ApolloClient type tests to check dataState and data

c730b6e

Use invariant to check for dataState in dataMasking tests

f2332a6

Switch to toEmitValue

aee1f0c

Check for dataState in mutationResults

c6367a7

Update type tests in useBackgroundQuery to check for data state

c3be1f1

Use some necessary type casts

96ffc78

Update type tests for useLazyQuery

c88bd79

Update type tests for useSuspenseQuery

dc20ddc

Add some necessary type casts

8df4a86

Minor type manipulation

7117e81

Update behavior in data masking test

57b1b3b

Add changeset

e05d975

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

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

jerelmiller Feb 6, 2025

jerelmiller Feb 6, 2025

jerelmiller Feb 7, 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

jerelmiller Feb 6, 2025

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 📦

jerelmiller Feb 6, 2025

Choose a reason for hiding this comment

jerelmiller Feb 6, 2025

Choose a reason for hiding this comment

jerelmiller Feb 6, 2025

Choose a reason for hiding this comment

jerelmiller Feb 7, 2025

Choose a reason for hiding this comment

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