docs: adds useBackgroundQuery and useReadQuery docs (#10880)

* docs: adds useBackgroundQuery and useReadQuery docs * docs: add description to Using `useBackgroundQuery_experimental` and `useReadQuery_experimental` section * Update docs/shared/useBackgroundQuery-result.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/shared/useBackgroundQuery-options.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/source/api/react/hooks-experimental.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/source/api/react/hooks-experimental.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/shared/useSuspenseQuery-options.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/shared/useBackgroundQuery-result.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/source/api/react/hooks-experimental.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * Update docs/source/api/react/hooks-experimental.mdx Co-authored-by: Jerel Miller <jerelmiller@gmail.com> * review feedback * select prettier fixes --------- Co-authored-by: Jerel Miller <jerelmiller@gmail.com>
apollographql · May 17, 2023 · 5ab0563 · 5ab0563
1 parent 9b47d7d
commit 5ab0563
Show file tree

Hide file tree

Showing 6 changed files with 475 additions and 25 deletions.
diff --git a/docs/shared/useBackgroundQuery-options.mdx b/docs/shared/useBackgroundQuery-options.mdx
@@ -0,0 +1,143 @@
+<table class="field-table api-ref">
+
+<thead>
+  <tr>
+    <td>Name /<br/>Type</td>
+    <td>Description</td>
+  </tr>
+</thead>
+<tbody>
+
+<tr>
+<td colspan="2">
+
+**Operation options**
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `variables`
+
+`{ [key: string]: any }`
+</td>
+
+<td>
+
+An object containing all of the GraphQL variables your query requires to execute.
+
+Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `errorPolicy`
+
+`ErrorPolicy`
+</td>
+
+<td>
+
+Specifies how the query handles a response that returns both GraphQL errors and partial results.
+
+For details, see [GraphQL error policies](/react/data/error-handling/#graphql-error-policies).
+
+The default value is `none`, which causes the `useReadQuery` hook to throw the error.
+</td>
+</tr>
+
+<tr>
+<td colspan="2">
+
+**Networking options**
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `context`
+
+`Record<string, any>`
+</td>
+
+<td>
+
+If you're using [Apollo Link](/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `canonizeResults`
+
+`Boolean`
+</td>
+
+<td>
+
+If `true`, result objects read from the cache will be _canonized_, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results.
+
+The default value is `false`.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `client`
+
+`ApolloClient`
+</td>
+
+<td>
+
+The instance of `ApolloClient` to use to execute the query.
+
+By default, the instance that's passed down via context is used, but you can provide a different instance here.
+
+</td>
+</tr>
+
+<tr>
+<td colspan="2">
+
+**Caching options**
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `fetchPolicy`
+
+`SuspenseQueryHookFetchPolicy`
+</td>
+
+<td>
+
+Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).
+
+For details, see [Setting a fetch
+policy](/react/data/queries/#setting-a-fetch-policy). This hook only supports
+the `cache-first`, `network-only`, `no-cache`, and `cache-and-network` fetch
+policies.
+
+The default value is `cache-first`.
+
+</td>
+</tr>
+
+</tbody>
+
+</table>
diff --git a/docs/shared/useBackgroundQuery-result.mdx b/docs/shared/useBackgroundQuery-result.mdx
@@ -0,0 +1,79 @@
+<table class="field-table api-ref">
+
+<thead>
+  <tr>
+    <td>Name /<br/>Type</td>
+    <td>Description</td>
+  </tr>
+</thead>
+
+<tbody>
+
+<tr>
+<td colspan="2">
+
+**Query reference**
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `queryRef`
+
+`QueryReference<TData>`
+</td>
+<td>
+
+In order to link a query initiated by a specific `useBackgroundQuery` call to the place its data is consumed—which can be uniquely identified not only by the query and variables passed, but also the optional `queryKey` supplied by the user—the hook returns a `queryRef` that can later be read by `useReadQuery`.
+
+</td>
+</tr>
+
+<tr>
+<td colspan="2">
+
+**Helper functions**
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `refetch`
+
+`(variables?: Partial<TVariables>) => Promise<ApolloQueryResult>`
+</td>
+
+<td>
+
+A function that enables you to re-execute the query, optionally passing in new `variables`.
+
+To guarantee that the refetch performs a network request, its `fetchPolicy` is set to `network-only` (unless the original query's `fetchPolicy` is `no-cache` or `cache-and-network`, which also guarantee a network request).
+
+Calling this function will cause the component to re-suspend, unless the call site is wrapped in [`startTransition`](https://react.dev/reference/react/startTransition).
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `fetchMore`
+
+`({ query?: DocumentNode, variables?: TVariables, updateQuery: Function}) => Promise<ApolloQueryResult>`
+</td>
+
+<td>
+
+A function that helps you fetch the next set of results for a [paginated list field](/react/pagination/core-api/).
+
+Calling this function will cause the component to re-suspend, unless the call site is wrapped in [`startTransition`](https://react.dev/reference/react/startTransition).
+
+</td>
+</tr>
+
+</tbody>
+</table>
diff --git a/docs/shared/useReadQuery-result.mdx b/docs/shared/useReadQuery-result.mdx
@@ -0,0 +1,68 @@
+<table class="field-table api-ref">
+
+<thead>
+  <tr>
+    <td>Name /<br/>Type</td>
+    <td>Description</td>
+  </tr>
+</thead>
+
+<tbody>
+
+<tr>
+<td colspan="2">
+
+**Operation result**
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `data`
+
+`TData`
+</td>
+<td>
+
+An object containing the result of your GraphQL query after it completes.
+
+This value might be `undefined` if a query results in one or more errors (depending on the query's `errorPolicy`).
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `error`
+
+`ApolloError`
+</td>
+<td>
+
+If the query produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+
+This property can be ignored when using the default `errorPolicy` or an `errorPolicy` of `none`. The hook will throw the error instead of setting this property.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `networkStatus`
+
+`NetworkStatus`
+</td>
+
+<td>
+
+A number indicating the current network state of the query's associated request. [See possible values.](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/core/networkStatus.ts#L4)
+
+</td>
+</tr>
+
+</tbody>
+</table>
diff --git a/docs/shared/useSuspenseQuery-options.mdx b/docs/shared/useSuspenseQuery-options.mdx
@@ -62,32 +62,31 @@ The default value is `none`, which causes the hook to throw the error.
 <tr>
 <td>
 
-###### `suspensePolicy`
+###### `context`
 
-`SuspensePolicy`
+`Record<string, any>`
 </td>
 
 <td>
 
-Determines whether the component should re-suspend when refetching data. Set to
-`initial` to avoid re-suspending the component on a refetch.
+If you're using [Apollo Link](/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
 
-The default value is `always`, which will cause the component to always
-re-suspend when refetching data.
 </td>
 </tr>
 
 <tr>
 <td>
 
-###### `context`
+###### `canonizeResults`
 
-`Record<string, any>`
+`Boolean`
 </td>
 
 <td>
 
-If you're using [Apollo Link](/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
+If `true`, result objects read from the cache will be _canonized_, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results.
+
+The default value is `false`.
 
 </td>
 </tr>
@@ -142,33 +141,33 @@ The default value is `cache-first`.
 <tr>
 <td>
 
-###### `nextFetchPolicy`
+###### `returnPartialData`
 
-`SuspenseQueryHookFetchPolicy`
+`boolean`
 </td>
 
 <td>
 
-Specifies the [`fetchPolicy`](#fetchpolicy) to use for all executions of this query _after_ this execution.
+If `true`, the query can return _partial_ results from the cache if the cache doesn't contain results for _all_ queried fields.
 
-For example, you can use this to switch back to a `cache-first` fetch policy after using `cache-and-network` or `network-only` for a single execution.
+The default value is `false`.
 
 </td>
 </tr>
 
 <tr>
 <td>
 
-###### `returnPartialData`
+###### `refetchWritePolicy`
 
-`boolean`
+`"merge" | "overwrite"`
 </td>
 
 <td>
 
-If `true`, the query can return _partial_ results from the cache if the cache doesn't contain results for _all_ queried fields.
+Watched queries must opt into overwriting existing data on refetch, by passing `refetchWritePolicy: "overwrite"` in their `WatchQueryOptions`.
 
-The default value is `false`.
+The default value is `"overwrite"`.
 
 </td>
 </tr>