relay-runtime 20.1.0 → 21.0.0

package/llm-docs/api-reference/hooks/use-lazy-load-query.mdx

@@ -0,0 +1,62 @@
+---
+id: use-lazy-load-query
+title: useLazyLoadQuery
+slug: /api-reference/use-lazy-load-query/
+description: API reference for useLazyLoadQuery, a React hook used to lazily fetch query data when a component renders
+keywords:
+  - lazy fetching
+  - query
+  - fetch
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+## `useLazyLoadQuery`
+
+Hook used to fetch a GraphQL query during render. This hook can trigger multiple nested or waterfalling round trips if used without caution, and waits until render to start a data fetch (when it can usually start a lot sooner than render), thereby degrading performance. Instead, prefer [`usePreloadedQuery`](../use-preloaded-query).
+
+```js
+const React = require('React');
+
+const {graphql, useLazyLoadQuery} = require('react-relay');
+
+function App() {
+  const data = useLazyLoadQuery(
+    graphql`
+      query AppQuery($id: ID!) {
+        user(id: $id) {
+          name
+        }
+      }
+    `,
+    {id: 4},
+    {fetchPolicy: 'store-or-network'},
+  );
+
+ return <h1>{data.user?.name}</h1>;
+}
+```
+
+### Arguments
+
+* `gqlQuery`: GraphQL query specified using a `graphql` template literal.
+* `variables`: Object containing the variable values to fetch the query. These variables need to match GraphQL variables declared inside the query.
+* `options`: _*[Optional]*_ options object
+  * `fetchPolicy`: _*[Optional]*_ Determines if cached data should be used, and when to send a network request based on the cached data that is currently available in the Relay store (for more details, see our [Fetch Policies](../../guided-tour/reusing-cached-data/fetch-policies) and [Garbage Collection](../../guided-tour/reusing-cached-data/presence-of-data) guides):
+     * "store-or-network": _*(default)*_ *will* reuse locally cached data and will *only* send a network request if any data for the query is missing. If the query is fully cached, a network request will *not* be made.
+     * "store-and-network": *will* reuse locally cached data and will *always* send a network request, regardless of whether any data was missing from the local cache or not.
+     * "network-only": *will* *not* reuse locally cached data, and will *always* send a network request to fetch the query, ignoring any data that might be locally cached in Relay.
+     * "store-only": *will* *only* reuse locally cached data, and will *never* send a network request to fetch the query. In this case, the responsibility of fetching the query falls to the caller, but this policy could also be used to read and operate on data that is entirely [local](../../guided-tour/updating-data/local-data-updates).
+  * `fetchKey`: _*[Optional]*_ A `fetchKey` can be passed to force a re-evaluation of the current query and variables when the component re-renders, even if the variables didn't change, or even if the component isn't remounted (similarly to how passing a different `key` to a React component will cause it to remount). If the `fetchKey` is different from the one used in the previous render, the current query will be re-evaluated against the store, and it might be refetched depending on the current `fetchPolicy` and the state of the cache.
+  * `networkCacheConfig`: _*[Optional]*_ Default value: `{force: true}`. Object containing cache config options for the *network layer*. Note that the network layer may contain an *additional* query response cache which will reuse network responses for identical queries. If you want to bypass this cache completely (which is the default behavior), pass `{force: true}` as the value for this option.
+  * `UNSTABLE_renderPolicy`: _*[Optional]*_ Undocumented option.
+
+### Return Value
+
+- `data`: Object that contains data which has been read out from the Relay store; the object matches the shape of specified query.
+  - The Flow type for data will also match this shape, and contain types derived from the GraphQL Schema. For example, the type of `data` above is: `{| user: ?{| name: ?string |} |}`.
+
+import UseLazyLoadQueryExtra from './_use-lazy-load-query-extra.mdx';
+
+<UseLazyLoadQueryExtra />
+<DocsRating />

package/llm-docs/api-reference/hooks/use-mutation.mdx

@@ -0,0 +1,94 @@
+---
+id: use-mutation
+title: useMutation
+slug: /api-reference/use-mutation/
+description: API reference for useMutation, a React hook used to execute a GraphQL mutation
+keywords:
+  - mutation
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+
+## `useMutation`
+
+Hook used to execute a mutation in a React component.
+
+```js
+import type {FeedbackLikeMutation} from 'FeedbackLikeMutation.graphql';
+const React = require('React');
+
+const {graphql, useMutation} = require('react-relay');
+
+function LikeButton() {
+  const [commit, isInFlight] = useMutation<FeedbackLikeMutation>(graphql`
+    mutation FeedbackLikeMutation($input: FeedbackLikeData!) {
+      feedback_like(data: $input) {
+        feedback {
+          id
+          viewer_does_like
+          like_count
+        }
+      }
+    }
+  `);
+
+  if (isInFlight) {
+    return <Spinner />;
+  }
+
+  return (
+    <button
+      onClick={() => {
+        commit({
+          variables: {
+            input: {
+              id: '123',
+              text: 'text',
+            },
+          },
+          onCompleted(data) {
+            console.log(data);
+          },
+        });
+      }}
+    />
+  );
+}
+```
+
+### Arguments
+
+* `mutation`: GraphQL mutation specified using a `graphql` template literal.
+
+<OssOnly>
+
+* `commitMutationFn`: `<T: MutationParameters>(IEnvironment, MutationConfig<T>): Disposable`. *_[Optional]_* A function with the same signature as [`commitMutation`](../commit-mutation), which will be called in its stead. Defaults to `commitMutation`.
+
+</OssOnly>
+
+// @fb-only
+
+### Return Value
+
+Tuple containing the following values:
+
+* [0] `commitMutation`: The function that will execute the mutation
+    * Arguments, the syntax signature is almost the same as our `commitMutation` API
+        * `variables`: Object containing the variables needed for the mutation. For example, if the mutation defines an `$input` variable, this object should contain an `input` key, whose shape must match the shape of the data expected by the mutation as defined by the GraphQL schema.
+        * `onCompleted`: Callback function executed when the request is completed and the in-memory Relay store is updated with the `updater` function. Takes a `response` object, which is the "raw" server response. Internally `errors` are not allowed, `CRITICAL` error will be thrown in the `onError` handler.
+        * `onError`: Callback function executed if Relay encounters an error during the request. Internally, `CRITICAL` error during reading the mutation result on the server
+        * `optimisticResponse`: Object containing the data to optimistically update the local in-memory store, i.e. immediately, before the mutation request has completed. This object must have the same shape as the mutation's response type, as defined by the GraphQL schema. If provided, Relay will use the `optimisticResponse` data to update the fields on the relevant records in the local data store, *before* `optimisticUpdater` is executed. If an error occurs during the mutation request, the optimistic update will be rolled back.
+        * `optimisticUpdater`: Function used to optimistically update the local in-memory store, i.e. immediately, before the mutation request has completed. If an error occurs during the mutation request, the optimistic update will be rolled back. This function takes a `store`, which is a proxy of the in-memory [Relay Store](../store/). In this function, the client defines how to update the local data via the `store` instance. For details on how to use the `store`, please refer to our [Relay Store API Reference](../store/). Please note:
+            * It is usually preferable to just pass an `optimisticResponse` option instead of an `optimisticUpdater`, unless you need to perform updates on the local records that are more complicated than just updating fields (e.g. deleting records or adding items to collections).
+            * If you do decide to use an `optimisticUpdater`, often times it can be the same function as `updater`.
+        * `updater`: Function used to update the local in-memory store based on the real server response from the mutation. If `updater` is not provided, by default, Relay will know to automatically update the fields on the records referenced in the mutation response; however, you should pass an `updater` if you need to make more complicated updates than just updating fields (e.g. deleting records or adding items to collections). When the server response comes back, Relay first reverts any changes introduced by `optimisticUpdater` or `optimisticResponse` and will then execute `updater`. This function takes a `store`, which is a proxy of the in-memory [Relay Store](../store/). In this function, the client defines how to update the local data based on the server response via the `store` instance. For details on how to use the `store`, please refer to our [Relay Store API](../store/)
+        * `uploadables`: An optional uploadable map, an object representing any number of uploadable items, with one key per item. Each value must be of type `File` or `Blob`.
+        *  No environment argument: `useMutation` will automatically use the current environment provided by `RelayEnvironmentProvider`
+    * Return value:
+        * `disposable`: Object containing a `dispose` function. Calling `disposable.dispose()` will revert the optimistic update, and Relay won't update the store or call any success/error callback, but the network request is not guaranteed to be cancelled. If the `dispose` is called after the mutation has succeeded, it will not rollback the update in Relay store.
+* [1] `areMutationsInFlight`: Will be `true` if any mutation triggered by calling `commitMutation` is still in flight. If you call `commitMutation` multiple times, there can be multiple mutations in flight at once.
+
+
+<DocsRating />

package/llm-docs/api-reference/hooks/use-pagination-fragment.mdx

@@ -0,0 +1,166 @@
+---
+id: use-pagination-fragment
+title: usePaginationFragment
+slug: /api-reference/use-pagination-fragment/
+description: API reference for usePaginationFragment, a React hook used to paginate a connection
+keywords:
+  - pagination
+  - connection
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+import {default as FbUsePaginationFragmentReturnValue} from '../../FbFakeContent.mdx'; // @oss-only
+
+## `usePaginationFragment`
+
+You can use `usePaginationFragment` to render a fragment that uses a `@connection` and paginate over it:
+
+```js
+import type {FriendsList_user$key} from 'FriendsList_user.graphql';
+
+const React = require('React');
+
+const {graphql, usePaginationFragment} = require('react-relay');
+
+type Props = {
+  user: FriendsList_user$key,
+};
+
+function FriendsList(props: Props) {
+  const {
+    data,
+    loadNext,
+    loadPrevious,
+    hasNext,
+    hasPrevious,
+    isLoadingNext,
+    isLoadingPrevious,
+    refetch, // For refetching connection
+  } = usePaginationFragment(
+    graphql`
+      fragment FriendsListComponent_user on User
+      @argumentDefinitions(
+        count: { type: "Int", defaultValue: 5 }
+        cursor: { type: "String" }
+      )
+      @refetchable(queryName: "FriendsListPaginationQuery") {
+        name
+        friends(first: $count, after: $cursor)
+        @connection(key: "FriendsList_user_friends") {
+          edges {
+            node {
+              name
+              age
+            }
+          }
+        }
+      }
+    `,
+    props.user,
+  );
+
+  return (
+    <>
+      <h1>Friends of {data.name}:</h1>
+
+      <List items={data.friends?.edges.map(edge => edge.node)}>
+        {node => {
+          return (
+            <div>
+              {node.name} - {node.age}
+            </div>
+          );
+        }}
+      </List>
+      <Button onClick={() => loadNext(10)}>Load more friends</Button>
+    </>
+  );
+}
+
+module.exports = FriendsList;
+```
+
+### Arguments
+
+* `fragment`: GraphQL fragment specified using a `graphql` template literal.
+    * This fragment must have an `@connection` directive on a connection field, otherwise using it will throw an error.
+    * This fragment must have a `@refetchable` directive, otherwise using it will throw an error. The `@refetchable` directive can only be added to fragments that are "refetchable", that is, on fragments that are declared on `Viewer` or  `Query` types, or on a type that implements `Node` (i.e. a type that has an `id`).
+        * Note that you *do not* need to manually specify a pagination query yourself. The `@refetchable` directive will autogenerate a query with the specified `queryName`. This will also generate Flow types for the query, available to import from the generated file: `<queryName>.graphql.js`.
+* `fragmentReference`: The *fragment reference* is an opaque Relay object that Relay uses to read the data for the fragment from the store; more specifically, it contains information about which particular object instance the data should be read from.
+    * The type of the fragment reference can be imported from the generated Flow types, from the file `<fragment_name>.graphql.js`, and can be used to declare the type of your `Props`. The name of the fragment reference type will be: `<fragment_name>$key`. We use our [lint rule](https://github.com/relayjs/eslint-plugin-relay) to enforce that the type of the fragment reference prop is correctly declared.
+
+### Return Value
+
+<FbInternalOnly>
+  <FbUsePaginationFragmentReturnValue />
+</FbInternalOnly>
+
+<OssOnly>
+
+Object containing the following properties:
+
+* `data`: Object that contains data which has been read out from the Relay store; the object matches the shape of specified fragment.
+    * The Flow type for data will also match this shape, and contain types derived from the GraphQL Schema.
+* `isLoadingNext`: Boolean value which indicates if a pagination request for the *next* items in the connection is currently in flight, including any incremental data payloads.
+* `isLoadingPrevious`: Boolean value which indicates if a pagination request for the *previous* items in the connection is currently in flight, including any incremental data payloads.
+* `hasNext`: Boolean value which indicates if the end of the connection has been reached in the "forward" direction. It will be true if there are more items to query for available in that direction, or false otherwise.
+* `hasPrevious`: Boolean value which indicates if the end of the connection has been reached in the "backward" direction. It will be true if there are more items to query for available in that direction, or false otherwise.
+* `loadNext`: Function used to fetch more items in the connection in the "forward" direction.
+    * Arguments:
+        * `count`*:* Number that indicates how many items to query for in the pagination request.
+        * `options`: *_[Optional]_* options object
+            * `onComplete`: Function that will be called whenever the refetch request has completed, including any incremental data payloads. If an error occurs during the request, `onComplete` will be called with an `Error` object as the first parameter.
+    * Return Value:
+        * `disposable`: Object containing a `dispose` function. Calling `disposable.dispose()` will cancel the pagination request.
+    * Behavior:
+        * Calling `loadNext`  *will not* cause the component to suspend. Instead, the `isLoadingNext` value will be set to true while the request is in flight, and the new items from the pagination request will be added to the connection, causing the component to re-render.
+        * Pagination requests initiated from calling `loadNext` will *always* use the same variables that were originally used to fetch the connection, *except* pagination variables (which need to change in order to perform pagination); changing variables other than the pagination variables during pagination doesn't make sense, since that'd mean we'd be querying for a different connection.
+* `loadPrevious`: Function used to fetch more items in the connection in the "backward" direction.
+    * Arguments:
+        * `count`*:* Number that indicates how many items to query for in the pagination request.
+        * `options`: *_[Optional]_* options object
+            * `onComplete`: Function that will be called whenever the refetch request has completed, including any incremental data payloads. If an error occurs during the request, `onComplete` will be called with an `Error` object as the first parameter.
+    * Return Value:
+        * `disposable`: Object containing a `dispose` function. Calling `disposable.dispose()` will cancel the pagination request.
+    * Behavior:
+        * Calling `loadPrevious`  *will not* cause the component to suspend. Instead, the `isLoadingPrevious` value will be set to true while the request is in flight, and the new items from the pagination request will be added to the connection, causing the component to re-render.
+        * Pagination requests initiated from calling `loadPrevious` will *always* use the same variables that were originally used to fetch the connection, *except* pagination variables (which need to change in order to perform pagination); changing variables other than the pagination variables during pagination doesn't make sense, since that'd mean we'd be querying for a different connection.
+* `refetch`: Function used to refetch the connection fragment with a potentially new set of variables.
+    * Arguments:
+        * `variables`: Object containing the new set of variable values to be used to fetch the `@refetchable` query.
+            * These variables need to match GraphQL variables referenced inside the fragment.
+            * However, only the variables that are intended to change for the refetch request need to be specified; any variables referenced by the fragment that are omitted from this input will fall back to using the value specified in the original parent query. So for example, to refetch the fragment with the exact same variables as it was originally fetched, you can call `refetch({})`.
+            * Similarly, passing an `id` value for the `$id` variable is _*optional*_, unless the fragment wants to be refetched with a different `id`. When refetching a `@refetchable` fragment, Relay will already know the id of the rendered object.
+        * `options`: *_[Optional]_* options object
+            * `fetchPolicy`: Determines if cached data should be used, and when to send a network request based on cached data that is available. See the [Fetch Policies](../../guided-tour/reusing-cached-data/fetch-policies/) section for full specification.
+            * `onComplete`: Function that will be called whenever the refetch request has completed, including any incremental data payloads.
+    * Return value:
+        * `disposable`: Object containing a `dispose` function. Calling `disposable.dispose()` will cancel the refetch request.
+    * Behavior:
+        * Calling `refetch` with a new set of variables will fetch the fragment again *with the newly provided variables*. Note that the variables you need to provide are only the ones referenced inside the fragment. In this example, it means fetching the translated body of the currently rendered Comment, by passing a new value to the `lang` variable.
+        * Calling `refetch` will re-render your component and may cause it to *[suspend](../../guided-tour/rendering/loading-states)*, depending on the specified `fetchPolicy` and whether cached data is available or if it needs to send and wait for a network request. If refetch causes the component to suspend, you'll need to make sure that there's a `Suspense` boundary wrapping this component.
+        * For more details on Suspense, see our [Loading States with Suspense](../../guided-tour/rendering/loading-states/) guide.
+
+</OssOnly>
+
+### Behavior
+
+* The component is automatically subscribed to updates to the fragment data: if the data for this particular `User` is updated anywhere in the app (e.g. via fetching new data, or mutating existing data), the component will automatically re-render with the latest updated data.
+* The component will suspend if any data for that specific fragment is missing, and the data is currently being fetched by a parent query.
+    * For more details on Suspense, see our [Loading States with Suspense](../../guided-tour/rendering/loading-states/) guide.
+* Note that pagination (`loadNext` or `loadPrevious`), *will not* cause the component to suspend.
+
+### Differences with `PaginationContainer`
+
+* A pagination query no longer needs to be specified in this api, since it will be automatically generated by Relay by using a `@refetchable` fragment.
+* This api supports simultaneous bi-directional pagination out of the box.
+* This api no longer requires passing `getVariables` or `getFragmentVariables` configuration functions, like the `PaginationContainer` does.
+    * This implies that pagination no longer has a distinction between `variables` and `fragmentVariables`, which were previously vaguely defined concepts. Pagination requests will always use the same variables that were originally used to fetch the connection, *except* pagination variables (which need to change in order to perform pagination); changing variables other than the pagination variables during pagination doesn't make sense, since that'd mean we'd be querying for a different connection.
+* This api no longer takes additional configuration like `direction` or `getConnectionFromProps` function (like Pagination Container does). These values will be automatically determined by Relay.
+* Refetching no longer has a distinction between `variables` and `fragmentVariables`, which were previously vaguely defined concepts. Refetching will always correctly refetch and render the fragment with the variables you provide (any variables omitted in the input will fallback to using the original values in the parent query).
+* Refetching will unequivocally update the component, which was not always true when calling `refetchConnection` from `PaginationContainer` (it would depend on what you were querying for in the refetch query and if your fragment was defined on the right object type).
+
+
+<DocsRating />

package/llm-docs/api-reference/hooks/use-prefetchable-forward-pagination-fragment.mdx

@@ -0,0 +1,134 @@
+---
+id: use-prefetchable-forward-pagination-fragment
+title: usePrefetchableForwardPaginationFragment
+slug: /api-reference/use-prefetchable-forward-pagination-fragment/
+description: API reference for usePrefetchableForwardPaginationFragment, an experimental React hook used to paginate a connection and automatically prefetches
+keywords:
+  - pagination
+  - connection
+  - prefetching
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+NOTE: This is an experimental API and may be subject to change.
+`usePrefetchableForwardPaginationFragment` is similar to [`usePaginationFragment`](../use-pagination-fragment). It adds the capability to automatically prefetch a `bufferSize` number of items to fill the buffer without displaying the items. And when `loadNext` is called, it vends from the buffer first to achieve faster pagination. It only supports forward pagination (provides APIs for `loadNext`, `hasNext` and `isLoadingNext`) for now.
+
+```js
+import type {FriendsList_user$key} from 'FriendsList_user.graphql';
+
+const React = require('React');
+
+const {graphql, usePrefetchableForwardPaginationFragment} = require('react-relay');
+
+type Props = {
+  user: FriendsList_user$key,
+};
+
+function FriendsList(props: Props) {
+  const {
+    data,
+    edges, // NOTE: It is required to use `edges` to access the items
+    loadNext,
+    hasNext,
+    isLoadingNext,
+    refetch, // For refetching connection
+  } = usePrefetchableForwardPaginationFragment(
+    graphql`
+      fragment FriendsListComponent_user on User
+      @refetchable(queryName: "FriendsListPaginationQuery") {
+        name
+        friends(first: $count, after: $cursor)
+        @connection(key: "FriendsList_user_friends", prefetchable_pagination: true) {
+          edges {
+            node {
+              name
+              age
+            }
+          }
+        }
+      }
+    `,
+    props.user,
+  );
+
+  return (
+    <>
+      <h1>Friends of {data.name}:</h1>
+
+      <List items={edges.map(edge => edge.node)}>
+        {node => {
+          return (
+            <div>
+              {node.name} - {node.age}
+            </div>
+          );
+        }}
+      </List>
+      <Button onClick={() => loadNext(10)}>Load more friends</Button>
+    </>
+  );
+}
+
+module.exports = FriendsList;
+```
+
+### Arguments
+
+* `fragment`: GraphQL fragment specified using a `graphql` template literal.
+    * This fragment must have an `@connection` directive on a connection field, and set `prefetchable_pagination` to `true`, otherwise using it will throw an error.
+    * This fragment must have a `@refetchable` directive, otherwise using it will throw an error. The `@refetchable` directive can only be added to fragments that are "refetchable", that is, on fragments that are declared on `Viewer` or  `Query` types, or on a type that implements `Node` (i.e. a type that has an `id`).
+        * Note that you *do not* need to manually specify a pagination query yourself. The `@refetchable` directive will autogenerate a query with the specified `queryName`. This will also generate Flow types for the query, available to import from the generated file: `<queryName>.graphql.js`.
+* `fragmentReference`: The *fragment reference* is an opaque Relay object that Relay uses to read the data for the fragment from the store; more specifically, it contains information about which particular object instance the data should be read from.
+    * The type of the fragment reference can be imported from the generated Flow types, from the file `<fragment_name>.graphql.js`, and can be used to declare the type of your `Props`. The name of the fragment reference type will be: `<fragment_name>$key`. We use our [lint rule](https://github.com/relayjs/eslint-plugin-relay) to enforce that the type of the fragment reference prop is correctly declared.
+* `bufferSize`: The size of the buffer. The component will always try to prefetch to fill the buffer.
+* `initialSize`: *_[Optional]_* argument to define the initial number of items to display. If it is unset, the component shows all available items on the initial render or on refetch.
+* `prefetchingLoadMoreOptions`: *_[Optional]_* fetching arguments to provide to the automatic prefetch.
+  * `options`: *_[Optional]_* options object
+      * `onComplete`: Function that will be called whenever the request has completed, including any incremental data payloads. If an error occurs during the request, `onComplete` will be called with an `Error` object as the first parameter.
+* `minimumFetchSize`: Optional argument to define the minimum number of items to fetch in any requests.
+
+### Return Value
+
+Object containing the following properties:
+
+* `edges`: The edges to use. This provides a filtered list of edges in the connection that excludes the buffer. Do not use the connection edges from `data` to render otherwise the hook will not work correctly.
+* `data`: Object that contains data which has been read out from the Relay store; the object matches the shape of specified fragment.
+    * The Flow type for data will also match this shape, and contain types derived from the GraphQL Schema.
+* `isLoadingNext`: Boolean value which indicates if a pagination request for the *next* items in the connection is currently in flight, including any incremental data payloads. The value stays `false` if the hook is automatically prefetching to fill the buffer, and the code hasn't asked for more items.
+* `hasNext`: Boolean value which indicates if the end of the connection has been reached in the "forward" direction. It will be true if there are more items to query for available in that direction, or there are more items in the buffer, or false otherwise.
+* `loadNext`: Function used to fetch more items in the connection in the "forward" direction.
+    * Arguments:
+        * `count`*:* Number that indicates how many items to show more from buffer or fetch.
+        * `options`: *_[Optional]_* options object
+            * `onComplete`: Function that will be called whenever the request has completed, including any incremental data payloads. If an error occurs during the request, `onComplete` will be called with an `Error` object as the first parameter.
+    * Return Value: void
+    * Behavior:
+        * Calling `loadNext`  *will not* cause the component to suspend. The component first tries to fill the request using items prefetched in the buffer, if there aren't enough items, it sends a request. The `isLoadingNext` value will be set to true while the request is in flight.
+        * Pagination requests initiated from calling `loadNext` will *always* use the same variables that were originally used to fetch the connection, *except* pagination variables (which need to change in order to perform pagination); changing variables other than the pagination variables during pagination doesn't make sense, since that'd mean we'd be querying for a different connection.
+
+* `refetch`: Function used to refetch the connection fragment with a potentially new set of variables.
+    * Arguments:
+        * `variables`: Object containing the new set of variable values to be used to fetch the `@refetchable` query.
+            * These variables need to match GraphQL variables referenced inside the fragment.
+            * However, only the variables that are intended to change for the refetch request need to be specified; any variables referenced by the fragment that are omitted from this input will fall back to using the value specified in the original parent query. So for example, to refetch the fragment with the exact same variables as it was originally fetched, you can call `refetch({})`.
+            * Similarly, passing an `id` value for the `$id` variable is _*optional*_, unless the fragment wants to be refetched with a different `id`. When refetching a `@refetchable` fragment, Relay will already know the id of the rendered object.
+        * `options`: *_[Optional]_* options object
+            * `fetchPolicy`: Determines if cached data should be used, and when to send a network request based on cached data that is available. See the [Fetch Policies](../../guided-tour/reusing-cached-data/fetch-policies/) section for full specification.
+            * `onComplete`: Function that will be called whenever the refetch request has completed, including any incremental data payloads.
+    * Return value:
+        * `disposable`: Object containing a `dispose` function. Calling `disposable.dispose()` will cancel the refetch request.
+    * Behavior:
+        * Calling `refetch` with a new set of variables will fetch the fragment again *with the newly provided variables*. Note that the variables you need to provide are only the ones referenced inside the fragment. In this example, it means fetching the translated body of the currently rendered Comment, by passing a new value to the `lang` variable.
+        * Calling `refetch` will re-render your component and may cause it to *[suspend](../../guided-tour/rendering/loading-states)*, depending on the specified `fetchPolicy` and whether cached data is available or if it needs to send and wait for a network request. If refetch causes the component to suspend, you'll need to make sure that there's a `Suspense` boundary wrapping this component.
+        * For more details on Suspense, see our [Loading States with Suspense](../../guided-tour/rendering/loading-states/) guide.
+
+### Behavior
+
+* The component automatically fetches for more items to fill the buffer in `useEffect`.
+* The component is automatically subscribed to updates to the fragment data: if the data for this particular `User` is updated anywhere in the app (e.g. via fetching new data, or mutating existing data), the component will automatically re-render with the latest updated data.
+* The component will suspend if any data for that specific fragment is missing, and the data is currently being fetched by a parent query.
+    * For more details on Suspense, see our [Loading States with Suspense](../../guided-tour/rendering/loading-states/) guide.
+* Note that pagination (`loadNext`), *will not* cause the component to suspend.
+
+<DocsRating />

package/llm-docs/api-reference/hooks/use-preloaded-query.mdx

@@ -0,0 +1,84 @@
+---
+id: use-preloaded-query
+title: usePreloadedQuery
+slug: /api-reference/use-preloaded-query/
+description: API reference for usePreloadedQuery, a React hook used to read query data from the Relay store using a query reference
+keywords:
+  - read
+  - query
+  - query reference
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+## `usePreloadedQuery`
+
+Hook used to access data fetched by an earlier call to [`loadQuery`](../load-query) or with the help of [`useQueryLoader`](../use-query-loader). This implements the "render-as-you-fetch" pattern:
+
+* Call the `loadQuery` callback returned from `useQueryLoader`. This will store a query reference in React state.
+    * You can also call the imported `loadQuery` directly, which returns a query reference. In that case, store the item in state or in a React ref, and call `dispose()` on the value when you are no longer using it.
+* Then, in your render method, consume the query reference with `usePreloadedQuery()`. This call will suspend if the query is still pending, throw an error if it failed, and otherwise return the query results.
+* This pattern is encouraged over `useLazyLoadQuery()` as it can allow fetching data earlier while not blocking rendering.
+
+For more information, see the [Rendering Queries](../../guided-tour/rendering/queries) guide.
+
+```js
+
+import type {AppQueryType} from 'AppQueryType.graphql';
+
+const React = require('React');
+
+const {graphql, useQueryLoader, usePreloadedQuery} = require('react-relay');
+
+const AppQuery = graphql`
+  query AppQuery($id: ID!) {
+    user(id: $id) {
+      name
+    }
+  }
+`;
+
+type Props = {
+  initialQueryRef: PreloadedQuery<AppQueryType>,
+};
+
+function NameLoader(props) {
+  const [queryReference, loadQuery] = useQueryLoader(
+    AppQuery,
+    props.initialQueryRef, /* e.g. provided by router */
+  );
+
+  return (<>
+    <Button
+      onClick={() => loadQuery({id: '4'})}
+      disabled={queryReference != null}
+    >
+      Reveal your name!
+    </Button>
+    <Suspense fallback="Loading...">
+      {queryReference != null
+        ? <NameDisplay queryReference={queryReference} />
+        : null
+      }
+    </Suspense>
+  </>);
+}
+
+function NameDisplay({ queryReference }) {
+  const data = usePreloadedQuery(AppQuery, queryReference);
+
+  return <h1>{data.user?.name}</h1>;
+}
+```
+
+### Arguments
+
+* `query`: GraphQL query specified using a `graphql` template literal.
+* `preloadedQueryReference`: A `PreloadedQuery` query reference, which can be acquired from [`useQueryLoader`](../use-query-loader) or by calling [`loadQuery()`](../load-query) .
+
+### Return Value
+
+* `data`: Object that contains data which has been read out from the Relay store; the object matches the shape of specified query.
+    * The Flow type for data will also match this shape, and contain types derived from the GraphQL Schema. For example, the type of `data` above is: `{ user: ?{ name: ?string } }`.
+
+<DocsRating />

package/llm-docs/api-reference/hooks/use-query-loader.mdx

@@ -0,0 +1,95 @@
+---
+id: use-query-loader
+title: useQueryLoader
+slug: /api-reference/use-query-loader/
+description: API reference for useQueryLoader, a React hook used to imperatively fetch data for a query in response to a user event
+keywords:
+  - query
+  - fetch
+  - preload
+  - render-as-you-fetch
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+## `useQueryLoader`
+
+Hook used to make it easy to safely load and retain queries. It will keep a query reference stored in state, and dispose of it when the component is disposed or it is no longer accessible via state.
+
+This hook is designed to be used with [`usePreloadedQuery`](../use-preloaded-query) to implement the "render-as-you-fetch" pattern. For more information, see the [Fetching Queries for Render](../../guided-tour/rendering/queries/) guide.
+
+```js
+import type {PreloadedQuery} from 'react-relay';
+
+const {useQueryLoader, usePreloadedQuery} = require('react-relay');
+
+const AppQuery = graphql`
+  query AppQuery($id: ID!) {
+    user(id: $id) {
+      name
+    }
+  }
+`;
+
+function QueryFetcherExample() {
+  const [
+    queryReference,
+    loadQuery,
+    disposeQuery,
+  ] = useQueryLoader(
+    AppQuery,
+  );
+
+  if (queryReference == null) {
+    return (
+      <Button onClick={() => loadQuery({})}> Click to reveal the name </Button>
+    );
+  }
+
+  return (
+    <>
+      <Button onClick={disposeQuery}>
+        Click to hide the name and dispose the query.
+      </Button>
+      <React.Suspense fallback="Loading">
+        <NameDisplay queryReference={queryReference} />
+      </React.Suspense>
+    </>
+  );
+}
+
+function NameDisplay({ queryReference }) {
+  const data = usePreloadedQuery(AppQuery, queryReference);
+
+  return <h1>{data.user?.name}</h1>;
+}
+```
+
+### Arguments
+
+* `query`: GraphQL query specified using a `graphql` template literal.
+* `initialQueryRef`: _*[Optional]*_ An initial `PreloadedQuery` to be used as the initial value of the `queryReference` stored in state and returned by `useQueryLoader`.
+
+### Return value
+
+A tuple containing the following values:
+
+* `queryReference`: the query reference, or `null`.
+* `loadQuery`: a callback that, when executed, will load a query, which will be accessible as `queryReference`. If a previous query was loaded, it will dispose of it. It should not be called during React's render phase.
+    * Parameters
+        * `variables`: the variables with which the query is loaded.
+        * `options`: `LoadQueryOptions`. An optional options object, containing the following keys:
+            * `fetchPolicy`: _*[Optional]*_ Determines if cached data should be used, and when to send a network request based on the cached data that is currently available in the Relay store (for more details, see our [Fetch Policies](../../guided-tour/reusing-cached-data/fetch-policies) and [Garbage Collection](../../guided-tour/reusing-cached-data/presence-of-data) guides):
+                * "store-or-network": _*(default)*_ *will* reuse locally cached data and will *only* send a network request if any data for the query is missing. If the query is fully cached, a network request will *not* be made.
+                * "store-and-network": *will* reuse locally cached data and will *always* send a network request, regardless of whether any data was missing from the local cache or not.
+                * "network-only": *will* *not* reuse locally cached data, and will *always* send a network request to fetch the query, ignoring any data that might be locally cached in Relay.
+            * `networkCacheConfig`: *_[Optional]_* Default value: `{force: true}`. Object containing cache config options for the *network layer*. Note that the network layer may contain an *additional* query response cache which will reuse network responses for identical queries. If you want to bypass this cache completely (which is the default behavior), pass `{force: true}` as the value for this option.
+* `disposeQuery`: a callback that, when executed, will set `queryReference` to `null` and call `.dispose()` on it. It has type `() => void`. It should not be called during React's render phase.
+
+### Behavior
+
+* The `loadQuery` callback will fetch data if passed a query, or data and the query if passed a preloadable concrete request. Once both the query and data are available, the data from the query will be written to the store. This differs from the behavior of `preloadQuery_DEPRECATED`, which would only write data to the store if the query was passed to `usePreloadedQuery`.
+* This query reference will be retained by the Relay store, preventing the data from being garbage collected. Once `.dispose()` is called on the query reference, the data is liable to be garbage collected.
+* The `loadQuery` callback should not be called during React's render phase.
+
+<DocsRating />