relay-runtime 20.1.1 → 21.0.1

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

@@ -0,0 +1,511 @@
+---
+id: imperatively-modifying-linked-fields
+title: Imperatively modifying linked fields
+slug: /guided-tour/updating-data/imperatively-modifying-linked-fields/
+description: Using readUpdatableQuery to update linked fields in the store
+keywords:
+- record source
+- store
+- updater
+- typesafe updaters
+- readUpdatableQuery
+- readUpdatableFragment
+- updatable
+- assignable
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+:::note
+See also [using readUpdatableQuery to update scalar fields in the store](../imperatively-modifying-store-data).
+:::
+
+
+The examples in the [previous section](../imperatively-modifying-store-data/) showed how to use the `readUpdatableQuery` API to update scalar fields like `is_new_comment` and `is_selected`.
+
+The examples did **not** cover how to assign to linked fields. Let's start with an example of a component which allows the user of the application to update the Viewer's `best_friend` field.
+
+## Example: setting the viewer's best friend
+
+In order to assign a viewer's best friend, that viewer must have such a field. It may be defined by the server schema, or it may be defined locally in a schema extension as follows:
+
+```graphql
+extend type Viewer {
+  best_friend: User,
+}
+```
+
+Next, let's define a fragment and give it the `@assignable` directive, making it an **assignable fragment**. Assignable fragments can only contain a single field, `__typename`. This fragment will be on the `User` type, which is the type of the `best_friend` field.
+
+```js
+// AssignBestFriendButton.react.js
+graphql`
+  fragment AssignBestFriendButton_assignable_user on User @assignable {
+    __typename
+  }
+`;
+```
+
+The fragment must be spread at both the source (i.e. on the viewer's new best friend), and at the destination (within the viewer's `best_friend` field in the updatable query).
+
+Lets define a component with a fragment where we spread `AssignBestFriendButton_assignable_user`. This user will be the viewer's new best friend.
+
+```js
+// AssignBestFriendButton.react.js
+import type {AssignBestFriendButton_user$key} from 'AssignBestFriendButton_user.graphql';
+
+const {useFragment} = require('react-relay');
+
+export default function AssignBestFriendButton({
+  someTypeRef: AssignBestFriendButton_user$key,
+}) {
+  const data = useFragment(graphql`
+    fragment AssignBestFriendButton_someType on SomeType {
+      user {
+        name
+        ...AssignBestFriendButton_assignable_user
+      }
+    }
+  `, someTypeRef);
+
+  // We will replace this stub with the real thing below.
+  const onClick = () => {};
+
+  return (<button onClick={onClick}>
+    Declare {data.user?.name ?? 'someone with no name'} your new best friend!
+  </button>);
+}
+```
+
+That's great! Now, we have a component that renders a button. Let's fill out that button's click handler by using the `commitLocalUpdate` and `readUpdatableQuery` APIs to assign `viewer.best_friend`.
+
+* In order to make it valid to assign `data.user` to `best_friend`, we must **also** spread `AssignBestFriendButton_assignable_user` under the `best_friend` field in the viewer in the updatable query or fragment.
+
+```js
+import type {RecordSourceSelectorProxy} from 'react-relay';
+
+const {commitLocalUpdate, useRelayEnvironment} = require('react-relay');
+
+// ...
+
+const environment = useRelayEnvironment();
+const onClick = () => {
+  const updatableData = commitLocalUpdate(
+    environment,
+    (store: RecordSourceSelectorProxy) => {
+      const {updatableData} = store.readUpdatableQuery(
+          graphql`
+            query AssignBestFriendButtonUpdatableQuery
+            @updatable {
+              viewer {
+                best_friend {
+                  ...AssignBestFriendButton_assignable_user
+                }
+              }
+            }
+          `,
+          {}
+        );
+
+      if (data.user != null && updatableData.viewer != null) {
+        updatableData.viewer.best_friend = data.user;
+      }
+    }
+  );
+};
+```
+
+### Putting it all together
+
+The full example is as follows:
+
+```graphql
+extend type Viewer {
+  best_friend: User,
+}
+```
+
+```js
+// AssignBestFriendButton.react.js
+import type {AssignBestFriendButton_user$key} from 'AssignBestFriendButton_user.graphql';
+import type {RecordSourceSelectorProxy} from 'react-relay';
+
+const {commitLocalUpdate, useFragment, useRelayEnvironment} = require('react-relay');
+
+graphql`
+  fragment AssignBestFriendButton_assignable_user on User @assignable {
+    __typename
+  }
+`;
+
+export default function AssignBestFriendButton({
+  someTypeRef: AssignBestFriendButton_someType$key,
+}) {
+  const data = useFragment(graphql`
+    fragment AssignBestFriendButton_someType on SomeType {
+      user {
+        name
+        ...AssignBestFriendButton_assignable_user
+      }
+    }
+  `, someTypeRef);
+
+  const environment = useRelayEnvironment();
+  const onClick = () => {
+    const updatableData = commitLocalUpdate(
+      environment,
+      (store: RecordSourceSelectorProxy) => {
+        const {updatableData} = store.readUpdatableQuery(
+            graphql`
+              query AssignBestFriendButtonUpdatableQuery
+              @updatable {
+                viewer {
+                  best_friend {
+                    ...AssignBestFriendButton_assignable_user
+                  }
+                }
+              }
+            `,
+            {}
+          );
+
+        if (data.user != null && updatableData.viewer != null) {
+          updatableData.viewer.best_friend = data.user;
+        }
+      }
+    );
+  };
+
+  return (<button onClick={onClick}>
+    Declare {user.name ?? 'someone with no name'} my best friend!
+  </button>);
+}
+```
+
+Let's recap what is happening here.
+
+* We are writing a component in which clicking a button results in a user is being assigned to `viewer.best_friend`. After this button is clicked, all components which were previously reading the `viewer.best_friend` field will be re-rendered, if necessary.
+* The source of the assignment is a user where an **assignable fragment** is spread.
+* The target of the assignment is accessed using the `commitLocalUpdate` and `readUpdatableQuery` APIs.
+* The query passed to `readUpdatableQuery` must include the `@updatable` directive.
+* The target field must have that same **assignable fragment** spread.
+* We are checking whether `data.user` is not null before assigning. This isn't strictly necessary. However, if we assign `updatableData.viewer.best_friend = null`, we will be nulling out the linked field in the store! This is (probably) not what you want.
+
+## Pitfalls
+
+* Note that there are no guarantees about what fields are present on the assigned user. This means that anything that consumes an updated field has no guarantee that the required fields were fetched and are present on the assigned object.
+
+<FbInternalOnly>
+
+:::note
+
+It is technically feasible to add fields to the assignable fragment, which would have the effect of guaranteeing that certain fields are present in the assigned object.
+
+If this is a need, please reach out to [Relay Support](https://fb.workplace.com/groups/relay.support).
+
+:::
+
+</FbInternalOnly>
+
+## Example: Assigning to a list
+
+Let's modify the previous example to append the user to a list of best friends. In this example, the following principle is relevant:
+
+> Every assigned linked field (i.e. the right hand side of the assignment) **must originate in a read-only fragment, query, mutation or subscription**.
+
+This means that `updatableData.foo = updatableData.foo` is invalid. For the same reason, `updatableData.viewer.best_friends = updatableData.viewer.best_friends.concat([newBestFriend])` is invalid. To work around this restriction, we must select the existing best friends from a read-only fragment, and perform the assignment as follows: `viewer.best_friends = existing_list.concat([newBestFriend])`.
+
+Consider the following full example:
+
+```graphql
+extend type Viewer {
+  # We are now defined a "best_friends" field instead of a "best_friend" field
+  best_friends: [User!],
+}
+```
+
+```js
+// AssignBestFriendButton.react.js
+import type {AssignBestFriendButton_user$key} from 'AssignBestFriendButton_user.graphql';
+import type {AssignBestFriendButton_viewer$key} from 'AssignBestFriendButton_viewer';
+
+import type {RecordSourceSelectorProxy} from 'react-relay';
+
+const {commitLocalUpdate, useFragment, useRelayEnvironment} = require('react-relay');
+
+graphql`
+  fragment AssignBestFriendButton_assignable_user on User @assignable {
+    __typename
+  }
+`;
+
+export default function AssignBestFriendButton({
+  someTypeRef: AssignBestFriendButton_someType$key,
+  viewerFragmentRef: AssignBestFriendButton_viewer$key,
+}) {
+  const data = useFragment(graphql`
+    fragment AssignBestFriendButton_someType on SomeType {
+      user {
+        name
+        ...AssignBestFriendButton_assignable_user
+      }
+    }
+  `, someTypeRef);
+
+  const viewer = useFragment(graphql`
+    fragment AssignBestFriendButton_viewer on Viewer {
+      best_friends {
+        # since viewer.best_friends appears in the right hand side of the assignment
+        # (i.e. updatableData.viewer.best_friends = viewer.best_friends.concat(...)),
+        # the best_friends field must contain the correct assignable fragment spread
+        ...AssignBestFriendButton_assignable_user
+      }
+    }
+  `, viewerRef);
+
+  const environment = useRelayEnvironment();
+  const onClick = () => {
+    commitLocalUpdate(
+      environment,
+      (store: RecordSourceSelectorProxy) => {
+        const {updatableData} = store.readUpdatableQuery(
+            graphql`
+              query AssignBestFriendButtonUpdatableQuery
+              @updatable {
+                viewer {
+                  best_friends {
+                    ...AssignBestFriendButton_assignable_user
+                  }
+                }
+              }
+            `,
+            {}
+          );
+
+        if (data.user != null && updatableData.viewer != null && viewer.best_friends != null) {
+          updatableData.viewer.best_friends = [
+            ...viewer.best_friends,
+            data.user,
+          ];
+        }
+      }
+    );
+  };
+
+  return (<button onClick={onClick}>
+    Add {user.name ?? 'someone with no name'} to my list of best friends!
+  </button>);
+}
+```
+
+## Example: assigning from an abstract field to a concrete field
+
+If you are assigning from an abstract field, e.g. a `Node` to a `User` (which implements `Node`), you must use an inline fragment to refine the `Node` type to `User`. Consider this snippet:
+
+```js
+const data = useFragment(graphql`
+  fragment AssignBestFriendButton_someType on Query {
+    node(id: "4") {
+      ... on User {
+        __typename
+        ...AssignBestFriendButton_assignable_user
+      }
+    }
+  }
+`, queryRef);
+
+const environment = useRelayEnvironment();
+const onClick = () => {
+  const updatableData = commitLocalUpdate(
+    environment,
+    (store: RecordSourceSelectorProxy) => {
+      const {updatableData} = store.readUpdatableQuery(
+          graphql`
+            query AssignBestFriendButtonUpdatableQuery
+            @updatable {
+              viewer {
+                best_friend {
+                  ...AssignBestFriendButton_assignable_user
+                }
+              }
+            }
+          `,
+          {}
+        );
+
+      if (data.node != null && data.node.__typename === "User" && updatableData.viewer != null) {
+        updatableData.viewer.best_friend = data.node;
+      }
+    }
+  );
+};
+```
+
+In this snippet, we do two things:
+
+* We use an inline fragment to refine the `Node` type to the `User` type. Inside of this refinement, we spread the assignable fragment.
+* We check that `data.node.__typename === "User"`. This indicates to Flow that within that if block, `data.node` is known to be a user, and therefore `updatableData.viewer.best_friend = data.node` can typecheck.
+
+## Example: assigning to an interface when the source is guaranteed to implement that interface
+
+You may wish to assign to a destination field that has an interface type (in this example, `Actor`). If the source field is guaranteed to implement that interface, then assignment is straightforward.
+
+For example, the source might have the same interface type or have a concrete type (`User`, in this example) that implements that interface.
+
+Consider the following snippet:
+
+```js
+graphql`
+  fragment Foo_actor on Actor @assignable {
+    __typename
+  }
+`;
+
+const data = useFragment(graphql`
+  fragment Foo_query on Query {
+    user {
+      ...Foo_actor
+    }
+    viewer {
+      actor {
+        ...Foo_actor
+      }
+    }
+  }
+`, queryRef);
+
+const environment = useRelayEnvironment();
+const onClick = () => {
+  commitLocalUpdate(environment, store => {
+    const {updatableData} = store.readUpdatableQuery(
+      graphql`
+        query FooUpdatableQuery @updatable {
+          viewer {
+            actor {
+              ...Foo_actor
+            }
+          }
+        }
+      `,
+      {}
+    );
+
+    // Assigning the user works as you would expect
+    if (updatableData.viewer != null && data.user != null) {
+      updatableData.viewer = data.user;
+    }
+
+    // As does assigning the viewer
+    if (updatableData.viewer != null && data.viewer?.actor != null) {
+      updatableData.viewer = data.viewer.actor;
+    }
+  });
+};
+```
+
+## Example: assigning to an interface when the source is **not** guaranteed to implement that interface
+
+You may wish to assign to a destination field that has an interface type (in this example, `Actor`). If the source type (e.g. `Node`) is **not** known to implement that interface, then an extra step is involved: validation.
+
+<FbInternalOnly>
+
+:::note
+
+With additional changes to Relay's type generation, this can be made simpler. Please reach out to [Robert Balicki](https://www.internalfb.com/profile/view/1238951) if this is a pain point for you.
+
+:::
+
+</FbInternalOnly>
+
+In order to understand why, some background is necessary. The flow type for the setter for an interface field might look like:
+
+```js
+set actor(value: ?{
+  +__id: string,
+  +__isFoo_actor: string,
+  +$fragmentSpreads: Foo_actor$fragmentType,
+  ...
+}): void,
+```
+
+The important thing to note is that the setter expects an object with a non-null `__isFoo_actor` field.
+
+When an assignable fragment with an abstract type is spread in a regular fragment, it results in an `__isFoo_actor: string` selection that is not optional if the type is known to implement the interface, and optional otherwise.
+
+Since a `Node` is **not** guaranteed to implement `Actor`, when the Relay compiler encounters the selection `node(id: "4") { ...Foo_actor }`, it will emit an optional field (`__isFoo_actor?: string`). Attempting to assign this to `updatableData.viewer.actor` will not typecheck!
+
+### Introducing validators
+
+The generated file for every generated artifact includes a named `validator` export. In our example, the function is as follows:
+
+```js
+function validate(value/*: {
+  +__id: string,
+  +__isFoo_actor?: string,
+  +$fragmentSpreads: Foo_actor$fragmentType,
+  ...
+}*/)/*: false | {
+  +__id: string,
+  +__isFoo_actor: string,
+  +$fragmentSpreads: Foo_actor$fragmentType,
+  ...
+}*/ {
+  return value.__isFoo_actor != null ? (value/*: any*/) : false;
+}
+```
+
+In other words, this function checks for the presence of the `__isFoo_actor` field. If it is found, it returns the same object, but with a flow type that is valid for assignment. If not, it returns false.
+
+### Example
+
+Let's put this all together in an example:
+
+```js
+import {validate as validateActor} from 'Foo_actor.graphql';
+
+graphql`
+  fragment Foo_actor on Actor @assignable {
+    __typename
+  }
+`;
+
+const data = useFragment(graphql`
+  fragment Foo_query on Query {
+    node(id: "4") {
+      ...Foo_actor
+    }
+  }
+`, queryRef);
+
+const environment = useRelayEnvironment();
+const onClick = () => {
+  commitLocalUpdate(environment, store => {
+    const {updatableData} = store.readUpdatableQuery(
+      graphql`
+        query FooUpdatableQuery @updatable {
+          viewer {
+            actor {
+              ...Foo_actor
+            }
+          }
+        }
+      `,
+      {}
+    );
+
+    if (updatableData.viewer != null && data.node != null) {
+      const validActor = validateActor(data.node);
+      if (validActor !== false) {
+        updatableData.viewer.actor = validActor;
+      }
+    }
+  });
+};
+```
+
+### Can flow be used to infer the presence of this field?
+
+Unfortunately, if you check for the presence of `__isFoo_actor`, Flow does not infer that (on the type level), the field is not optional. Hence, we need to use validators.
+
+<DocsRating />

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

@@ -0,0 +1,142 @@
+---
+id: imperatively-modifying-store-data-unsafe
+title: Imperatively modifying store data (unsafe)
+slug: /guided-tour/updating-data/imperatively-modifying-store-data-unsafe/
+description: Imperatively modifying store data
+keywords:
+- record source
+- store
+- updater
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+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. Since the second optimistic response **not recalculated**, the value of the like count will remain increased by two.
+
+An optimistic updater, on the other hand, would be re-run in this circumstance.
+
+## When **not** to use updaters
+
+### To trigger other side effects
+
+You should use the `onCompleted` callback to trigger other side effects.
+
+## 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. At that point, the mutation response is written to the store and regular updaters are executed. See [order of execution of updater functions](../graphql-mutations/#order-of-execution-of-updater-functions).
+
+Regular updaters are executed when a mutation completes successfully.
+
+## Example
+
+Let's consider an example that provides an updater to `commitMutation`.
+
+```js
+import type {Environment} from 'react-relay';
+import type {CommentCreateData, CreateCommentMutation} from 'CreateCommentMutation.graphql';
+
+const {commitMutation, graphql} = require('react-relay');
+const {ConnectionHandler} = require('relay-runtime');
+
+function commitCommentCreateMutation(
+  environment: Environment,
+  feedbackID: string,
+  input: CommentCreateData,
+) {
+  return commitMutation<CreateCommentMutation>(environment, {
+    mutation: graphql`
+      mutation CreateCommentMutation($input: CommentCreateData!) {
+        comment_create(input: $input) {
+          comment_edge {
+            cursor
+            node {
+              body {
+                text
+              }
+            }
+          }
+        }
+      }
+    `,
+    variables: {input},
+    updater: (store: RecordSourceSelectorProxy, _response: ?CreateCommentMutation$data) => {
+      // we are not using _response in this example, but it is
+      // provided and statically typed.
+
+      const feedbackRecord = store.get(feedbackID);
+
+      // Get connection record
+      const connectionRecord = ConnectionHandler.getConnection(
+        feedbackRecord,
+        'CommentsComponent_comments_connection',
+      );
+
+      // Get the payload returned from the server
+      const payload = store.getRootField('comment_create');
+
+      // Get the edge inside the payload
+      const serverEdge = payload.getLinkedRecord('comment_edge');
+
+      // Build edge for adding to the connection
+      const newEdge = ConnectionHandler.buildConnectionEdge(
+        store,
+        connectionRecord,
+        serverEdge,
+      );
+
+      // Add edge to the end of the connection
+      ConnectionHandler.insertEdgeAfter(
+        connectionRecord,
+        newEdge,
+      );
+    },
+  });
+}
+
+module.exports = {commit: commitCommentCreateMutation};
+```
+
+Let's distill this example:
+
+* The updater receives 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 in response to the mutation response: you can *create entirely new records*, or *update or delete existing ones*.
+* The updater receives a second `data` argument, which contains the data selected by the mutation fragment. This can be used to retrieve the payload data without interacting with the *`store`*. The type of this mutation response can be imported from the auto-generated `Mutation.graphql.js` file, and is given the name `MutationName$data`.
+    * The type of this `data` argument is a nullable version of the `$data` type.
+    * The `data` arguments contains just the data selected directly by the mutation argument. In other words, if another fragment is spread in the mutation, the data from that fragment will not be available within `data` by default.
+* In our specific example, we're adding a new comment to our local store after it has successfully been added on the server. Specifically, we're adding a new item to a connection; for more details on the specifics of how that works, check out our section on [adding and removing items from a connection](../../list-data/updating-connections/).
+    * There is no need for an updater in this example — it would be a great place to use the `@appendEdge` directive instead!
+* Note that the mutation response is a *root field* record that can be read from the `store` using the `store.getRootField` API. In our case, we're reading the `comment_create` root field, which is a root field in the mutation response.
+* Note that the `root` field of the mutation is different from the `root` of queries, and `store.getRootField` in the mutation updater can only get the record from the mutation response. To get records from the root that's not in the mutation response, use `store.getRoot().getLinkedRecord` instead.
+* Once the updater completes, any local data updates caused by the mutation `updater` will automatically cause components subscribed to the data to be notified of the change and re-render.
+
+## Learn more
+
+See the full APIs [here](../../../api-reference/store/).
+
+<DocsRating />