create branded `QueryRef` type without exposed properties

[phryneas]

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[bot]]

🦋 Changeset detected

Latest commit: acc9ba9b162556ad1524391dc1ff9527280050fb

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[bot]]

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[bot]]

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	acc9ba9b162556ad1524391dc1ff9527280050fb
🔍 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]

/release:pr

[github-actions[bot]]

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

[phryneas]

/release:pr

[github-actions[bot]]

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]

/release:pr

[github-actions[bot]]

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

npm i @apollo/client@3.10.2

[phryneas]

/release:pr

[github-actions[bot]]

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

npm i @apollo/client@3.10.2

[phryneas]

/release:pr

[github-actions[bot]]

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]

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