Skip to content

Commit

Permalink
docs: adds useBackgroundQuery and useReadQuery docs (#10880)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
alessbell and jerelmiller authored May 17, 2023
1 parent 9b47d7d commit 5ab0563
Show file tree
Hide file tree
Showing 6 changed files with 475 additions and 25 deletions.
143 changes: 143 additions & 0 deletions docs/shared/useBackgroundQuery-options.mdx
Original file line number Diff line number Diff line change
@@ -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>
79 changes: 79 additions & 0 deletions docs/shared/useBackgroundQuery-result.mdx
Original file line number Diff line number Diff line change
@@ -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>
68 changes: 68 additions & 0 deletions docs/shared/useReadQuery-result.mdx
Original file line number Diff line number Diff line change
@@ -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>
33 changes: 16 additions & 17 deletions docs/shared/useSuspenseQuery-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
Loading

0 comments on commit 5ab0563

Please sign in to comment.