relay-runtime 20.1.1 → 21.0.0

package/llm-docs/guided-tour/updating-data/imperatively-modifying-store-data.mdx

@@ -0,0 +1,275 @@
+---
+id: imperatively-modifying-store-data
+title: Imperatively modifying store data
+slug: /guided-tour/updating-data/imperatively-modifying-store-data/
+description: Using readUpdatableQuery to update scalar fields in the store
+keywords:
+- record source
+- store
+- updater
+- typesafe updaters
+- readUpdatableQuery
+- readUpdatableFragment
+- updatable
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+:::note
+See also [this guide on updating linked fields in the store](../imperatively-modifying-linked-fields).
+:::
+
+Data in Relay stores can be imperatively modified within updater functions.
+
+## When to use updaters
+
+### Complex client updates
+
+You might provide an updater function if the changes to local data are more complex than what can be achieved by simply writing a network response to the store and cannot be handled by the declarative mutation directives.
+
+### Client schema extensions
+
+In addition, since the network response necessarily will not include data for fields defined in client schema extensions, you may wish to use an updater to initialize data defined in client schema extensions.
+
+### Use of other APIs
+
+Lastly, there are things you can only achieve using updaters, such as invalidating nodes, deleting nodes, finding all connections at a given field, etc.
+
+### If multiple optimistic responses modify a given store value
+
+If two optimistic responses affect a given value, and the first optimistic response is rolled back, the second one will remain applied.
+
+For example, if two optimistic responses each increase a story's like count by one, and the first optimistic response is rolled back, the second optimistic response remains applied. However, it is **not recalculated**, and the value of the like count will remain increased by two.
+
+## When **not** to use updaters
+
+### To trigger other side effects
+
+You should use the `onCompleted` callback to trigger other side effects. `onCompleted` callbacks are guaranteed to be called once, but updaters and optimistic updaters can be called repeatedly.
+
+## The various types of updater functions
+
+The `useMutation` and `commitMutation` APIs accept configuration objects which can include `optimisticUpdater` and `updater` fields. The `requestSubscription` and `useSubscription` APIs accept configuration objects which can include `updater` fields.
+
+In addition, there is another API (`commitLocalUpdate`) which also accepts an updater function. It will be discussed in the [Other APIs for modifying local data](../local-data-updates/) section.
+
+## Optimistic updaters vs updaters
+
+Mutations can have both optimistic and regular updaters. Optimistic updaters are executed when a mutation is triggered. When that mutation completes or errors, the optimistic update is rolled back.
+
+Regular updaters are executed when a mutation completes successfully.
+
+## Example
+
+Let's construct an example in which an `is_new_comment` field (which is defined in a schema extension) is set to `true` on a newly created Feedback object in a mutation updater.
+
+```graphql
+# Feedback.graphql
+extend type Feedback {
+  is_new_comment: Boolean
+}
+```
+
+```js
+// CreateFeedback.js
+import type {Environment} from 'react-relay';
+import type {
+  FeedbackCreateData,
+  CreateFeedbackMutation,
+  CreateFeedbackMutation$data,
+} from 'CreateFeedbackMutation.graphql';
+
+const {commitMutation, graphql} = require('react-relay');
+const {ConnectionHandler} = require('relay-runtime');
+
+function commitCreateFeedbackMutation(
+  environment: Environment,
+  input: FeedbackCreateData,
+) {
+  return commitMutation<FeedbackCreateData>(environment, {
+    mutation: graphql`
+      mutation CreateFeedbackMutation($input: FeedbackCreateData!) {
+        feedback_create(input: $input) {
+          feedback {
+            id
+            # Step 1: in the mutation response, spread an updatable fragment (defined below).
+            # This updatable fragment will select the fields that we want to update on this
+            # particular feedback object.
+            ...CreateFeedback_updatable_feedback
+          }
+        }
+      }
+    `,
+    variables: {input},
+
+    // Step 2: define an updater
+    updater: (store: RecordSourceSelectorProxy, response: ?CreateCommentMutation$data) => {
+      // Step 3: Access and nullcheck the feedback object.
+      // Note that this could also have been achieved with the @required directive.
+      const feedbackRef = response?.feedback_create?.feedback;
+      if (feedbackRef == null) {
+        return;
+      }
+
+      // Step 3: call store.readUpdatableFragment
+      const {updatableData} = store.readUpdatableFragment(
+          // Step 4: Pass it a fragment literal, where the fragment contains the @updatable directive.
+          // This fragment selects the fields that you wish to update on the feedback object.
+          // In step 1, we spread this fragment in the query response.
+          graphql`
+            fragment CreateFeedback_updatable_feedback on Feedback @updatable {
+              is_new_comment
+            }
+          `,
+          // Step 5: Pass the fragment reference.
+          feedbackRef
+        );
+
+      // Step 6: Mutate the updatableData object!
+      updatableData.is_new_comment = true;
+    },
+  });
+}
+
+module.exports = {commit: commitCreateFeedbackMutation};
+```
+
+Let's distill what's going on here.
+
+* The `updater` accepts two parameters: a `RecordSourceSelectorProxy` and an optional object that is the result of reading out the mutation response.
+    * The type of this second argument is a nullable version of the `$data` type that is imported from the generated mutation file.
+    * The second argument contains just the data selected directly by the mutation argument. In other words, it will not contain any fields selected solely by spread fragments.
+* This `updater` is executed after the mutation response has been written to the store.
+* In this example updater, we do three things:
+  * First, we spread an updatable fragment in the mutation response.
+  * Second, we read out the fields selected by this fragment by calling `readUpdatableFragment`. This returns an updatable proxy object.
+  * Third, we update fields on this updatable proxy.
+* Once this updater completes, the updates that have been recorded are written to the store, and all affected components are re-rendered.
+
+## Example 2: Updating data in response to user interactions
+
+Let's consider the common case of updating store data in response to a user interaction.  In a click handler, let's a toggle an `is_selected` field. This field is defined on Users in a client schema extension.
+
+```graphql
+# User.graphql
+extend type User {
+  is_selected: Boolean
+}
+```
+
+```js
+// UserSelectToggle.react.js
+import type {RecordSourceSelectorProxy} from 'react-relay';
+import type {UserSelectToggle_viewer$key} from 'UserSelectToggle_viewer.graphql';
+
+const {useRelayEnvironment, commitLocalUpdate} = require('react-relay');
+
+function UserSelectToggle({ userId, viewerRef }: {
+  userId: string,
+  viewerRef: UserSelectToggle_viewer$key,
+}) {
+  const viewer = useFragment(graphql`
+    fragment UserSelectToggle_viewer on Viewer {
+      user(user_id: $user_id) {
+        id
+        name
+        is_selected
+        ...UserSelectToggle_updatable_user
+      }
+    }
+  `, viewerRef);
+
+  const environment = useRelayEnvironment();
+
+  return <button
+    onClick={() => {
+      commitLocalUpdate(
+        environment,
+        (store: RecordSourceSelectorProxy) => {
+          const userRef = viewer.user;
+          if (userRef == null) {
+            return;
+          }
+
+          const {updatableData} = store.readUpdatableFragment(
+            graphql`
+              fragment UserSelectToggle_updatable_user on User @updatable {
+                is_selected
+              }
+            `,
+            userRef
+          );
+
+          updatableData.is_selected = !viewer?.user?.is_selected;
+        }
+      );
+    }}
+  >
+    {viewer?.user?.is_selected ? 'Deselect' : 'Select'} {viewer?.user?.name}
+  </button>
+}
+```
+
+Let's distill what's going on here.
+
+* In a click handler, we call `commitLocalUpdate`, which accepts a Relay environment and an updater function. **Unlike in the previous examples, this updater does not accept a second parameter** because there is no associated network payload.
+* In this updater function, we access get an updatable proxy object by calling `store.readUpdatableFragment`, and toggle the `is_selected` field.
+* Like the previous example in which we called `readUpdatableFragment`, this can be rewritten to use the `readUpdatableQuery` API.
+
+:::note
+This example can be rewritten using the `environment.commitPayload` API, albeit without type safety.
+:::
+
+## Alternative API: `readUpdatableQuery`.
+
+In the previous examples, we used an updatable fragment to access the record whose fields we want to update. This can also be possible to do with an updatable query.
+
+If we know the path from the root (i.e. the object whose type is `Query`) to the record we wish to modify, we can use the `readUpdatableQuery` API to achieve this.
+
+For example, we could set the viewer's `name` field in response to an event as follows:
+
+```js
+// NameUpdater.react.js
+function NameUpdater({ queryRef }: {
+  queryRef: NameUpdater_viewer$key,
+}) {
+  const environment = useRelayEnvironment();
+  const data = useFragment(
+    graphql`
+      fragment NameUpdater_viewer on Viewer {
+        name
+      }
+    `,
+    queryRef
+  );
+  const [newName, setNewName] = useState(data?.viewer?.name);
+  const onSubmit = () => {
+    commitLocalUpdate(environment, store => {
+      const {updatableData} = store.readUpdatableQuery(
+        graphql`
+          query NameUpdaterUpdateQuery @updatable {
+            viewer {
+              name
+            }
+          }
+        `,
+        {}
+      );
+      const viewer = updatableData.viewer;
+      if (viewer != null) {
+        viewer.name = newName;
+      }
+    });
+  };
+
+  // etc
+}
+```
+
+* This particular example can be rewritten using `readUpdatableFragment`. However, you may prefer `readUpdatableQuery` for several reasons:
+  * You do not have ready access to a fragment reference, e.g. if the call to `commitLocalUpdate` is not obviously associated with a component.
+  * You do not have ready access to a fragment where we select the **parent record** of the record we wish to modify (e.g. the `Query` in this example). Due to a known type hole in Relay, **updatable fragments cannot be spread at the top level.**
+  * You wish to use variables in the updatable fragment. Currently, updatable fragments reuse the variables that were passed to the query. This means that you cannot, for example, have an updatable fragment with fragment-local variables and call `readUpdatableFragment` multiple times, each time passing different variables.
+
+<DocsRating />

package/llm-docs/guided-tour/updating-data/introduction.mdx

@@ -0,0 +1,25 @@
+---
+id: introduction
+title: Introduction
+slug: /guided-tour/updating-data/introduction
+description: Relay guide to updating data
+keywords:
+- updating
+- mutation
+- useMutation
+- commitMutation
+- relay store
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+In the Fetching Data section, we discuss how to fetch data using GraphQL queries. Though fetching data can have the *incidental* effect of modifying data in Relay's local store (if the fetched data has changed), we haven't discussed any ways to *intentionally* modify our locally stored data.
+
+This section will do just that: it will discuss how to update our local data store, and data on the server.
+
+:::note
+The **Relay store** is a cache of GraphQL data, associated with a given Relay environment, that we have encountered during the execution of an application.
+:::
+
+<DocsRating />

package/llm-docs/guided-tour/updating-data/local-data-updates.mdx

@@ -0,0 +1,71 @@
+---
+id: local-data-updates
+title: Local Data Updates
+slug: /guided-tour/updating-data/local-data-updates/
+description: Other APIs for modifying store data
+keywords:
+- client-only
+- commitLocalUpdate
+- commitPayload
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+// @fb-only
+
+There are a couple of APIs that Relay provides in order to make purely local updates to the Relay store (i.e. updates not tied to a server operation).
+
+Note that local data updates can be made both on [client-only data](../client-only-data/), or on regular data that was fetched from the server via an operation.
+
+## commitLocalUpdate
+
+To make updates using an [`updater`](../imperatively-modifying-store-data/) function, you can use the `commitLocalUpdate` API:
+
+```js
+import type {Environment} from 'react-relay';
+
+const {commitLocalUpdate, graphql} = require('react-relay');
+
+function commitCommentCreateLocally(
+  environment: Environment,
+  feedbackID: string,
+) {
+  return commitLocalUpdate(environment, store => {
+    // Imperatively mutate the store here
+  });
+}
+
+module.exports = {commit: commitCommentCreateLocally};
+```
+
+* `commitLocalUpdate` update simply takes an environment and an updater function.
+    * `updater` takes a *`store`* argument, which is an instance of a [`RecordSourceSelectorProxy`](../../../api-reference/store/);  this interface allows you to *imperatively* write and read data directly to and from the Relay store. This means that you have full control over how to update the store: you can *create entirely new records*, or *update or delete existing ones*.
+    * Unlike regular and optimistic updaters that are accepted by the mutation and subscription APIs, the updater passed to `commitLocalUpdate` does not accept a second parameter. This is because there is no associated network response.
+* Note that any local data updates will automatically cause components subscribed to the data to be notified of the change and re-render.
+
+## commitPayload
+
+`commitPayload` takes an `OperationDescriptor` and the payload for the query, and writes it to the Relay Store. The payload will be resolved like a normal server response for a query, and will also resolve Data Driven Dependencies that are passed as `JSResource`, `requireDefer`, etc.
+
+```js
+import type {FooQueryRawResponse} from 'FooQuery.graphql'
+
+const {createOperationDescriptor} = require('relay-runtime');
+
+const operationDescriptor = createOperationDescriptor(FooQuery, {
+  id: 'an-id',
+  otherVariable: 'value',
+});
+
+const payload: FooQueryRawResponse = {...};
+
+environment.commitPayload(operationDescriptor, payload);
+```
+
+* An `OperationDescriptor` can be created by `createOperationDescriptor`; it takes the query and the query variables.
+* The payload can be typed using the Flow type generated by adding the directive `@raw_response_type` to the query.
+* Note that any local data updates will automatically cause components subscribed to the data to be notified of the change and re-render.
+
+// @fb-only
+
+<DocsRating />

package/llm-docs/guided-tour/updating-data/typesafe-updaters-faq.mdx

@@ -0,0 +1,83 @@
+---
+id: typesafe-updaters-faq
+title: Typesafe updaters FAQ
+slug: /guided-tour/updating-data/typesafe-updaters-faq/
+description: Typesafe updater FAQ
+keywords:
+- typesafe updaters
+- readUpdatableQuery
+- readUpdatableFragment
+- updater
+- updatable
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+# Typesafe Updaters FAQ
+
+<FbInternalOnly>
+
+:::note
+
+Is something missing from this Q&A? Are you confused? Would you like help adopting these APIs? Please, reach out to [Robert Balicki](https://fb.workplace.com/profile.php?id=100042823931887). I am happy to help!
+
+:::
+
+</FbInternalOnly>
+
+# General
+
+## What is typesafe updaters?
+
+Typesafe updaters is the name given to a project to provide a typesafe and ergonomic alternative to the existing APIs for imperatively updating data in the Relay store.
+
+For example, [`readUpdatableFragment`](../../../api-reference/store/#readupdatablefragmentfragment-updatablefragmenttfragmenttype-tdatafragmentreference-hasupdatablespreadtfragmenttype-updatabledatatdata) and [`readUpdatableQuery`](../../../api-reference/store/#readupdatablequeryquery-updatablequerytvariables-tdatavariables-tvariables-updatabledatatdata) are two typesafe updaters that the store exposes.
+
+## Why?
+
+Relay provides typesafe and ergonomic APIs for fetching and managing data that originates on the server. In addition, Relay provides the ability to define local-only fields in **client schema extensions**. However, the APIs for mutating the data in these fields has hitherto been verbose and not ergonomic, meaning that we could not recommend Relay as a solution for managing local state.
+
+## What was wrong with the existing APIs?
+
+The pre-existing APIs are verbose and not typesafe. They make it easy to make a variety of mistakes and require that the developer understand a new set of APIs only when writing updaters.
+
+Typesafe updaters is a set of APIs that are typesafe and more ergonomic. They leverage well-known Relay idioms (queries, fragments, type refinement) and use getters and setters instead of requiring that the developer learn about a set of methods that are unused elsewhere.
+
+## How does a developer use typesafe updaters?
+
+With typesafe updaters, a developers writes an updatable query or a fragment that specifies the data to imperatively update. Then, the developer reads out that data from the store, returning a so-called **updatable proxy**. Then, the developer mutates that updatable proxy. Mutating that updatable proxy using setters (e.g. `updatableData.name = "Godzilla"`) results in calls to the old API, but with added type safety.
+
+## What is an updatable query or fragment?
+
+An updatable query or fragment is a query or fragment that has the `@updatable` directive.
+
+# Updatable queries and fragments are not fetched
+
+## Are fields selected in updatable queries and fragments fetched from the server?
+
+No! The server doesn't know about updatable queries and fragments. Their fields are never fetched.
+
+Even if you spread an updatable fragment in a regular query or fragment, the fields selected by that updatable fragment are not fetched as part of that request.
+
+## What if I want to fetch a field and also mutate it?
+
+You should select that field in both a regular query/fragment **and** in an updatable query/fragment.
+
+## What are some consequences of this?
+
+* When you read out updatable data, it can be missing if it isn't present in the store.
+* You cannot spread regular fragments in updatable queries/fragments.
+* The generated artifact for updatable queries/fragments does not contain a query ID and does not contain a normalization AST (which is used for writing network data to the store.)
+* Directives like `@defer`, etc. do not make sense in this context, and are disallowed.
+
+# Misc
+
+## Where do I get a `store`?
+
+The classes `RelayRecordSourceSelectorProxy`, `RecordSourceProxy` and `RelayRecordSourceProxy` contain the methods `readUpdatableQuery` and `readUpdatableFragment`. One can acquire an instance of these classes:
+
+* In updaters of mutations and subscriptions
+* In optimistic updaters of mutations
+* When using `RelayModernEnvironment`'s `commitUpdate`, `applyUpdate`, etc. methods.
+* When using the standalone `commitLocalUpdate` method.