relay-runtime 20.1.1 → 21.0.1

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

@@ -0,0 +1,122 @@
+---
+id: use-refetchable-fragment
+title: useRefetchableFragment
+slug: /api-reference/use-refetchable-fragment/
+description: API reference for useRefetchableFragment, a React hook used to refetch fragment data
+keywords:
+  - refetch
+  - fragment
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+// @fb-only
+
+## `useRefetchableFragment`
+
+You can use `useRefetchableFragment` when you want to fetch and re-render a fragment with different data:
+
+<FbInternalOnly>
+  // @fb-only
+</FbInternalOnly>
+
+<OssOnly>
+
+```js
+import type {CommentBody_comment$key} from 'CommentBody_comment.graphql';
+
+const React = require('React');
+
+const {graphql, useRefetchableFragment} = require('react-relay');
+
+
+type Props = {
+  comment: CommentBody_comment$key,
+};
+
+function CommentBody(props: Props) {
+  const [data, refetch] = useRefetchableFragment(
+    graphql`
+      fragment CommentBody_comment on Comment
+      @refetchable(queryName: "CommentBodyRefetchQuery") {
+        body(lang: $lang) {
+          text
+        }
+      }
+    `,
+    props.comment,
+  );
+
+  return (
+    <>
+      <p>{data.body?.text}</p>
+      <Button
+        onClick={() => {
+          refetch({lang: 'SPANISH'}, {fetchPolicy: 'store-or-network'})
+        }}
+      >
+        Translate Comment
+      </Button>
+    </>
+  );
+}
+
+module.exports = CommentBody;
+```
+
+</OssOnly>
+
+### Arguments
+
+* `fragment`: GraphQL fragment specified using a `graphql` template literal. 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` and has the capability to be queried by its `id` field. See [graphql server specification section](../../guides/graphql-server-specification) for more details).
+    * Note that you *do not* need to manually specify a refetch 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>
+  // @fb-only
+</FbInternalOnly>
+
+<OssOnly>
+
+Tuple containing the following values
+
+* [0] `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.
+* [1] `refetch`: Function used to refetch the 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.
+            * If the fragment key passed to `useRefetchableFragment` is optional then all non-optional variables must be passed including, potentially, the object's ID since Relay may not have any existing variables to reuse.
+            * If the fragment key is non-optional, 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, if the fragment key is non-optional, passing an `id` value for the `$id` variable is _*optional*_, unless the fragment wants to be refetched with a different `id`. When refetching a non-nullable `@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.
+
+### Differences with `RefetchContainer`
+
+* A refetch query no longer needs to be specified in this api, since it will be automatically generated by Relay by using a `@refetchable` fragment.
+* Refetching no longer has a distinction between `refetchVariables` and `renderVariables`, 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 from the parent query).
+* Refetching will unequivocally update the component, which was not always true when calling refetch from `RefetchContainer` (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-relay-environment.mdx

@@ -0,0 +1,37 @@
+---
+id: use-relay-environment
+title: useRelayEnvironment
+slug: /api-reference/use-relay-environment/
+description: API reference for useRelayEnvironment, a React hook used to access the Relay environment from context
+keywords:
+  - environment
+  - context
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+## `useRelayEnvironment`
+
+Hook used to access a Relay environment that was set by a [`RelayEnvironmentProvider`](../relay-environment-provider):
+
+```js
+const React = require('React');
+
+const {useRelayEnvironment} = require('react-relay');
+
+function MyComponent() {
+  const environment = useRelayEnvironment();
+
+  const handler = useCallback(() => {
+    // For example, can be used to pass the environment to functions
+    // that require a Relay environment.
+    commitMutation(environment, ...);
+  }, [environment])
+
+  return (...);
+}
+
+module.exports = MyComponent;
+```
+
+<DocsRating />

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

@@ -0,0 +1,66 @@
+---
+id: use-subscription
+title: useSubscription
+slug: /api-reference/use-subscription/
+description: API reference for useSubscription, a React hook used to subscribe and unsubscribe from a subscription
+keywords:
+  - subscription
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+import GraphQLSubscriptionConfig from '../types/GraphQLSubscriptionConfig.mdx';
+
+## `useSubscription`
+
+Hook used to subscribe and unsubscribe to a subscription.
+
+```js
+import {graphql, useSubscription} from 'react-relay';
+import {useMemo} from 'react';
+
+const subscription = graphql`
+  subscription UserDataSubscription($input: InputData!) {
+    # ...
+  }
+`;
+
+function UserComponent({ id }) {
+  // IMPORTANT: your config should be memoized.
+  // Otherwise, useSubscription will re-render too frequently.
+  const config = useMemo(() => ({
+    variables: {id},
+    subscription,
+  }), [id, subscription]);
+
+  useSubscription(config);
+
+  return (/* ... */);
+}
+```
+
+### Arguments
+
+* `config`: a memoized config of type [`GraphQLSubscriptionConfig`](#type-graphqlsubscriptionconfigtsubscriptionpayload) passed to [`requestSubscription`](../request-subscription/)
+* `requestSubscriptionFn`: `?<TSubscriptionPayload>(IEnvironment, GraphQLSubscriptionConfig<TSubscriptionPayload>) => Disposable`. An optional function with the same signature as [`requestSubscription`](../request-subscription/), which will be called in its stead. Defaults to `requestSubscription`.
+
+<GraphQLSubscriptionConfig />
+
+### Behavior
+
+* This is only a thin wrapper around the `requestSubscription` API. It will:
+  * Subscribe when the component is mounted with the given config
+  * Unsubscribe when the component is unmounted
+  * Unsubscribe and resubscribe with new values if the environment, config or `requestSubscriptionFn` changes.
+* If you have the need to do something more complicated, such as imperatively requesting a subscription, please use the [`requestSubscription`](../request-subscription/) API directly.
+* See the [GraphQL Subscriptions Guide](../../guided-tour/updating-data/graphql-subscriptions/) for a more detailed explanation of how to work with subscriptions.
+
+<FbInternalOnly>
+
+:::note
+`useSubscription` doesn't automatically add `client_subscription_id`. You may need to provide an arbitrary `client_subscription_id` to `config.variables.input`
+:::
+
+</FbInternalOnly>
+
+<DocsRating />

package/llm-docs/api-reference/relay-resolvers/docblock-format.mdx

@@ -0,0 +1,321 @@
+---
+id: docblock-format
+title: 'Docblock Format'
+slug: /api-reference/relay-resolvers/docblock-format/
+description: Docblock format for Relay Resolvers
+---
+import {FbInternalOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Relay Resolvers allow you to define additional types and fields in your GraphQL schema that are backed by client-side data. To achieve this, the Relay compiler looks for special `@relayType` and `@relayField` docblocks in your code. These docblocks define the types and fields in your schema and also tell Relay where to find the resolver functions that implement them.
+
+For an overview of Relay Resolvers and how to think about them, see the [Relay Resolvers](../../guides/relay-resolvers/introduction.mdx) guide. This page documents the different docblock tags that the Relay compiler looks for, and how to use them.
+
+:::note The Relay compiler only looks at docblocks which include the
+`@relayType` or `@relayField` tag. Any other docblocks will be ignored.
+:::
+
+## `@relayType TypeName`
+
+The `@relayType` tag followed by a single name defines a new GraphQL type in your schema. By default it is expected to be followed by an exported function whose name matches the type name. The function should accept an ID as its sole argument and return the JavaScript model/object which is the backing data for the type. See [`@weak`](#weak) for an alternative way to define the backing data for a type.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+  ```tsx
+  /**
+   * @relayType User
+   */
+  export function User(id): UserModel {
+    return UserModel.getById(id);
+  }
+  ```
+  </TabItem>
+  <TabItem value="Flow">
+
+  ```tsx
+  /**
+   * @relayType
+   */
+  export function User(id): UserModel {
+    return UserModel.getById(id);
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+
+
+See the [Defining Types](../../guides/relay-resolvers/defining-types.mdx) guide for more information.
+
+## `@relayField TypeName.fieldName: FieldTypeName`
+
+If the typename in a `@relayField` tag is followed by a dot and then a field definition, it defines a new field on the type. The portion following the `.` is expected to follow GraphQL's
+[schema definition language](https://spec.graphql.org/June2018/#FieldDefinition).
+
+Field definitions are expected to be followed by an exported function whose name matches the field name. The function should accept the model/object returned by the type resolver as its sole argument and return the value of the field.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+  ```tsx
+  /**
+   * @relayField User.name: String
+   */
+  export function name(user: UserModel): string {
+    return user.name;
+  }
+  ```
+  </TabItem>
+  <TabItem value="Flow">
+
+  ```tsx
+  /**
+   * @relayType
+   */
+  export function name(user: UserModel): string {
+    return user.name;
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+See the [Defining Fields](../../guides/relay-resolvers/defining-fields.mdx) guide for more information.
+
+## `@rootFragment`
+
+Relay Resolvers may also be used to model data that is derived from other data in the graph. These fields will be automatically recomputed by Relay when the data they depend on changes.
+
+To define a derived field, use the `@rootFragment` tag on an existing field
+definition, and follow it with the name of a fragment that defines the data that the field depends on. The resolver function for the field will be passed a fragment key which can be used to read the fragment data using `readFragment()`.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+  ```tsx
+  import {readFragment} from 'relay-runtime';
+
+  /**
+   * @relayField User.fullName: String
+   * @rootFragment UserFullNameFragment
+   */
+  export function fullName(key: UserFullNameFragment$key): string {
+    const user = readFragment(
+      graphql`
+        fragment UserFullNameFragment on User {
+          firstName
+          lastName
+        }
+      `,
+      key,
+    );
+    return `${user.firstName} ${user.lastName}`;
+  }
+  ```
+  </TabItem>
+  <TabItem value="Flow">
+
+  ```tsx
+  import {readFragment} from 'relay-runtime';
+
+  /**
+   * @relayType
+   */
+  export function fullName(key: UserFullNameFragment$key): string {
+    const user = readFragment(
+      graphql`
+        fragment UserFullNameFragment on User {
+          firstName
+          lastName
+        }
+      `,
+      key,
+    );
+    return `${user.firstName} ${user.lastName}`;
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+See [Derived Fields](../../guides/relay-resolvers/derived-fields.mdx) for more information.
+
+## `@live`
+
+When modeling client state that can change over time, a resolver function which returns a single value is not sufficient. To accommodate this, Relay Resolvers allow you to define a field that returns a stream of values over time. This is done by adding the `@live` tag to a _field or type definition_.
+
+`@live` resolvers must return an object with the shape of a `LiveStateValue` to allow Relay to read the current value and subscribe to changes.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+  ```tsx
+  import type {LiveState} from 'relay-runtime';
+
+  /**
+  * @relayField Query.counter: Int
+  * @live
+  */
+  export function counter(): LiveState<number> {
+    return {
+      read: () => store.getState().counter,
+      subscribe: cb => {
+        return store.subscribe(cb);
+      },
+    };
+  }
+  ```
+  </TabItem>
+  <TabItem value="Flow">
+
+  ```tsx
+  import type {LiveState} from 'relay-runtime';
+
+  /**
+  * @relayType
+  */
+  export function counter(): LiveState<number> {
+    return {
+      read: () => store.getState().counter,
+      subscribe: cb => {
+        return store.subscribe(cb);
+      },
+    };
+  }
+  ```
+
+  </TabItem>
+</Tabs>
+
+See the [Live Fields](../../guides/relay-resolvers/live-fields.mdx) guide for
+more information.
+
+## `@weak`
+
+By default, Relay Resolvers expect the backing data for a type to be returned by a resolver function. However, in some cases objects of a given type may not have identifiers. In this case, you can use the `@relayType TypeName` syntax described above followed by the tag `@weak` to define a "weak" type.
+
+Weak type declarations are expected to be followed by an exported type
+definition whose name matches the type name.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+  ```tsx
+  /**
+  * @relayType ProfilePicture
+  * @weak
+  */
+  export type ProfilePicture = {
+    url: string;
+    width: number;
+    height: number;
+  };
+  ```
+  </TabItem>
+  <TabItem value="Flow">
+
+  ```tsx
+  /**
+  * @relayType
+  */
+  export type ProfilePicture = {
+    url: string;
+    width: number;
+    height: number;
+  };
+  ```
+  </TabItem>
+</Tabs>
+
+See the [Weak Types](../../guides/relay-resolvers/defining-types.mdx#Defining a “weak” type) guide for more information including how to define an edge to a weak type.
+
+## `@deprecated`
+
+Just like the GraphQL schema definition language, Relay Resolvers support the `@deprecated` tag to mark a field as deprecated. The tag may be followed by a string which will be used as the deprecation reason. Deprecated fields will
+receive special treatment in the editor if you are using the
+[Relay VSCode extension](../../editor-support.mdx).
+
+```tsx
+/**
+ * @relayField User.name: String
+ * @deprecated Use `fullName` instead.
+ */
+export function name(user: UserModel): string {
+  return user.name;
+}
+```
+
+See the [Deprecated](../../guides/relay-resolvers/deprecated.mdx) guide for more information.
+
+## Descriptions
+
+Any free text in the docblock (text not following a tag) will be used as the description for the type or field. This description will be surfaced in the editor if you are using the [Relay VSCode extension](../../editor-support.mdx).
+
+```tsx
+/**
+ * @relayField User.name: String
+ *
+ * What's in a name? That which we call a rose by any other name would smell
+ * just as sweet.
+ */
+export function name(user: UserModel): string {
+  return user.name;
+}
+```
+
+See the [Descriptions](../../guides/relay-resolvers/descriptions.mdx) guide for more information.

package/llm-docs/api-reference/relay-resolvers/runtime-functions.mdx

@@ -0,0 +1,94 @@
+---
+id: runtime-functions
+title: "Runtime Functions"
+slug: /api-reference/relay-resolvers/runtime-functions/
+description: Runtime functions associated with Relay Resolvers
+---
+
+This page documents the runtime functions associated with Relay Resolvers. For an overview of Relay Resolvers and how to think about them, see the [Relay Resolvers](../../guides/relay-resolvers/introduction.mdx) guide.
+
+## RelayModernStore
+
+
+RelayModernStore exposes `batchLiveStateUpdates()`. See [Live Fields](../../guides/relay-resolvers/live-fields.mdx#batching) for more details of how to use this method.
+
+## `readFragment()`
+
+Derived resolver fields model data that is derived from other data in the graph. To read the data that a derived field depends on, they must use the `readFragment()` function which is exported from `relay-runtime`. This function accepts a GraphQL fragment and a fragment key, and returns the data for the fragment.
+
+:::warning
+`readFragment()` may only be used in Relay Resolvers. It will throw an error if used in any other context.
+:::
+
+```tsx
+import {readFragment} from "relay-runtime";
+
+/**
+ * @relayField User.fullName: String
+ * @rootFragment UserFullNameFragment
+ */
+export function fullName(key: UserFullNameFragment$key): string {
+  const user = readFragment(graphql`
+    fragment UserFullNameFragment on User {
+      firstName
+      lastName
+    }
+  `, key);
+  return `${user.firstName} ${user.lastName}`;
+}
+```
+
+Note that Relay will ensure your field resolver is recomputed any time data in that fragment changes.
+
+See the [Derived Fields](../../guides/relay-resolvers/derived-fields.mdx) guide for more information.
+
+## `suspenseSentinel()`
+
+Live resolvers model client state that can change over time. If at some point during that field's lifecycle, the data being read is in a pending state, for example if the data is being fetched from an API, the resolver may return the `suspenseSentinel()` to indicate that the data is not yet available.
+
+Relay expects that when the data is available, the `LiveStateValue` will notify Relay by calling the subscribe callback.
+
+```tsx
+import {suspenseSentinel} from 'relay-runtime';
+
+/**
+ * @relayField Query.myIp: String
+ * @live
+ */
+export function myIp(): LiveState<string> {
+  return {
+    read: () => {
+      const state = store.getState();
+      const ipLoadObject = state.ip;
+      if (ipLoadObject.status === "LOADING") {
+        return suspenseSentinel();
+      }
+      return state.ip;
+    },
+    subscribe: (callback) => {
+      return store.subscribe(callback);
+    },
+  };
+}
+```
+
+See the [Live Fields](../../guides/relay-resolvers/live-fields.mdx) guide for more information.
+
+## `useClientQuery()`
+
+If a query contains only client fields, it may not currently be used with hooks like `usePreloadedQuery` and `useLazyLoadQuery` since both of those hooks assume they will need to issue a network request. If you attempt to use these APIs in Flow you will get a type error.
+
+Instead, for client-only queries, you can use the `useClientQuery` hook:
+
+```tsx
+import {useClientQuery} from 'react-relay';
+
+export function MyComponent() {
+  const data = useClientQuery(graphql`
+    query MyQuery {
+      myIp
+    }
+  `);
+  return <div>{data.myIp}</div>;
+}
+```