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.

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 added 4 commits May 13, 2024 13:44

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

X-oss-byte mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.7.17 to 3.10.4 X-oss-byte/next.js#1218

Open

shonore mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.3.19 to 3.10.4 shonore/Fickle#1456

Open

Denismyand mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.10.1 to 3.10.4 Denismyand/rick-and-morty#4

Open

arddluma mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.8.7 to 3.10.4 etherspot/etherspot-prime-sdk#128

Closed

NOUIY mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.1.1 to 3.10.4 NOUIY/next.js#2210

Open

nejidevelops mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.7.7 to 3.10.4 nejidevelops/intern#18

Open

iamsatyanchal mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.5.8 to 3.10.4 iamsatyanchal/CoinCoin#112

Open

NOUIY mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.3.11 to 3.10.4 NOUIY/next.js#2211

Open

GregBrimble mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.0.0-beta.44 to 3.10.4 GregBrimble/workers.sh#566

Open

peterleiva mentioned this pull request Jun 5, 2024

[Snyk] Upgrade @apollo/client from 3.5.10 to 3.10.4 peterleiva/community-client#232

Open

basilisSam mentioned this pull request Jun 6, 2024

[Snyk] Upgrade @apollo/client from 3.5.10 to 3.10.4 basilisSam/Github-Issues#309

Open

shonore mentioned this pull request Jun 6, 2024

[Snyk] Upgrade @apollo/client from 3.3.19 to 3.10.4 shonore/Fickle#1461

Open

MartinWitt mentioned this pull request Jun 6, 2024

[Snyk] Upgrade @apollo/client from 3.10.3 to 3.10.4 MartinWitt/laughing-train#1809

Open

X-oss-byte mentioned this pull request Jun 6, 2024

[Snyk] Upgrade @apollo/client from 3.3.11 to 3.10.4 X-oss-byte/next.js#1219

Open

This was referenced Jun 6, 2024

[Snyk] Upgrade @apollo/client from 3.3.19 to 3.10.4 shonore/Fickle#1466

Open

[Snyk] Upgrade @apollo/client from 3.3.19 to 3.10.4 shonore/Fickle#1471

Open

[Snyk] Upgrade @apollo/client from 3.3.19 to 3.10.4 shonore/Fickle#1476

Open

sandermendes mentioned this pull request Jun 8, 2024

[Snyk] Upgrade @apollo/client from 3.7.17 to 3.10.4 sandermendes/Project-001#307

Open

github-actions bot locked as resolved and limited conversation to collaborators Jun 13, 2024

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

Loading

changeset-bot bot commented May 2, 2024 •

edited

Loading

github-actions bot commented May 2, 2024 •

edited

Loading

netlify bot commented May 2, 2024 •

edited

Loading

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

Loading

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

Loading

phryneas commented May 8, 2024

create branded QueryRef type without exposed properties #11824

create branded QueryRef type without exposed properties #11824

Conversation

phryneas commented May 2, 2024 • edited Loading

changeset-bot bot commented May 2, 2024 • edited Loading

🦋 Changeset detected

github-actions bot commented May 2, 2024 • edited Loading

size-limit report 📦

netlify bot commented May 2, 2024 • edited Loading

✅ 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 Loading

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 Loading

Choose a reason for hiding this comment

phryneas commented May 8, 2024

create branded `QueryRef` type without exposed properties #11824

create branded `QueryRef` type without exposed properties #11824

phryneas commented May 2, 2024 •

edited

Loading

changeset-bot bot commented May 2, 2024 •

edited

Loading

github-actions bot commented May 2, 2024 •

edited

Loading

netlify bot commented May 2, 2024 •

edited

Loading

phryneas May 3, 2024 •

edited

Loading

phryneas May 7, 2024 •

edited

Loading