relay-runtime 20.1.1 → 21.0.0

package/llm-docs/guided-tour/list-data/advanced-pagination.mdx

@@ -0,0 +1,157 @@
+---
+id: advanced-pagination
+title: Advanced Pagination
+slug: /guided-tour/list-data/advanced-pagination/
+description: Relay guide for advanced pagination
+keywords:
+- pagination
+- usePaginationFragment
+- prefetching
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+In this section we're going to cover how to implement more advanced pagination use cases than the default cases covered by `usePaginationFragment`.
+
+
+## Pagination Over Multiple Connections
+
+If you need to paginate over multiple connections within the same component, you can use `usePaginationFragment` multiple times:
+
+```js
+import type {CombinedFriendsListComponent_user$key} from 'CombinedFriendsListComponent_user.graphql';
+import type {CombinedFriendsListComponent_viewer$key} from 'CombinedFriendsListComponent_viewer.graphql';
+
+const React = require('React');
+
+const {graphql, usePaginationFragment} = require('react-relay');
+
+type Props = {
+  user: CombinedFriendsListComponent_user$key,
+  viewer: CombinedFriendsListComponent_viewer$key,
+};
+
+function CombinedFriendsListComponent(props: Props) {
+
+  const {data: userData, ...userPagination} = usePaginationFragment(
+    graphql`
+      fragment CombinedFriendsListComponent_user on User {
+        name
+        friends
+          @connection(
+            key: "CombinedFriendsListComponent_user_friends_connection"
+          ) {
+          edges {
+            node {
+              name
+              age
+            }
+          }
+        }
+      }
+    `,
+    props.user,
+  );
+
+  const {data: viewerData, ...viewerPagination} = usePaginationFragment(
+    graphql`
+      fragment CombinedFriendsListComponent_user on Viewer {
+        actor {
+          ... on User {
+            name
+            friends
+              @connection(
+                key: "CombinedFriendsListComponent_viewer_friends_connection"
+              ) {
+              edges {
+                node {
+                  name
+                  age
+                }
+              }
+            }
+          }
+        }
+      }
+    `,
+    props.viewer,
+  );
+
+  return (...);
+}
+```
+
+However, we recommend trying to keep a single connection per component, to keep the components easier to follow.
+
+
+
+## Bi-directional Pagination
+
+In the [Pagination](../pagination/) section we covered how to use `usePaginationFragment` to paginate in a single *"forward"* direction. However, connections also allow paginating in the opposite *"backward"* direction. The meaning of *"forward"* and *"backward"* directions will depend on how the items in the connection are sorted, for example  *"forward"* could mean more recent*, and "backward"* could mean less recent.
+
+Regardless of the semantic meaning of the direction, Relay also provides the same APIs to paginate in the opposite direction, using `usePaginationFragment`, as long  as the `before` and `last` connection arguments are also used along with `after` and `first`:
+
+```js
+import type {FriendsListComponent_user$key} from 'FriendsListComponent_user.graphql';
+
+const React = require('React');
+const {Suspense} = require('React');
+
+const {graphql, usePaginationFragment} = require('react-relay');
+
+type Props = {
+  userRef: FriendsListComponent_user$key,
+};
+
+function FriendsListComponent(props: Props) {
+  const {
+    data,
+    loadPrevious,
+    hasPrevious,
+    // ... forward pagination values
+  } = usePaginationFragment(
+    graphql`
+      fragment FriendsListComponent_user on User {
+        name
+        friends(after: $after, before: $before, first: $first, last: $last)
+          @connection(key: "FriendsListComponent_user_friends_connection") {
+          edges {
+            node {
+              name
+              age
+            }
+          }
+        }
+      }
+    `,
+    userRef,
+  );
+
+  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>
+
+      {hasPrevious ? (
+        <Button onClick={() => loadPrevious(10)}>
+          Load more friends
+        </Button>
+      ) : null}
+
+      {/* Forward pagination controls can go simultaneously here */}
+    </>
+  );
+}
+```
+
+* The APIs for both *"forward"* and *"backward"* are exactly the same, they're only named differently. When paginating forward, then the  `after` and `first` connection arguments will be used, when paginating backward, the `before` and `last` connection arguments will be used.
+* Note that the primitives for both *"forward"* and *"backward"* pagination are exposed from a single call to `usePaginationFragment`, so both *"forward"* and *"backward"* pagination can be performed simultaneously in the same component.

package/llm-docs/guided-tour/list-data/connections.mdx

@@ -0,0 +1,81 @@
+---
+id: connections
+title: Why Connections?
+slug: /guided-tour/list-data/connections/
+description: Relay guide for connections
+keywords:
+- pagination
+- connections
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+# Why Connections?
+
+:::info
+For a video format of how the connection spec was derived, check out [Sabrina Wasserman's GraphQL talk](../../guides/graphql-server-specification.mdx#graphql-conf-talk)!
+:::
+
+Relay does a lot of the work for you when handling paginated collections of items. But to do that, it relies on a specific convention for how those collections are modeled in your schema. This convention is powerful and flexible, and comes out of experience building many products with collections of items. Let’s step through the design process for this schema convention so that we can understand why it works this way.
+
+There are three important points to understand:
+
+* You may need to model data about an item's inclusion in the collection, such as in a list of friends where you may wish to model the date you friended that person. We handle this by creating nodes that represent the edges, the relationship between the item in the collection and the collection itself.
+* The page itself has properties, such as whether or not there is a next page available. We handle this with a node that represents the current page info.
+* Pagination is done by *cursors* — opaque symbols that point to the next page of results — rather than offsets.
+
+Imagine we want to show a list of the user’s friends. At a high level, we imagine a graph where the viewer and their friends are each nodes. From the viewer to each friend node is an edge, and the edge itself has properties.
+
+![Conceptual graph with properties on its edges](/img/docs/tutorial/connections-conceptual-graph.png)
+
+Now let’s try to model this situation using GraphQL.
+
+In GraphQL, only nodes can have properties, not edges. So the first thing we’ll do is represent the conceptual edge from you to your friend with its very own node.
+
+![Edge properties modeled using nodes that represent the edges](/img/docs/tutorial/connections-edge-nodes.png)
+
+Now the properties of the edge are represented by a new type of node called a “`FriendsEdge`”.
+
+The GraphQL to query this would look like this:
+
+```
+// XXX example only, not final code
+fragment FriendsFragment1 on Viewer {
+  friends {
+    since // a property of the edge
+    node {
+      name // a property of the friend itself
+    }
+  }
+}
+```
+
+Now we have a good place in the GraphQL schema to put edge-specific information such as the date when the edge was created (that is, the date you friended that person).
+
+* * *
+
+Now consider what we would need to model in our schema in order to support pagination and infinite scrolling.
+
+* The client must be able to specify how large of a page it wants.
+* The client must be informed as to whether any more pages are available, so that it can enable or disable the ‘next page’ button (or, for infinite scrolling, can stop making further requests).
+* The client must be able to ask for the next page after the one it already has.
+
+How can we use the features of GraphQL to do these things? Specifying the page size is done with field arguments. In other words, instead of just `friends` the query will say `friends(first: 3)`, passing the page size as an argument to the `friends` field.
+
+For the server to say whether there is a next page or not, we need to introduce a node in the graph that has information about the *list of friends itself,* just like we are introducing a node for each edge to store information about the edge itself. This new node is called a *Connection*.
+
+The Connection node represents the connection itself between you and your friends. Metadata about the connection is stored there — for example, it could have a `totalCount` field that says how many friends you have. In addition, it always has two fields which represent the *current* page: a `pageInfo` field with metadata about the current page, such as whether there is another page available — and an `edges` field that points to the edges we saw before:
+
+![The full connection model with page info and edges](/img/docs/tutorial/connections-full-model.png)
+
+Finally, we need a way to request the next page of results. You’ll notice in the above diagram that the `PageInfo` node has a field called `lastCursor`.  This is an opaque token provided by the server that represents the position in the list of the last edge that we were given (the friend “Charmaine”). We can then pass this cursor back to the server in order to retrieve the next page.
+
+By passing the `lastCursor` value back to the server as an argument to the `friends` field, we can ask the server for friends that are *after* the ones we’ve already retrieved:
+
+![After fetching the next page of results](/img/docs/tutorial/connections-full-model-next-page.png)
+
+This overall scheme for modeling paginated lists is specified in detail in the [GraphQL Cursor Connections Spec](https://relay.dev/graphql/connections.htm). It is flexible for many different applications, and although Relay relies on this convention to handle pagination automatically, designing your schema this way is a good idea whether or not you use Relay.
+
+Now that we've stepped through the underlying model for Connections, let’s turn our attention to actually using it to implement Comments for our Newsfeed stories.
+
+<DocsRating />

package/llm-docs/guided-tour/list-data/pagination.mdx

@@ -0,0 +1,193 @@
+---
+id: pagination
+title: Pagination with Connections
+slug: /guided-tour/list-data/pagination/
+description: Relay guide to connections and pagination
+keywords:
+- pagination
+- connections
+- usePaginationFragment
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+# Pagination with Connections
+
+In order to paginate through lists of data (load only discrete slices of list data), Relay introduces an abstraction known as a "connection". Connections allow you to request discrete slices of data from the server as well as information about the list itself (e.g. how to get the next page of data). For more information about the design of connections, see [Why Connections?](./connections.mdx).
+
+A query with a connection includes:
+- the *connection* itself, a field that returns the `edges` and `pageInfo`. It includes a `first` argument to indicate the page size and an `after` argument to indicate where the beginning of the list is.
+- the *edge*, which contains the `cursor` (a bookmark of where you are in the list) and the `node` (the actual record the connection is paginating over).
+- the *pageInfo*, which contains information about getting more edges (`hasPreviousPage`, `hasNextPage`, `startCursor`, and `endCursor`).
+
+A typical query fragment (for fetching a list of comments) may look like:
+```
+const StoryCommentsSectionFragment = graphql`
+  fragment StoryCommentsSectionFragment on Story {
+    # the connection with arguments to specify which items to fetch
+    comments(after: $cursor, first: $count) {
+      edges {                # the list of edges
+        node {               # the Comment record itself
+          ...CommentFragment # the fields on Comment to fetch
+        }
+        cursor               # an identifier of this Comment's place in the list
+      }
+      pageInfo {             # the page info
+        hasNextPage          # if another page of comments is available
+      }
+    }
+  }
+`;
+```
+
+:::info
+Relay uses "cursors" to specify the beginning of a list. Each node is associated with a unique cursor, which can be passed to the connection to fetch the next page _after_ that cursor. This makes it easy to fetch consecutive pages of data.
+:::
+
+## Connection Directives
+
+Relay handles a lot of the pagination logic for you but to do so, connections must be augmented with directives containing some additional information.
+
+```
+const StoryCommentsSectionFragment = graphql`
+  fragment StoryCommentsSectionFragment on Story
+  @argumentDefinitions(
+    cursor: { type: "String" }
+    count: { type: "Int", defaultValue: 3 }
+  )
+  @refetchable(queryName: "StoryCommentsSectionPaginationQuery") {
+    comments(after: $cursor, first: $count)
+      @connection(key: "StoryCommentsSectionFragment_comments") {
+      edges {
+        node {
+          ...CommentFragment
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        hasPreviousPage
+        startCursor
+        endCursor
+      }
+    }
+  }
+`;
+```
+Breaking this down:
+- `@argumentDefinitions` is just defining the `$cursor` and `$count` variables as [fragment arguments](../../api-reference/graphql/graphql-directives.mdx#argumentdefinitions)
+- `@refetchable` makes the fragment [refetchable](../../tutorial/refetchable-fragments.mdx) so that Relay can fetch it again with new arguments — usually, a new cursor for the `$cursor` argument.
+- `@connection` is what Relay uses to tell _which field_ within the fragment represents the connection to paginate over. The `@connection` directive requires a `key` argument which must be a unique string — here formed from the fragment name and field name. This key is used when editing the connection’s contents via [mutations](../updating-data/updating-connections.mdx).
+
+:::tip
+Relay’s pagination features only work with fragments, not entire queries. This is usually fine as queries are generally issued at some high-level routing component, which would rarely be the same component that’s showing a paginated list. If you need to paginate something at the query level, refactor the connection field out into a fragment that is defined on the `Query` type.
+:::
+
+For a full specification of connections, see the [GraphQL Cursor Connections Spec](https://relay.dev/graphql/connections.htm).
+
+## The usePaginationFragment hook
+
+Relay provides an easy way to use connections in React via the [`usePaginationFragment`](../../api-reference/hooks/use-pagination-fragment.mdx) hook. This hook acts similarly to the [`useFragment`](../../api-reference/hooks/use-fragment.mdx) hook but also provides additional callbacks for loading the next/previous page of data along with checking if those pages exist and loading indicators if a request is in flight. Using the `usePaginationFragment` hook also means you can omit the `pageInfo` and `cursor` fields from your fragment as Relay will automatically insert them and use the information to paginate via the hook. Taking the previous example with the `StoryCommentsSectionFragment`, the fragment can be reduced to:
+
+```
+const StoryCommentsSectionFragment = graphql`
+  fragment StoryCommentsSectionFragment on Story
+  @argumentDefinitions(
+    cursor: { type: "String" }
+    count: { type: "Int", defaultValue: 3 }
+  )
+  @refetchable(queryName: "StoryCommentsSectionPaginationQuery") {
+    comments(after: $cursor, first: $count)
+      @connection(key: "StoryCommentsSectionFragment_comments") {
+      edges {
+        node {
+          ...CommentFragment
+        }
+      }
+    }
+  }
+`;
+```
+
+Here's an example of how the `usePaginationFragment` hook can be used to implement pagination in a React component:
+
+```
+function StoryCommentsSection({story}) {
+  const {
+    data,
+    hasNext,
+    loadNext,
+    isLoadingNext,
+  } = usePaginationFragment(StoryCommentsSectionFragment, story);
+  return (
+    <>
+      {data.comments.edges.map(commentEdge =>
+        <Comment comment={commentEdge.node} />
+      )}
+      {hasNext && (
+        <LoadMoreCommentsButton
+          onClick={() => loadNext(3)}
+          disabled={isLoadingNext}
+        />
+      )}
+      {isLoadingNext && <SmallSpinner />}
+    </>
+  );
+}
+```
+In this example, the `story` prop passed to the `usePaginationFragment` is the same as the query reference passed to `useFragment`. Along with the fragment `data`, the hook in this example also returns `loadNext`, `hasNext`, and `isLoadingNext`.
+- `hasNext` indicates whether another page of data exists.
+- `loadNext` is a function that can be called to load the next page of data — for example when a user clicks on the `LoadMoreCommentsButton`. It takes an argument to indicate how many new items to fetch.
+- In order to provide a better user experience, `isLoadingNext` can be used to show a loading indicator while the next page of comments is loading.
+
+:::info
+When the request to fetch the next items completes, the connection will be automatically updated and the component will re-render with the latest items in the connection. In our case, this means that the `comments` field will always contain *all* of the comments that we've fetched so far. By default, *Relay will automatically append new items to the connection upon completing a pagination request,* and will make them available to your fragment component*.* If you need a different behavior, check out the [Advanced Pagination Use Cases](./advanced-pagination.mdx) section.
+:::
+
+For the full information on the `usePaginationFragment` hook, check out the [API reference](../../api-reference/hooks/use-pagination-fragment.mdx).
+
+## React Loading States
+
+React provides [suspense](https://react.dev/reference/react/Suspense) to allow a fallback while data is loading and [transitions](https://react.dev/reference/react/startTransition) to provide a better user experience when updating data. These can be used in conjunction with `usePaginationFragment`.
+
+Taking the example above,
+```
+function StoryCommentsSection({story}) {
+  const {
+    data,
+    hasNext,
+    loadNext,
+    isLoadingNext,
+  } = usePaginationFragment(StoryCommentsSectionFragment, story);
+  return (
+    <>
+      {data.comments.edges.map(commentEdge => {
+        return (
+          <Suspense fallback={<Glimmer />}>
+            <Comment comment={commentEdge.node} />
+          </Suspense>
+        );
+      })}
+      {hasNext && (
+        <LoadMoreCommentsButton
+          onClick={() => {
+            startTransition(() => {
+              loadNext(3)
+            });
+          }}
+          disabled={isLoadingNext}
+        />
+      )}
+      {isLoadingNext && <SmallSpinner />}
+    </>
+  );
+}
+```
+
+Calling `loadNext` may cause the component or new children components to suspend (as explained in [Loading States with Suspense](../rendering/loading-states.mdx)). This means that you'll need to make sure that there's a `Suspense` boundary wrapping this component from above and/or that you are using a transition in order to show the appropriate pending or loading state.
+
+:::note
+Since `loadNext` may cause the component to suspend, regardless of whether a transition is used to render a pending state (i.e. with a loading indicator from [useTransition](https://react.dev/reference/react/useTransition)), `startTransition` should always be used to schedule that update for the best user experience.
+:::
+
+<DocsRating />

package/llm-docs/guided-tour/list-data/rendering-connections.mdx

@@ -0,0 +1,112 @@
+---
+id: rendering-connections
+title: Rendering Connections
+slug: /guided-tour/list-data/rendering-connections/
+description: Relay guide to rendering connections
+keywords:
+- pagination
+- usePaginationFragment
+- connection
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+// @fb-only
+// @fb-only
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+In Relay, in order to display a list of data that is backed by a GraphQL connection, first you need to declare a fragment that queries for a connection:
+
+```js
+const {graphql} = require('RelayModern');
+
+const userFragment = graphql`
+  fragment UserFragment on User {
+    name
+    friends(after: $cursor, first: $count)
+      @connection(key: "UserFragment_friends") {
+      edges {
+        node {
+          ...FriendComponent
+        }
+      }
+    }
+  }
+`;
+```
+
+* In the example above, we're querying for the `friends` field, which is a connection; in other words, it adheres to the connection spec. Specifically, we can query the `edges` and `node`s in the connection; the `edges` usually contain information about the relationship between the entities, while the `node`s are the actual entities at the other end of the relationship; in this case, the `node`s are objects of type `User` representing the user's friends.
+* In order to indicate to Relay that we want to perform pagination over this connection, we need to mark the field with the `@connection` directive. We must also provide a *static* unique identifier for this connection, known as the `key`. We recommend the following naming convention for the connection key: `<fragment_name>_<field_name>`.
+* We will go into more detail later as to why it is necessary to mark the field as a `@connection` and give it a unique `key` in our [Updating Connections](../updating-connections/) section.
+
+
+In order to render this fragment which queries for a connection, we can use the `usePaginationFragment` Hook:
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+<OssOnly>
+
+```js
+import type {FriendsListComponent_user$key} from 'FriendsList_user.graphql';
+
+const React = require('React');
+const {Suspense} = require('React');
+
+const {graphql, usePaginationFragment} = require('react-relay');
+
+type Props = {
+  user: FriendsListComponent_user$key,
+};
+
+function FriendsListComponent(props: Props) {
+  const {data} = usePaginationFragment(
+    graphql`
+      fragment FriendsListComponent_user on User
+      @refetchable(queryName: "FriendsListPaginationQuery") {
+        name
+        friends(first: $count, after: $cursor)
+        @connection(key: "FriendsList_user_friends") {
+          edges {
+            node {
+              ...FriendComponent
+            }
+          }
+        }
+      }
+    `,
+    props.user,
+  );
+
+
+  return (
+    <>
+      {data.name != null ? <h1>Friends of {data.name}:</h1> : null}
+
+      <div>
+        {/* Extract each friend from the resulting data */}
+        {(data.friends?.edges ?? []).map(edge => {
+          const node = edge.node;
+          return (
+            <Suspense fallback={<Glimmer />}>
+              <FriendComponent user={node} />
+            </Suspense>
+          );
+        })}
+      </div>
+    </>
+  );
+}
+
+module.exports = FriendsListComponent;
+```
+// @fb-only
+
+* `usePaginationFragment` behaves the same way as a `useFragment` (see the [Fragments](../../rendering/fragments/) section), so our list of friends is available under `data.friends.edges.node`, as declared by the fragment. However, it also has a few additions:
+    * It expects a fragment that is a connection field annotated with the `@connection` directive
+    * It expects a fragment that is annotated with the `@refetchable` directive. Note that  `@refetchable` directive can only be added to fragments that are "refetchable", that is, on fragments that are on `Viewer`, on `Query`, on any type that implements `Node` (i.e. a type that has an `id` field), or on a `@fetchable` type. <FbInternalOnly> For more info on `@fetchable` types, see [this post](https://fb.workplace.com/groups/graphql.fyi/permalink/1539541276187011/). </FbInternalOnly>
+* It takes two Flow type parameters: the type of the generated query (in our case  `FriendsListPaginationQuery`), and a second type which can always be inferred, so you only need to pass underscore (`_`).
+
+</OssOnly>
+
+<DocsRating />

package/llm-docs/guided-tour/list-data/streaming-pagination.mdx

@@ -0,0 +1,87 @@
+---
+id: streaming-pagination
+title: Streaming Pagination
+slug: /guided-tour/list-data/streaming-pagination/
+description: Relay guide to streaming pagination
+keywords:
+- pagination
+- usePaginationFragment
+- connection
+- streaming
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+<FbInternalOnly>
+
+Additionally, we can combine `usePaginationFragment` with Relay's [Incremental Data Delivery](../../../guides/incremental-data-delivery/) capabilities in order to fetch a connection and incrementally receive each item in the connection as it becomes ready, instead of waiting for the whole list of items to be returned in a single payload. This can be useful when for example computing each item in the connection is an expensive operation in the server, and we want to be able to show the first item(s) in the list as soon as possible without blocking on *all* the items that we need to become available; for example, on News Feed a user could ideally see and start interacting with the first story while additional stories loaded in below.
+
+</FbInternalOnly>
+
+<OssOnly>
+
+Additionally, we can combine `usePaginationFragment` with Relay's Incremental Data Delivery capabilities in order to fetch a connection and incrementally receive each item in the connection as it becomes ready, instead of waiting for the whole list of items to be returned in a single payload. This can be useful when for example computing each item in the connection is an expensive operation in the server, and we want to be able to show the first item(s) in the list as soon as possible without blocking on *all* the items that we need to become available; for example, on News Feed a user could ideally see and start interacting with the first story while additional stories loaded in below.
+
+</OssOnly>
+
+In order to do so, we can use the `@stream_connection` directive instead of the `@connection` directive:
+
+```js
+import type {FriendsListComponent_user$key} from 'FriendsList_user.graphql';
+
+const React = require('React');
+
+const {graphql, usePaginationFragment} = require('react-relay');
+
+type Props = {
+  user: FriendsListComponent_user$key,
+};
+
+function FriendsListComponent(props: Props) {
+  // ...
+
+  const {
+    data,
+    loadNext,
+    hasNext,
+  } = usePaginationFragment(
+    graphql`
+      fragment FriendsListComponent_user on User
+      @refetchable(queryName: "FriendsListPaginationQuery") {
+        name
+        friends(first: $count, after: $cursor)
+        @stream_connection(key: "FriendsList_user_friends", initial_count: 2,) {
+          edges {
+            node {
+              name
+              age
+            }
+          }
+        }
+      }
+    `,
+    props.user,
+  );
+
+  return (...);
+}
+
+module.exports = FriendsListComponent;
+```
+
+Let's distill what's happening here:
+
+* The `@stream_connection` directive can be used directly in place of the `@connection` directive; it accepts the same arguments as @connection plus additional, *optional* parameters to control streaming:
+    * `initial_count: Int`: A number (defaulting to zero) that controls how many items will be included in the initial payload. Any subsequent items are streamed, so when set to zero the list will initially be empty and all items will be streamed. Note that this number does not affect how many items are returned *total*, only how many items are included in the initial payload. For example, consider a product that today makes an initial fetch for 2 items and then *immediately* issues a pagination query to fetch 3 more. With streaming, this product could instead choose to fetch 5 items in the initial query with initial_count=2, in order to fetch the 2 items quickly while avoiding a round trip for the subsequent 3 items.
+* As with regular usage of `usePaginationFragment`, the connection will be automatically updated as new items are streamed in from the server, and the component will re-render each time with the latest items in the connection.
+
+
+<FbInternalOnly>
+
+For more information, see our docs on [Incremental Data Delivery](../../../guides/incremental-data-delivery/#stream_connection).
+
+</FbInternalOnly>
+
+
+<DocsRating />

package/llm-docs/guided-tour/managing-data-outside-react/retaining-queries.mdx

@@ -0,0 +1,51 @@
+---
+id: retaining-queries
+title: Retaining Queries
+slug: /guided-tour/accessing-data-without-react/retaining-queries/
+description: Relay guide to retaining queries
+keywords:
+- retaining
+- query
+- environment
+- garbage collection
+- gc
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+In order to manually retain a query so that the data it references isn’t garbage collected by Relay, we can use the `environment.retain` method:
+
+```js
+const {
+  createOperationDescriptor,
+  getRequest,
+  graphql,
+} = require('relay-runtime')
+
+// Query graphql object
+const query = graphql`...`;
+
+// Construct Relay's internal representation of the query
+const queryRequest = getRequest(query);
+const queryDescriptor = createOperationDescriptor(
+  queryRequest,
+  variables
+);
+
+// Retain query; this will prevent the data for this query and
+// variables from being garbage collected by Relay
+const disposable = environment.retain(queryDescriptor);
+
+// Disposing of the disposable will release the data for this query
+// and variables, meaning that it can be deleted at any moment
+// by Relay's garbage collection if it hasn't been retained elsewhere
+disposable.dispose();
+```
+
+:::note
+Relay automatically manages the query data retention based on any mounted query components that are rendering the data, so you usually should not need to call retain directly within product code. For any advanced or special use cases, query data retention should usually be handled within infra-level code, such as a Router.
+:::
+
+
+<DocsRating />