create branded `QueryRef` type without exposed properties #11824

phryneas · 2024-05-02T16:01:26Z

Create branded QueryRef type without exposed properties.

This change deprecates QueryReference in favor of a QueryRef type that doesn't expose any properties.
This change also updates preloadQuery to return a new PreloadedQueryRef type, which exposes the toPromise function as it does today. This means that query refs produced by useBackgroundQuery and useLoadableQuery now return QueryRef types that do not have access to a toPromise function, which was never meant to be used in combination with these hooks.

While we tend to avoid any types of breaking changes in patch releases as this, this change was necessary to support an upcoming version of the React Server Component integration, which needed to omit the toPromise function that would otherwise have broken at runtime.
Note that this is a TypeScript-only change. At runtime, toPromise is still present on all queryRefs currently created by this package - but we strongly want to discourage you from accessing it in all cases except for the PreloadedQueryRef use case.

Migration is as simple as replacing all references to QueryReference with QueryRef, so it should be possible to do this with a search & replace in most code bases:

-import { QueryReference } from '@apollo/client'
+import { QueryRef } from '@apollo/client'

- function Component({ queryRef }: { queryRef: QueryReference<TData> }) {
+ function Component({ queryRef }: { queryRef: QueryRef<TData> }) {
  // ...
}

changeset-bot · 2024-05-02T16:01:30Z

🦋 Changeset detected

Latest commit: acc9ba9

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	Patch

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

github-actions · 2024-05-02T16:02:41Z

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	38.65 KB (+0.1% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	47.06 KB (+1.22% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	44.68 KB (+1.45% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	34.17 KB (+0.01% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	32.06 KB (+0.01% 🔺)
import { ApolloProvider } from "dist/react/index.js"	1.23 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.22 KB (0%)
import { useQuery } from "dist/react/index.js"	5.28 KB (0%)
import { useQuery } from "dist/react/index.js" (production)	4.36 KB (-0.03% 🔽)
import { useLazyQuery } from "dist/react/index.js"	5.52 KB (0%)
import { useLazyQuery } from "dist/react/index.js" (production)	4.59 KB (-0.03% 🔽)
import { useMutation } from "dist/react/index.js"	3.52 KB (0%)
import { useMutation } from "dist/react/index.js" (production)	2.74 KB (0%)
import { useSubscription } from "dist/react/index.js"	3.21 KB (-0.07% 🔽)
import { useSubscription } from "dist/react/index.js" (production)	2.4 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js"	5.44 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.1 KB (+0.03% 🔺)
import { useBackgroundQuery } from "dist/react/index.js"	4.96 KB (-0.06% 🔽)
import { useBackgroundQuery } from "dist/react/index.js" (production)	3.61 KB (0%)
import { useLoadableQuery } from "dist/react/index.js"	5.07 KB (+0.49% 🔺)
import { useLoadableQuery } from "dist/react/index.js" (production)	3.72 KB (+0.45% 🔺)
import { useReadQuery } from "dist/react/index.js"	3.33 KB (+0.57% 🔺)
import { useReadQuery } from "dist/react/index.js" (production)	3.27 KB (+0.61% 🔺)
import { useFragment } from "dist/react/index.js"	2.29 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	2.23 KB (0%)

netlify · 2024-05-02T16:06:59Z

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	`acc9ba9`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/664209c7afd94d0008083e48
😎 Deploy Preview	https://deploy-preview-11824--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.

phryneas · 2024-05-03T09:43:02Z

/release:pr

github-actions · 2024-05-03T09:43:36Z

Please add a changeset via npx changeset before attempting a snapshot release.

phryneas · 2024-05-03T10:02:26Z

/release:pr

github-actions · 2024-05-03T10:03:31Z

A new release has been made for this PR. You can install it with:

npm i @apollo/client@0.0.0-pr-11824-20240503100254

phryneas · 2024-05-03T12:27:31Z

src/react/internal/cache/QueryReference.ts

+export interface QueryReferenceBase<TData = unknown, TVariables = unknown> {
+  /** @internal */
+  [QUERY_REF_BRAND]?(variables: TVariables): TData;
+}

 /**
 * A `QueryReference` is an opaque object returned by `useBackgroundQuery`.
 * A child component reading the `QueryReference` via `useReadQuery` will
 * suspend until the promise resolves.
 */
-export interface QueryReference<TData = unknown, TVariables = unknown> {
+export interface QueryReference<TData = unknown, TVariables = unknown>
+  extends QueryReferenceBase<TData, TVariables> {


I'm a bit unhappy with a new QueryReferenceBase type here tbh., this should be the QueryReference type, and useBackgroundQuery and QueryPreloader should return two distinct types, where the toPromise callback should only be exposed on the QueryPreloader return value - it only makes sense there.

It's kinda breaking, but might be a consideration sooner rather than later @jerelmiller WDYT?

Let me take the weekend to think about this.

I'm in the same boat. If we can avoid the QueryReferenceBase type, I would love that, but I can definitely understand why we might need it.

phryneas · 2024-05-07T14:35:44Z

/release:pr

github-actions · 2024-05-07T14:36:41Z

A new release has been made for this PR. You can install it with:

npm i @apollo/client@3.10.2

phryneas · 2024-05-07T14:56:03Z

/release:pr

github-actions · 2024-05-07T14:57:03Z

A new release has been made for this PR. You can install it with:

npm i @apollo/client@3.10.2

phryneas · 2024-05-08T09:32:52Z

/release:pr

github-actions · 2024-05-08T09:34:03Z

A new release has been made for this PR. You can install it with:

npm i @apollo/client@0.0.0-pr-11824-20240508093324

phryneas · 2024-05-07T14:07:46Z

.api-reports/api-report.md

-// @public (undocumented)
-class InternalQueryReference<TData = unknown> {
-    // Warning: (ae-forgotten-export) The symbol "InternalQueryReferenceOptions" needs to be exported by the entry point index.d.ts


These internal types are now no longer exposed 🎉

phryneas · 2024-05-07T14:10:32Z

src/react/hooks/__tests__/useBackgroundQuery.test.tsx

+    expectTypeOf(inferredQueryRef).toMatchTypeOf<
      QueryReference<VariablesCaseData, VariablesCaseVariables> | undefined
    >();


ensuring similarity to the old QueryReference type

phryneas · 2024-05-07T14:12:54Z

src/react/hooks/useLoadableQuery.ts

    TData,
    TVariables
  > | null>(null);

+  assertWrappedQueryRef(queryRef);


additional assertion to make sure that a potential wrapper converted the QueryRef into a WrappedQueryRef correctly

phryneas · 2024-05-07T14:13:54Z

src/react/internal/cache/QueryReference.ts

@@ -27,17 +28,51 @@ type FetchMoreOptions<TData> = Parameters<

 const QUERY_REFERENCE_SYMBOL: unique symbol = Symbol();
 const PROMISE_SYMBOL: unique symbol = Symbol();
-
+declare const QUERY_REF_BRAND: unique symbol;


this exists only on type level

phryneas · 2024-05-07T14:14:44Z

src/react/internal/cache/QueryReference.ts

-export interface QueryReference<TData = unknown, TVariables = unknown> {
+export interface QueryRef<TData = unknown, TVariables = unknown> {
+  /** @internal */
+  [QUERY_REF_BRAND]?(variables: TVariables): TData;


using a function signature to capture the generics on this type

this was a bit too loose for TVariables previously

phryneas · 2024-05-07T14:17:04Z

src/react/internal/cache/QueryReference.ts

+   *
+   * {@inheritDoc @apollo/client!PreloadedQueryRef#toPromise:member(1)}
+   */
+  toPromise?: unknown;


This is kinda breaking, but will only break when calling toPromise on this type - but otherwise it ensures that this type and QueryRef can be assigned to each other, which is more important for backwards compat.

phryneas · 2024-05-07T14:25:51Z

src/react/internal/cache/QueryReference.ts

+ * @internal
+ * For usage in internal helpers only.
+ */
+interface WrappedQueryRef<TData = unknown, TVariables = unknown>


This is now a purely internal type (not even exported, thanks to assertWrappedQueryRef), which removes type references to all kinds of internals from the api surface

phryneas · 2024-05-08T12:21:31Z

Digging into that (unrelated) test failure, but already opening this for review.

phryneas · 2024-05-08T12:38:43Z

src/react/hooks/__tests__/useQuery.test.tsx

@@ -4465,7 +4465,7 @@ describe("useQuery Hook", () => {
              primes: [13, 17, 19, 23, 29],
            },
          },
-          delay: 10,
+          delay: 25,


This was a flaky test, this should stabilize it.

jerelmiller

This change looks great! I'm happy with the end result.

The only feedback I have is just to ensure we are providing a bit more info on the change in the changelog entry, but I've got no other feedback on the main changes. Thanks for this!

jerelmiller · 2024-05-08T22:18:34Z

.changeset/late-planets-argue.md

Can we perhaps add a small code snippet in here that demonstrates how to migrate from one to the other?

.changeset/late-planets-argue.md

src/react/internal/cache/__tests__/QueryReference.test.tsx

Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

create branded QueryReferenceBase type

9ab7015

update some test types

60b9e2d

changeset

14359b6

phryneas commented May 3, 2024

View reviewed changes

phryneas added 2 commits May 6, 2024 16:46

Merge branch 'main' into pr/queryRefBase

fb08336

split up into new hierarchy starting from QueryRef type

dbe4b6b

phryneas changed the title ~~create branded QueryReferenceBase type~~ create branded QueryRef type without exposed properties May 7, 2024

phryneas added 5 commits May 7, 2024 15:18

add export

f5da588

add some type assignability tests

6009ce3

update doc references

5c27e08

toPromise return type

7a1c222

adjust changeset

40bef55

Merge branch 'main' into pr/queryRefBase

6524aee

phryneas commented May 8, 2024

View reviewed changes

Merge branch 'main' into pr/queryRefBase

2a710dd

phryneas marked this pull request as ready for review May 8, 2024 12:21

phryneas requested a review from a team as a code owner May 8, 2024 12:21

stabilize flaky test

3256f0d

phryneas mentioned this pull request May 8, 2024

RSC preloading mechanism apollographql/apollo-client-nextjs#258

Merged

phryneas requested a review from jerelmiller May 8, 2024 12:36

phryneas commented May 8, 2024

View reviewed changes

jerelmiller approved these changes May 8, 2024

View reviewed changes

github-actions bot added the auto-cleanup 🤖 label May 8, 2024

phryneas and others added 8 commits May 13, 2024 11:53

Update .changeset/late-planets-argue.md

b1945e9

Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

types in tests

0a134e8

adjust notes

92ffc58

fix integration test TS?

193e539

fix integration test TS?

b36c633

fix integration test TS?

f73026f

fix integration test TS?

c20cd4f

Merge branch 'main' into pr/queryRefBase

acc9ba9

phryneas merged commit 47ad806 into main May 13, 2024
39 checks passed

phryneas deleted the pr/queryRefBase branch May 13, 2024 12:48

github-actions bot mentioned this pull request May 13, 2024

Version Packages #11843

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

create branded `QueryRef` type without exposed properties #11824

create branded `QueryRef` type without exposed properties #11824

phryneas commented May 2, 2024 •

edited

changeset-bot bot commented May 2, 2024 •

edited

github-actions bot commented May 2, 2024 •

edited

netlify bot commented May 2, 2024 •

edited

phryneas commented May 3, 2024

github-actions bot commented May 3, 2024

phryneas commented May 3, 2024

github-actions bot commented May 3, 2024

phryneas May 3, 2024 •

edited

jerelmiller May 3, 2024

phryneas commented May 7, 2024

github-actions bot commented May 7, 2024

phryneas commented May 7, 2024

github-actions bot commented May 7, 2024

phryneas commented May 8, 2024

github-actions bot commented May 8, 2024

phryneas May 7, 2024

phryneas May 7, 2024

phryneas May 7, 2024

phryneas May 7, 2024

phryneas May 7, 2024

phryneas May 7, 2024

phryneas May 7, 2024

phryneas May 7, 2024 •

edited

phryneas commented May 8, 2024

phryneas May 8, 2024

jerelmiller left a comment

jerelmiller May 8, 2024

phryneas May 13, 2024

create branded QueryRef type without exposed properties #11824

create branded QueryRef type without exposed properties #11824

Conversation

phryneas commented May 2, 2024 • edited

changeset-bot bot commented May 2, 2024 • edited

🦋 Changeset detected

github-actions bot commented May 2, 2024 • edited

size-limit report 📦

netlify bot commented May 2, 2024 • edited

✅ Deploy Preview for apollo-client-docs ready!

phryneas commented May 3, 2024

github-actions bot commented May 3, 2024

phryneas commented May 3, 2024

github-actions bot commented May 3, 2024

phryneas May 3, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phryneas commented May 7, 2024

github-actions bot commented May 7, 2024

phryneas commented May 7, 2024

github-actions bot commented May 7, 2024

phryneas commented May 8, 2024

github-actions bot commented May 8, 2024

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 May 7, 2024 • edited

Choose a reason for hiding this comment

phryneas commented May 8, 2024

Choose a reason for hiding this comment

jerelmiller left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

create branded `QueryRef` type without exposed properties #11824

create branded `QueryRef` type without exposed properties #11824

phryneas commented May 2, 2024 •

edited

changeset-bot bot commented May 2, 2024 •

edited

github-actions bot commented May 2, 2024 •

edited

netlify bot commented May 2, 2024 •

edited

phryneas May 3, 2024 •

edited

phryneas May 7, 2024 •

edited