relay-runtime 20.1.1 → 21.0.0

package/llm-docs/api-reference/graphql/graphql-directives.mdx

@@ -0,0 +1,378 @@
+---
+id: graphql-directives
+title: GraphQL Directives
+slug: /api-reference/graphql-and-directives/
+description: API Reference for GraphQL directives
+keywords:
+  - GraphQL
+  - Directive
+  - arguments
+  - argumentDefinitions
+  - connection
+  - relay
+  - inline
+  - provider
+---
+
+import DocsRating from '@site/src/core/DocsRating'; import {FbInternalOnly,
+OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+Relay uses directives to add additional information to GraphQL documents, which
+are used by the [Relay compiler](../../guides/compiler/) to generate the
+appropriate runtime artifacts. These directives only appear in your application
+code and are removed from requests sent to your GraphQL server.
+
+<OssOnly>
+
+**Note:** The Relay compiler will maintain any directives supported by your server (such as `@include` or `@skip`) so they remain part of the request to the GraphQL server and won't alter generated runtime artifacts.
+
+</OssOnly>
+<FbInternalOnly>
+
+**Note:** The Relay compiler will maintain any directives supported by your server (such as `@include` or `@skip`) so they remain part of the request to the GraphQL server and won't alter generated runtime artifacts. Additional directives are documented [here](https://www.internalfb.com/intern/wiki/GraphQL/APIs_and_References/Directives/#graphql-standard).
+
+</FbInternalOnly>
+
+## `@arguments`
+
+`@arguments` is a directive used to pass arguments to a fragment that was
+defined using [`@argumentDefinitions`](#argumentdefinitions). For example:
+
+```graphql
+query TodoListQuery($userID: ID) {
+  ...TodoList_list @arguments(count: $count, userID: $userID) # Pass arguments here
+}
+```
+
+## `@argumentDefinitions`
+
+`@argumentDefinitions` is a directive used to specify arguments taken by a
+fragment. For example:
+
+```graphql
+fragment TodoList_list on TodoList
+@argumentDefinitions(
+  count: {type: "Int", defaultValue: 10} # Optional argument
+  userID: {type: "ID"} # Required argument
+) {
+  title
+  todoItems(userID: $userID, first: $count) {
+    # Use fragment arguments here as variables
+    ...TodoItem_item
+  }
+}
+```
+
+### Provided Variables
+
+A provided variable is a special fragment variable whose value is supplied by a
+specified provider function at runtime. This simplifies supplying device
+attributes, user experiment flags, and other runtime constants to graphql
+fragments.
+
+To add a provided variable:
+
+- add an argument with `provider: "[JSModule].relayprovider"` to
+  `@argumentDefinitions`
+- ensure that `[JSModule].relayprovider.js` exists and exports a `get()`
+  function
+  - `get` should return the same value on every call for a given run.
+
+```graphql
+fragment TodoItem_item on TodoList
+@argumentDefinitions(
+  include_timestamp: {
+    type: "Boolean!"
+    provider: "Todo_ShouldIncludeTimestamp.relayprovider"
+  }
+) {
+  timestamp @include(if: $include_timestamp)
+  text
+}
+```
+
+```javascript
+// Todo_ShouldIncludeTimestamp.relayprovider.js
+export default {
+  get(): boolean {
+    // must always return true or false for a given run
+    return check('todo_should_include_timestamp');
+  },
+};
+```
+
+Notes:
+
+<FbInternalOnly>
+
+- Even though fragments declare provided variables in `argumentDefinitions`,
+  their parent cannot pass provided variables through `@arguments`.
+- An argument definition cannot specify both a provider and a defaultValue.
+- If the modified fragment is included in operations that use hack preloaders
+  (`@preloadable(hackPreloader: true)`), you will need to manually add provided
+  variables when calling `RelayPreloader::gen`.
+  - Hack's typechecker will fail with
+    `The field __relay_internal__pv__[JsModule] is missing.`
+  - We strongly encourage switching to
+    [Entrypoints](../../guides/entrypoints/using-entrypoints/) if possible.
+- _Unstable / subject to change_
+  - Relay transforms provided variables to operation root variables and renames
+    them to `__relay_internal__pv__[JsModule]`.
+    - Only relevant if you are debugging a query that uses provided variables.
+
+</FbInternalOnly>
+
+<OssOnly>
+
+- Even though fragments declare provided variables in `argumentDefinitions`,
+  their parent cannot pass provided variables through `@arguments`.
+- An argument definition cannot specify both a provider and a defaultValue.
+- _Unstable / subject to change_
+  - Relay transforms provided variables to operation root variables and renames
+    them to `__relay_internal__pv__[JsModule]`.
+    - Only relevant if you are debugging a query that uses provided variables.
+
+</OssOnly>
+
+## `@catch`
+
+`@catch` is a directive you can add to fields, fragments, queries, mutations,
+and aliased inline fragments in your Relay queries to declare how field-level
+errors are handled in runtime.
+
+See also [the @catch guide](../../guides/catch-directive/).
+
+## `@connection(key: String!, filters: [String])`
+
+With `usePaginationFragment`, Relay expects connection fields to be annotated
+with a `@connection` directive. For more detailed information and an example,
+check out the
+[docs on `usePaginationFragment`](../../guided-tour/list-data/rendering-connections).
+
+## `@refetchable(queryName: String!, directives: [String], preferFetchable: Boolean)`
+
+With `useRefetchableFragment` and `usePaginationFragment`, Relay expects a
+`@refetchable` directive. 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). 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`. For more
+detailed information and examples, check out the docs on
+[`useRefetchableFragment`](../use-refetchable-fragment/) or
+[`usePaginationFragment`](../use-pagination-fragment/).
+
+Optionally, you can pass in a list of directives to add to the autogenerated
+query. For example, this can be used to add the `@relay_test_operation`
+directive for [testing](../../guides/testing-relay-components):
+
+[Optional] `preferFetchable: Boolean`
+
+This argument tells the Relay compiler to prefer generating
+`fetch_MyType(): MyType` queries for types that implement the `Node` interface.
+This is useful for schemas that have adopted the `@strong` and `@fetchable`
+server annotations for types. You can directly fetch concrete objects without
+needing to refine `Node` interface to a specific type.
+
+```javascript
+graphql`
+  fragment FriendsListComponent_user on User
+  @refetchable(
+    queryName: "FriendsListFetchQuery"
+    directives: ["@relay_test_operation"]
+  ) {
+    ...
+  }
+`;
+```
+
+## `@relay(plural: Boolean)`
+
+When defining a fragment for use with `useFragment`, you can use the
+`@relay(plural: true)` directive to indicate that the hook expects the prop for
+that fragment to be a list of items instead of a single item. A query or parent
+that spreads a `@relay(plural: true)` fragment should do so within a plural
+field (ie a field backed by a
+[GraphQL list](http://graphql.org/learn/schema/#lists-and-non-null). For
+example:
+
+```javascript
+// Plural fragment definition
+graphql`
+  fragment TodoItems_items on TodoItem @relay(plural: true) {
+    id
+    text
+  }
+`;
+
+// Plural fragment usage: note the parent type is a list of items (`TodoItem[]`)
+fragment TodoApp_app on App {
+  items {
+    // parent type is a list here
+    ...TodoItem_items
+  }
+}
+```
+
+## `@required`
+
+`@required` is a directive you can add to fields in your Relay queries to
+declare how null values should be handled at runtime.
+
+See also [the @required guide](../../guides/required-directive/).
+
+## `@throwOnFieldError`
+
+`@throwOnFieldError` is a directive you can add to your Relay queries and fragments to have Relay throw if any field errors are encountered when reading the query or fragment. Adding the directive will allow Relay to generate non-null types for any fields marked as `@semanticNonNull` in the schema.
+
+See also [the @throwOnFieldError guide](../../guides/throw-on-field-error-directive/).
+
+**Read more about Relay's experimental support for
+[Semantic Nullability](../../guides/semantic-nullability.mdx).**
+
+## `@semanticNonNull`
+
+The `@semanticNonNull` directive can be added to fields in your schema to
+indicate that the field is non-nullable in the semantic sense, but that the
+client should still be prepared to handle errors.
+
+**Read more about Relay's experimental support for
+[Semantic Nullability](../../guides/semantic-nullability.mdx).**
+
+## `@alias`
+
+`@alias` is a directive that allows you to give a fragment spread or inline
+fragment an alias, similar to a field alias. This is useful when you want to
+conditionally include a fragment and check if it was fetched, or otherwise group
+data together.
+
+For fragment spreads, the alias will default to the fragment name. For inline
+fragments, the alias will default to the type name. If you wish to supply your
+own name, or you have an inline fragment without any type condition, you can
+specify the alias using the `as` argument.
+
+```graphql
+fragment MyFragment on User {
+  ... on User @alias(as: "myGreatAlias") {
+    name
+  }
+}
+```
+
+See also [the @alias guide](../../guides/alias-directive/).
+
+## `@inline`
+
+The hooks APIs that Relay exposes allow you to read data from the store only
+during the render phase. In order to read data from outside of the render phase
+(or from outside of React), Relay exposes the `@inline` directive. The data from
+a fragment annotated with `@inline` can be read using `readInlineData`.
+
+In the example below, the function `processItemData` is called from a React
+component. It requires an item object with a specific set of fields. All React
+components that use this function should spread the `processItemData_item`
+fragment to ensure all of the correct item data is loaded for this function.
+
+```javascript
+import {graphql, readInlineData} from 'react-relay';
+
+// non-React function called from React
+function processItemData(itemRef) {
+  const item = readInlineData(
+    graphql`
+      fragment processItemData_item on Item @inline {
+        title
+        price
+        creator {
+          name
+        }
+      }
+    `,
+    itemRef,
+  );
+  sendToThirdPartyApi({
+    title: item.title,
+    price: item.price,
+    creatorName: item.creator.name,
+  });
+}
+```
+
+```javascript
+export default function MyComponent({item}) {
+  function handleClick() {
+    processItemData(item);
+  }
+
+  const data = useFragment(
+    graphql`
+      fragment MyComponent_item on Item {
+        ...processItemData_item
+        title
+      }
+    `,
+    item,
+  );
+
+  return <button onClick={handleClick}>Process {item.title}</button>;
+}
+```
+
+## `@relay(mask: Boolean)`
+
+It is not recommended to use `@relay(mask: false)`. Please instead consider
+using the `@inline` fragment.
+
+`@relay(mask: false)` can be used to prevent data masking; when including a
+fragment and annotating it with `@relay(mask: false)`, its data will be
+available directly to the parent instead of being masked for a different
+container.
+
+Applied to a fragment definition, `@relay(mask: false)` changes the generated
+Flow types to be better usable when the fragment is included with the same
+directive. The Flow types will no longer be exact objects and no longer contain
+internal marker fields.
+
+This may be helpful to reduce redundant fragments when dealing with nested or
+recursive data within a single Component.
+
+Keep in mind that it is typically considered an **anti-pattern** to create a
+single fragment shared across many containers. Abusing this directive could
+result in over-fetching in your application.
+
+In the example below, the `user` prop will include the data for `id` and `name`
+fields wherever `...Component_internUser` is included, instead of Relay's normal
+behavior to mask those fields:
+
+```javascript
+graphql`
+  fragment Component_internUser on InternUser @relay(mask: false) {
+    id
+    name
+  }
+`;
+```
+
+## `@waterfall`
+
+With [Relay Resolvers](../../guides/relay-resolvers/introduction.mdx) it's
+possible to create client-defined edges in the graph which point to server
+types. When reading these edge fields, Relay is forced to lazily fetch the
+server data for the edge. This will force Relay to make a second request to the
+server to fetch the data for the edge.
+
+To highlight this tradeoff both in the editor and during code review, the Relay
+compiler expects all reads of these fields to be annotated as `@waterfall`.
+
+```graphql
+fragment EditPost on DraftPost {
+  author @waterfall {
+    name
+  }
+}
+```
+
+See the [Return Type](../../guides/relay-resolvers/return-types.mdx#server-types)
+portion of the Relay Resolvers guide for more information.
+
+<DocsRating />

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

@@ -0,0 +1,16 @@
+### Behavior
+
+* It is expected for `useLazyLoadQuery` to have been rendered under a [`RelayEnvironmentProvider`](../relay-environment-provider), in order to access the correct Relay environment, otherwise an error will be thrown.
+* Calling `useLazyLoadQuery`  will fetch and render the data for this query, and it may [*_suspend_*](../../guided-tour/rendering/loading-states) while the network request is in flight, depending on the specified `fetchPolicy`, and whether cached data is available, or if it needs to send and wait for a network request. If `useLazyLoadQuery` causes the component to suspend, you'll need to make sure that there's a `Suspense` ancestor wrapping this component in order to show the appropriate loading state.
+    * For more details on Suspense, see our [Loading States with Suspense](../../guided-tour/rendering/loading-states/) guide.
+* The component is automatically subscribed to updates to the query data: if the data for this query is updated anywhere in the app, the component will automatically re-render with the latest updated data.
+* After a component using `useLazyLoadQuery` has committed, re-rendering/updating the component will not cause the query to be fetched again.
+    * If the component is re-rendered with *different query variables,* that will cause the query to be fetched again with the new variables, and potentially re-render with different data.
+    * If the component *unmounts and remounts*, that will cause the current query and variables to be refetched (depending on the `fetchPolicy` and the state of the cache).
+
+### Differences with `QueryRenderer`
+
+* `useLazyLoadQuery` no longer takes a Relay environment as a parameter, and thus no longer sets the environment in React Context, like `QueryRenderer` did. Instead, `useLazyLoadQuery` should be used as a descendant of a [`RelayEnvironmentProvider`](../relay-environment-provider), which now sets the Relay environment in Context. Usually, you should render a single `RelayEnvironmentProvider` at the very root of the application, to set a single Relay environment for the whole application.
+* `useLazyLoadQuery` will use [Suspense](../../guided-tour/rendering/loading-states) to allow developers to render loading states using Suspense boundaries, and will throw errors if network errors occur, which can be caught and rendered with Error Boundaries. This as opposed to providing error objects or null props to the `QueryRenderer` render function to indicate errors or loading states.
+* `useLazyLoadQuery` fully supports fetch policies in order to reuse data that is cached in the Relay store instead of solely relying on the network response cache.
+* `useLazyLoadQuery` has better type safety guarantees for the data it returns, which was not possible with QueryRenderer since we couldn't parametrize the type of the data with a renderer api.

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

@@ -0,0 +1,84 @@
+---
+id: load-query
+title: loadQuery
+slug: /api-reference/load-query/
+description: API reference for loadQuery, which imperatively fetches data for a query, retains that query and returns a query reference
+keywords:
+  - preload
+  - fetch
+  - query
+  - render-as-you-fetch
+  - retain
+  - query reference
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## `loadQuery`
+
+This function is designed to be used with the `usePreloadedQuery()` hook to implement the "render-as-you-fetch".
+
+Query references returned from `loadQuery` will leak data into the Relay store if `.dispose()` is not called on them once they are no longer referenced. As such, prefer calling `useQueryLoader` when possible, which ensures that query references are disposed for you.
+
+See the [`usePreloadedQuery`](../use-preloaded-query) docs for a more complete example.
+
+```js
+const MyEnvironment = require('MyEnvironment');
+const {loadQuery} = require('react-relay');
+
+const query = graphql`
+  query AppQuery($id: ID!) {
+    user(id: $id) {
+      name
+    }
+  }
+`;
+
+// Note: you should generally not call loadQuery at the top level.
+// Instead, it should be called in response to an event (such a route navigation,
+// click, etc.).
+const queryReference = loadQuery(
+  MyEnvironment,
+  query,
+  {id: '4'},
+  {fetchPolicy: 'store-or-network'},
+);
+
+// later: pass queryReference to usePreloadedQuery()
+// Note that query reference should have .dispose() called on them,
+// which is missing in this example.
+```
+
+### Arguments
+
+* `environment`: A Relay Environment instance on which to execute the request. If you're starting this request somewhere within a React component, you probably want to use the environment you obtain from using [`useRelayEnvironment`](#userelayenvironment).
+* `query`: GraphQL query to fetch, specified using a `graphql` template literal, or a preloadable concrete request, which can be acquired by requiring the file `<name-of-query>$Parameters.graphql`. Relay will only generate the `$Parameters` file if the query is annotated with `@preloadable`.
+* `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`: Determines if cached data should be used, and whether 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.
+* `environmentProviderOptions`: *[Optional]* options object
+    * Options passed to an `environmentProvider` used in `prepareSurfaceEntryPoint.js`.
+
+### Return Value
+
+A query reference with the following properties:
+
+* `dispose`: a method that will release the query reference from being retained by the store. This can cause the data referenced by the query reference to be garbage collected.
+
+The exact format of the return value is *unstable and highly likely to change*. We strongly recommend not using any other properties of the return value, as such code would be highly likely to break when upgrading to future versions of Relay. Instead, pass the result of `loadQuery()` to `usePreloadedQuery()`.
+
+### Behavior
+
+* `loadQuery()` 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`.
+* the query reference returned from `loadQuery` will be retained by the Relay store, preventing the data from being garbage collected. Once you call `.dispose()` on the query reference, it can be garbage collected.
+* `loadQuery()` will throw an error if it is called during React's render phase.
+
+
+
+
+<DocsRating />

package/llm-docs/api-reference/hooks/relay-environment-provider.mdx

@@ -0,0 +1,78 @@
+---
+id: relay-environment-provider
+title: RelayEnvironmentProvider
+slug: /api-reference/relay-environment-provider/
+description: API reference for RelayEnvironmentProvider, which sets a Relay environment in React context
+keywords:
+  - environment
+  - context
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+## `RelayEnvironmentProvider`
+
+This component is used to set a Relay environment in React Context. Usually, a *single* instance of this component should be rendered at the very root of the application, in order to set the Relay environment for the whole application:
+
+```js
+const React = require('React');
+const {
+  Store,
+  RecordSource,
+  Environment,
+  Network,
+  Observable,
+} = require("relay-runtime");
+
+const {RelayEnvironmentProvider} = require('react-relay');
+
+/**
+ * Custom fetch function to handle GraphQL requests for a Relay environment.
+ *
+ * This function is responsible for sending GraphQL requests over the network and returning
+ * the response data. It can be customized to integrate with different network libraries or
+ * to add authentication headers as needed.
+ *
+ * @param {RequestParameters} params - The GraphQL request parameters to send to the server.
+ * @param {Variables} variables - Variables used in the GraphQL query.
+ */
+function fetchFunction(params, variables) {
+  const response = fetch("http://my-graphql/api", {
+    method: "POST",
+    headers: [["Content-Type", "application/json"]],
+    body: JSON.stringify({
+      query: params.text,
+      variables,
+    }),
+  });
+
+  return Observable.from(response.then((data) => data.json()));
+};
+
+/**
+ * Creates a new Relay environment instance for managing (fetching, storing) GraphQL data.
+ */
+function createEnvironment() {
+  const network = Network.create(fetchFunction);
+  const store = new Store(new RecordSource());
+  return new Environment({ store, network });
+}
+
+const environment = createEnvironment();
+
+function Root() {
+  return (
+    <RelayEnvironmentProvider environment={environment}>
+      <App />
+    </RelayEnvironmentProvider>
+  );
+}
+
+module.exports = Root;
+```
+
+### Props
+
+* `environment`: The Relay environment to set in React Context. Any Relay Hooks (like [`useLazyLoadQuery`](../use-lazy-load-query) or [`useFragment`](../use-fragment)) used in descendants of this provider component will use the Relay environment specified here
+
+<DocsRating/>

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

@@ -0,0 +1,65 @@
+---
+id: use-client-query
+title: useClientQuery
+slug: /api-reference/use-client-query/
+description: API reference for useClientQuery, a React hook used to render client only queries
+keywords:
+  - query
+  - read
+  - client-query
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+`useClientQuery` hook is used to render queries that read _only_ client fields.
+
+The Relay Compiler fully supports [client-side extensions](../../guides/client-schema-extensions/) of the schema, which allows you to define local fields and types.
+
+```graphql
+# example client extension of the `Query` type
+extend type Query {
+  client_field: String
+}
+```
+
+These client-only fields are not sent to the server, and should be updated
+using APIs for local updates, for example `commitPayload`.
+
+```js
+const React = require('React');
+
+const {graphql, useClientQuery} = require('react-relay');
+
+function ClientQueryComponent() {
+  const data = useClientQuery(
+    graphql`
+      query ClientQueryComponentQuery {
+        client_field
+      }
+    `,
+    {}, // variables
+  );
+
+  return (
+    <div>{data.client_field}</div>
+  );
+}
+```
+
+
+### Arguments
+
+* `query`: 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.
+
+### 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 |} |}`.
+
+### Behavior
+
+* This hooks works as [`useLazyLoadQuery`](../use-lazy-load-query) with `fetchPolicy: store-only`, it does not send the network request.
+
+
+<DocsRating />

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

@@ -0,0 +1,69 @@
+---
+id: use-fragment
+title: useFragment
+slug: /api-reference/use-fragment/
+description: API reference for useFragment, a React hook used to read fragment data from the Relay store using a fragment reference
+keywords:
+  - fragment
+  - read
+  - fragment reference
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+## `useFragment`
+
+```js
+import type {UserComponent_user$key} from 'UserComponent_user.graphql';
+
+const React = require('React');
+
+const {graphql, useFragment} = require('react-relay');
+
+type Props = {
+  user: UserComponent_user$key,
+};
+
+function UserComponent(props: Props) {
+  const data = useFragment(
+    graphql`
+      fragment UserComponent_user on User {
+        name
+        profile_picture(scale: 2) {
+          uri
+        }
+      }
+    `,
+    props.user,
+  );
+
+  return (
+    <>
+      <h1>{data.name}</h1>
+      <div>
+        <img src={data.profile_picture?.uri} />
+      </div>
+    </>
+  );
+}
+```
+
+### Arguments
+
+* `fragment`: GraphQL fragment specified using a `graphql` template literal.
+* `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
+
+* `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. For example, the type of `data` above is: `{ name: ?string, profile_picture: ?{ uri: ?string } }`.
+
+### 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.
+
+
+<DocsRating />