Adds support for skipToken in options for useSuspenseQuery and useBackgroundQuery and soft deprecates skip option

.changeset/early-days-stare.md

@@ -0,0 +1,50 @@
+---
+'@apollo/client': minor
+---
+
+Adds support for a `skipToken` sentinel that can be used as `options` in `useSuspenseQuery` and `useBackgroundQuery` to skip execution of a query. This works identically to the `skip` option but is more type-safe and as such, becomes the recommended way to skip query execution. As such, the `skip` option has been deprecated in favor of `skipToken`.
+
+```ts
+import { skipToken } from '@apollo/client';
+
+const id: number | undefined;
+
+const { data } = useSuspenseQuery(
+  query, 
+  id ? { variables: { id } } : skipToken
+);
+```
+
+### Breaking change
+
+Previously `useBackgroundQuery` would always return a `queryRef` whenever query execution was skipped. This behavior been updated to return a `queryRef` only when query execution is enabled. If initializing the hook with it skipped, `queryRef` is now returned as `undefined`.
+
+To migrate, conditionally render the component that accepts the `queryRef` as props.
+
+**Before**
+```ts
+function Parent() {
+  const [queryRef] = useBackgroundQuery(query, skip ? skipToken : undefined);
+  //      ^? QueryReference<TData | undefined>
+
+  return <Child queryRef={queryRef} />
+}
+
+function Child({ queryRef }: { queryRef: QueryReference<TData | undefined> }) {
+  const { data } = useReadQuery(queryRef);
+}
+```
+
+**After**
+```ts
+function Parent() {
+  const [queryRef] = useBackgroundQuery(query, skip ? skipToken : undefined);
+  //      ^? QueryReference<TData> | undefined
+
+  return queryRef ? <Child queryRef={queryRef} /> : null;
+}
+
+function Child({ queryRef }: { queryRef: QueryReference<TData> }) {
+  const { data } = useReadQuery(queryRef);
+}
+```

.prettierignore

@@ -96,6 +96,8 @@ src/react/hooks/*
 !src/react/hooks/useSuspenseCache.ts
 !src/react/hooks/useSuspenseQuery.ts
 !src/react/hooks/useBackgroundQuery.ts
+!src/react/hooks/useReadQuery.ts
+!src/react/hooks/constants.ts
 
 ## Allowed React hook tests
 !src/react/hooks/__tests__/

src/__tests__/__snapshots__/exports.ts.snap

@@ -52,6 +52,7 @@ Array [
   "selectURI",
   "serializeFetchParameter",
   "setLogVerbosity",
+  "skipToken",
   "split",
   "throwServerError",
   "toPromise",
@@ -270,6 +271,7 @@ Array [
   "operationName",
   "parser",
   "resetApolloContext",
+  "skipToken",
   "useApolloClient",
   "useBackgroundQuery",
   "useFragment",
@@ -312,6 +314,7 @@ Array [
 
 exports[`exports of public entry points @apollo/client/react/hooks 1`] = `
 Array [
+  "skipToken",
   "useApolloClient",
   "useBackgroundQuery",
   "useFragment",

src/react/cache/QueryReference.ts

@@ -21,7 +21,7 @@ type FetchMoreOptions<TData> = Parameters<
   ObservableQuery<TData>['fetchMore']
 >[0];
 
-export const QUERY_REFERENCE_SYMBOL: unique symbol = Symbol();
+const QUERY_REFERENCE_SYMBOL: unique symbol = Symbol();
 /**
  * A `QueryReference` is an opaque object returned by {@link useBackgroundQuery}.
  * A child component reading the `QueryReference` via {@link useReadQuery} will
@@ -37,14 +37,31 @@ interface InternalQueryReferenceOptions {
   autoDisposeTimeoutMs?: number;
 }
 
-const OBSERVED_CHANGED_OPTIONS: Array<keyof WatchQueryOptions> = [
+export function wrapQueryRef<TData>(
+  internalQueryRef: InternalQueryReference<TData>
+): QueryReference<TData> {
+  return { [QUERY_REFERENCE_SYMBOL]: internalQueryRef };
+}
+
+export function unwrapQueryRef<TData>(
+  queryRef: QueryReference<TData>
+): InternalQueryReference<TData> {
+  return queryRef[QUERY_REFERENCE_SYMBOL];
+}
+
+const OBSERVED_CHANGED_OPTIONS = [
   'canonizeResults',
   'context',
   'errorPolicy',
   'fetchPolicy',
   'refetchWritePolicy',
   'returnPartialData',
-];
+] as const;
+
+type ObservedOptions = Pick<
+  WatchQueryOptions,
+  typeof OBSERVED_CHANGED_OPTIONS[number]
+>;
 
 export class InternalQueryReference<TData = unknown> {
   public result: ApolloQueryResult<TData>;
@@ -68,12 +85,12 @@ export class InternalQueryReference<TData = unknown> {
     observable: ObservableQuery<TData>,
     options: InternalQueryReferenceOptions
   ) {
-    this.listen = this.listen.bind(this);
     this.handleNext = this.handleNext.bind(this);
     this.handleError = this.handleError.bind(this);
-    this.initiateFetch = this.initiateFetch.bind(this);
     this.dispose = this.dispose.bind(this);
     this.observable = observable;
+    // Don't save this result as last result to prevent delivery of last result
+    // when first subscribing
     this.result = observable.getCurrentResult(false);
     this.key = options.key;
 
@@ -138,14 +155,14 @@ export class InternalQueryReference<TData = unknown> {
     };
   }
 
-  didChangeOptions(watchQueryOptions: WatchQueryOptions) {
+  didChangeOptions(watchQueryOptions: ObservedOptions) {
     return OBSERVED_CHANGED_OPTIONS.some(
       (option) =>
         !equal(this.watchQueryOptions[option], watchQueryOptions[option])
     );
   }
 
-  applyOptions(watchQueryOptions: WatchQueryOptions) {
+  applyOptions(watchQueryOptions: ObservedOptions) {
     const {
       fetchPolicy: currentFetchPolicy,
       canonizeResults: currentCanonizeResults,
@@ -209,6 +226,9 @@ export class InternalQueryReference<TData = unknown> {
         break;
       }
       case 'idle': {
+        // This occurs when switching to a result that is fully cached when this
+        // class is instantiated. ObservableQuery will run reobserve when
+        // subscribing, which delivers a result from the cache.
         if (result.data === this.result.data) {
           return;
         }