relay-runtime 20.1.0 → 21.0.0

package/llm-docs/guides/alias-directive.mdx

@@ -0,0 +1,160 @@
+---
+id: alias-directive
+title: "@alias Directive"
+slug: /guides/alias-directive/
+description: Relay guide to @alias
+keywords:
+- alias
+- directive
+- fragment
+---
+
+The `@alias` directive allows you to expose a spread fragment — either a named fragment spread or an inline fragment — as a named field within your selection. This allows Relay to provide additional type safety in the case where your fragment’s type may not match the parent selection.
+
+:::info
+This document describes why the `@alias` directive was introduced, and how it can be used to improve type safety in your Relay applications. **To learn about its API, see the [API Reference](../api-reference/graphql/graphql-directives.mdx#alias).**
+:::
+
+Let's look at an example where `@alias` can be useful:
+
+## Abstract Types
+
+Imagine you have a component that renders information about a Viewer:
+
+```ts
+function MyViewer({viewerKey}) {
+  const {name} = useFragment(graphql`
+    fragment MyViewer on Viewer {
+      name @required(action: THROW)
+    }`, viewerKey);
+
+  return `My name is ${name}. That's ${name.length} letters long!`;
+}
+```
+
+To use that component in a component that has a fragment on Node (which Viewer implements), you could write something like this:
+
+```ts
+function MyNode({nodeKey}) {
+  const node = useFragment(graphql`
+    fragment MyFragment on Node {
+      ...MyViewer
+    }`, nodeKey);
+
+  return <MyViewer viewerKey={node} />
+}
+```
+
+Can you spot the problem? We don’t actually know that the node we are passing to `<MyViewer />` is actually a Viewer `<MyViewer />`. If `<MyNode />` tries to render a Comment — which also implements Node — we will get a runtime error in `<MyViewer />` because the field name is not present on Comment.
+
+```
+TypeError: Cannot read properties of undefined (reading 'length')
+```
+
+Not only do we not get a type letting us know that about this potential issue, but even at runtime, there is no way to check if node implements Viewer because Viewer is an abstract type!
+
+## Aliased Fragments
+
+Aliased fragments can solve this problem. Here’s what `<MyNode />` would look like using them:
+
+```ts
+function MyNode({nodeKey}) {
+  const node = useFragment(graphql`
+    fragment MyFragment on Node {
+      ...MyViewer @alias(as: "my_viewer")
+    }`, nodeKey);
+
+  // Relay returns the fragment key as its own nullable property
+  if(node.my_viewer == null) {
+    return null;
+  }
+
+  // Because `my_viewer` is typed as nullable, Flow/TypeScript will
+  // show an error if you try to use the `my_viewer` without first
+  // performing a null check.
+  //                          VVVVVVVVVVVVVV
+  return <MyViewer viewerKey={node.my_viewer} />
+}
+```
+
+With this approach, you can see that Relay exposes the fragment key as its own nullable property, which allows us to check that node actually implements Viewer and even allows Flow to enforce that the component handles the possibility!
+
+## @skip and @include
+
+A similar problem can occur when using `@skip` and `@include` directives on fragments. In order to safely use the spread fragment, you need to check if it was fetched. Historically this has required gaining access to the query variable that was used to determine if the fragment was skipped or included.
+
+With `@alias`, you can now check if the fragment was fetched by simply assigning the fragment an alias, and checking if the alias is null:
+
+```ts
+function MyUser({userKey}) {
+  const user = useFragment(graphql`
+    fragment MyFragment on User {
+      ...ConditionalData @skip(if: $someVar) @alias
+    }`, userKey);
+
+  if(user.ConditionalData == null) {
+    return "No data fetched";
+  }
+  return <ConditionalData userKey={user.ConditionalData} />
+}
+```
+
+## Enforced Safety
+
+We've outlined two different ways that fragments can be unsafe in Relay today without `@alias`. To help prevent runtime issues resulting from these unsafe edge cases, Relay requires that all conditionally fetched fragments are aliased.
+
+To disable this validation in your project, you can disable the `enforce_fragment_alias_where_ambiguous` compiler feature flag for your project. If you need to enable incremental adoption of this enforcement, Relay exposes a directive `@dangerously_unaliased_fixme` which will suppress enforcement errors. This will allow you to enable the enforcement for all new spreads without first needing to migrate all existing issues.
+
+The [Relay VSCode extension](../editor-support.mdx) offers quick fixes to add either `@alias` or `@dangerously_unaliased_fixme` to unsafe fragments, and the
+[mark-dangerous-conditional-fragment-spreads](../codemods/#mark-dangerous-conditional-fragment-spreads) codemod can be used to apply `@dangerously_unaliased_fixme` across your entire project.
+
+## Use with @required
+
+`@alias` can be used with [`@required(action: NONE)`](./required-directive.mdx) to group together required fields. In the following example, we group `name` and `email` together as `requiredFields`. If either is null, that null will bubble up to, the `user.requiredFields` field, making it null. This allows us to perform a single check, without impacting the `id` field.
+
+```ts
+function MyUser({userKey}) {
+  const user = useFragment(graphql`
+    fragment MyFragment on User {
+      id
+      ... @alias(as: "requiredFields") {
+        name @required(action: NONE)
+        email @required(action: NONE)
+      }
+    }`, userKey);
+
+  if(user.requiredFields == null) {
+    return `Missing required fields for user ${user.id}`;
+  }
+  return `Hello ${user.requiredFields.name} (${user.requiredFields.email}).!`;
+}
+```
+
+:::note
+Using `@required` on a fragment spread that has an `@alias` is not currently supported, but we may add support in the future.
+:::
+
+## Under the Hood
+
+For people familiar with Relay, or curious to learn, here is a brief description of how this feature is implemented:
+
+Under the hood, `@alias` is implemented entirely within Relay (compiler and runtime). It does not require any server support. The Relay compiler interprets the `@alias` directive, and generates types indicating that the fragment key, or inline fragment data, will be attached to the new field, rather than directly on the parent object. In the Relay runtime artifact, it wraps the fragment node with a new node indicating the name of the alias and additional information about the type of the fragment.
+
+The Relay compiler also inserts an additional field into the spread which allows it to determine if the fragment has matched:
+
+```graphql
+fragment Foo on Node {
+  ... on Viewer {
+    isViewer: __typename # <-- Relay inserts this
+    name
+  }
+}
+```
+
+Relay can now check for the existence of the `isViewer` field in the response to know if the fragment matched.
+
+When Relay reads the content of your fragment out of the store using its runtime artifact, it uses this information to attach the fragment key to this new field, rather than attaching it directly to the parent object.
+
+### Related
+
+While `@alias` is a Relay-specific feature, it draws inspiration from fragment modularity as outlined in the GraphQL [RFC Fragment Modularity](https://github.com/graphql/graphql-wg/blob/main/rfcs/FragmentModularity.mdx).

package/llm-docs/guides/catch-directive.mdx

@@ -0,0 +1,167 @@
+---
+id: catch-directive
+title: '@catch Directive'
+slug: /guides/catch-directive/
+description: Relay guide to @catch
+keywords:
+  - catch
+  - directive
+  - optional
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+The `@catch` directive can be added to fields, fragment/operation definitions or
+aliased inline fragment spreads declare how exceptions and unexpected values
+should be handled at runtime. Using `@catch` allows Relay to surface these error
+states as part of your fragment/query/mutation data instead of a null value
+(which has been the default behavior), or a runtime exception if
+[`@throwOnFieldError`](./throw-on-field-error-directive.mdx) is being used.
+
+:::tip
+Both `@catch` and `@throwOnFieldError` only handle field errors in the
+query/fragment/mutation in which they are used. They **do not** handle errors
+related to fields in any spread fragments.
+:::
+
+## `to` Argument
+
+The `@catch` directive accepts an optional `to` argument which has two options:
+
+- `RESULT` (default): The value is returned as `{ ok: true, value: T } | { ok: false, errors: [error] }`. This allows you implement explicit field-granular error handling in your application.
+- `NULL`: If an error is encountered within the `@catch`, the value will be replaced with `null`.
+
+## Examples
+
+If a `@catch` error is caught directly on the field that the error originated
+from - the error is provided on that field. Here's an example:
+
+```graphql
+query MyQuery {
+  viewer {
+    name @catch
+    age
+  }
+}
+```
+
+If `name` contains an error - it would be provided in the response data on the
+`name` field - like so:
+
+```js
+{
+  viewer: {
+    name: {
+      ok: false,
+      errors: [{path: ['viewer', 'name']}]
+    }
+    age: 39
+  }
+}
+```
+
+However, if `@catch` exists on one of the ancestors of a field, that error will
+bubble up to there, like so:
+
+```graphql
+query MyQuery {
+  viewer @catch {
+    name
+    age
+  }
+}
+```
+
+```js
+{
+  viewer: {
+    ok: false,
+    errors: [{ path: ['viewer', 'name'] } ]
+  }
+}
+```
+
+## Implications for nullability
+
+Fields whose errors are explicitly handled by `@catch`, either by being
+annotated with `@catch` or by being nested with a `@catch` ancestor will be
+typed using their [Semantic Nullability](./semantic-nullability.mdx). In other
+words, if a field has been marked as `@semanticNonNull` in the server schema to
+indicate that it will only be null in the case of error, Relay will type that
+field as non-nullable in its generated Flow/TypeScript types.
+
+## What can be caught with `@catch`?
+
+### Payload Field Errors
+
+Payload [field
+errors](https://spec.graphql.org/October2021/#sec-Errors.Field-errors) are
+errors that occur as the result of a server-side exception while executing a
+given field's resolver. In this case, the GraphQL specifies that the server must
+provide a null value where a value should be, and a separate errors object.
+
+When you `@catch` on a field, Relay takes those errors and provides them to you
+in-line instead, making them easier to handle, and no longer invisible.
+
+### @required(action: THROW) within an @catch
+
+If you have an `@required(action: THROW)` with an ancestor that contains a
+`@catch` - instead of throwing an exception, the `@required` error would bubble
+up and be provided in the same way normal errors would. Here's an example:
+
+```graphql
+query MyQuery {
+  viewer @catch {
+    name @required(action: THROW)
+    age
+  }
+}
+```
+
+```js
+{
+  viewer: {
+    ok: false,
+    errors: [{ path: ["viewer", "name"] }]
+  }
+}
+```
+
+### Missing Data in response
+
+[Here is an example of where missing data may occur in Relay](https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change)
+
+If a field is expected to have a value, and that field is undefined - the field
+is considered to be "missing data". This is also an unexpected state - and when
+it happens with an `@catch` as an ancestor, it will also be caught like so:
+
+```js
+{
+  viewer: {
+    ok: false,
+    errors: [{ path: ["viewer", "name"] }]
+  }
+}
+```
+
+## How does `@catch` interact with `@throwOnFieldError`?
+
+Using `@throwOnFieldError` enables fields to throw a JavaScript exception when a
+field error occurs. By using `@catch` - you tell Relay that you don't want a
+JavaScript exception in this case. Instead, you are requesting that the error be
+provided in the data object, with the same behaviors and rules as are listed
+above (including bubbling to a parent field).
+
+It is important to note that you can still use @catch without
+@throwOnFieldError. It will still provide you the error in the data object. But
+other fields that are not under a `@catch` will still not throw - because
+`@throwOnFieldError` would be missing.
+
+Read more about `@throwOnFieldError`
+[here](https://relay.dev/docs/next/api-reference/graphql-and-directives/#throwonfielderror-experimental).
+
+## GraphQL Conf Talk
+
+The Relay team gave a talk at GraphQL Conf 2024 about `@catch` and explicit error handling in Relay. You can watch it here:
+
+<iframe src="https://www.youtube-nocookie.com/embed/_TSYKAtaK5A" width={640} height={360} allowFullScreen={true} frameBorder="0" />

package/llm-docs/guides/client-schema-extensions.mdx

@@ -0,0 +1,208 @@
+---
+id: client-schema-extensions
+title: Client Schema Extensions
+slug: /guides/client-schema-extensions/
+description: Relay guide to client schema extensions
+keywords:
+- client
+- schema
+- extension
+- commitLocalUpdate
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+:::note
+See also [the local data updates](../../guided-tour/updating-data/local-data-updates/) and [client-only data](../../guided-tour/updating-data/client-only-data/) sections of the guided tour.
+:::
+
+Relay can be used to read and write local data, and act as a single source of truth for _all_ data in your client application.
+
+The Relay Compiler fully supports client-side extensions of the schema, which allows you to define local fields and types.
+
+## Table of Contents:
+
+-   [Extending the server schema](#extending-the-server-schema)
+-   [Querying local state](#querying-local-state)
+-   [Mutating local state](#mutating-local-state)
+-   [Initial local state](#initial-local-state)
+
+## Extending the server schema
+
+To extend the server schema, create a new `.graphql` file inside your `--src`
+directory.  Let's call it `./src/clientSchema.graphql`.  This file needs to be
+referenced in the `"schemaExtensions"` of your Relay config, either directly or
+via its folder.
+
+This schema describes what local data can be queried on the client.
+It can even be used to extend an existing server schema.
+
+For example, we can create a new type called `Note`:
+
+```graphql
+type Note {
+  id: ID!
+  title: String
+  body: String
+}
+```
+
+And then extend the server schema type `User`, with a list of `Note`, called `notes`.
+
+```graphql
+extend type User {
+  notes: [Note]
+}
+```
+
+## Querying local state
+
+Accessing local data is no different from querying your GraphQL server, although you are required to include at least one server field in the query.
+The field can be from the server schema, or it can be schema agnostic, like an introspection field (e.g. `__typename`).
+
+Here, we use [useLazyLoadQuery](../../api-reference/use-lazy-load-query) to get the current `User` via the `viewer` field, along with their id, name and the local list of notes.
+
+```javascript
+// Example.js
+import * as React from 'react';
+import { useLazyLoadQuery, graphql } from 'react-relay';
+
+const Example = (props) => {
+  const data = useLazyLoadQuery(graphql`
+    query ExampleQuery {
+      viewer {
+        id
+        name
+        notes {
+          id
+          title
+          body
+        }
+      }
+    }
+  `, {});
+  // ...
+}
+```
+
+## Mutating local state
+
+All local data lives in the [Relay Store](../../api-reference/store/).
+
+Updating local state can be done with any `updater` function.
+
+The `commitLocalUpdate` function is especially ideal for this, because writes to local state are usually executed outside of a mutation.
+
+To build upon the previous example, let's try creating, updating and deleting a `Note` from the list of `notes` on `User`.
+
+### Create
+
+```javascript
+import {commitLocalUpdate} from 'react-relay';
+
+let tempID = 0;
+
+function createUserNote(environment) {
+  commitLocalUpdate(environment, store => {
+    const user = store.getRoot().getLinkedRecord('viewer');
+    const userNoteRecords = user.getLinkedRecords('notes') || [];
+
+    // Create a unique ID.
+    const dataID = `client:Note:${tempID++}`;
+
+    //Create a new note record.
+    const newNoteRecord = store.create(dataID, 'Note');
+
+    // Add the record to the user's list of notes.
+    user.setLinkedRecords([...userNoteRecords, newNoteRecord], 'notes');
+  });
+}
+```
+
+Note that since this record will be rendered by the `ExampleQuery` via `useLazyLoadQuery`, the query data will automatically be retained and won't be garbage collected.
+
+If no component is rendering the local data and you want to manually retain it, you can do so by calling `environment.retain()`:
+
+```javascript
+import {createOperationDescriptor, getRequest} from 'relay-runtime';
+
+// Create a query that references that record
+const localDataQuery = graphql`
+  query LocalDataQuery {
+    viewer {
+      notes {
+        __typename
+      }
+    }
+  }
+`;
+
+// Create an operation descriptor for the query
+const request = getRequest(localDataQuery);
+const operation = createOperationDescriptor(request, {} /* variables */);
+
+
+// Tell Relay to retain this operation so any data referenced by it isn't garbage collected
+// In this case, all the notes linked to the `viewer` will be retained
+const disposable = environment.retain(operation);
+
+
+// Whenever you don't need that data anymore and it's okay for Relay to garbage collect it,
+// you can dispose of the retain
+disposable.dispose();
+```
+
+### Update
+
+```javascript
+import {commitLocalUpdate} from 'react-relay';
+
+function updateUserNote(environment, dataID, body, title) {
+  commitLocalUpdate(environment, store => {
+    const note = store.get(dataID);
+
+    note.setValue(body, 'body');
+    note.setValue(title, 'title')
+  });
+}
+```
+
+### Delete
+
+```javascript
+import {commitLocalUpdate} from 'react-relay';
+
+function deleteUserNote(environment, dataID) {
+  commitLocalUpdate(environment, store => {
+    const user = store.getRoot().getLinkedRecord('viewer');
+    const userNoteRecords = user.getLinkedRecords('notes');
+
+    // Remove the note from the list of user notes.
+    const newUserNoteRecords = userNoteRecords.filter(x => x.getDataID() !== dataID);
+
+    // Delete the note from the store.
+    store.delete(dataID);
+
+    // Set the new list of notes.
+    user.setLinkedRecords(newUserNoteRecords, 'notes');
+  });
+}
+```
+
+## Initial local state
+
+All new client-side schema fields default to `undefined` value. Often however, you will want to set the initial state before querying local data.
+You can use an updater function via `commitLocalUpdate` to prime local state.
+
+```javascript
+import {commitLocalUpdate} from 'react-relay';
+
+commitLocalUpdate(environment, store => {
+  const user = store.getRoot().getLinkedRecord('viewer');
+
+  // initialize user notes to an empty array.
+  user.setLinkedRecords([], 'notes');
+});
+```
+
+<DocsRating />

package/llm-docs/guides/codemods.mdx

@@ -0,0 +1,66 @@
+---
+id: codemods
+title: Codemods
+slug: /guides/codemods/
+description: Relay guide to codemods
+keywords:
+  - codemod
+  - codemods
+---
+
+import DocsRating from '@site/src/core/DocsRating'; import {FbInternalOnly,
+OssOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal'; import
+Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
+
+The Relay compiler has the ability to make changes across the source files of
+your projects with the use of codemods. You can see the list of codemods
+available by running the Relay compiler's `codemod` command:
+
+```
+> relay codemod --help
+Apply codemod (verification with auto-applied fixes)
+
+Usage: relay codemod [OPTIONS] [CONFIG] <COMMAND>
+
+Commands:
+  mark-dangerous-conditional-fragment-spreads  Marks unaliased conditional fragment spreads as @dangerously_unaliased_fixme
+  help                                         Print this message or the help of the given subcommand(s)
+
+Arguments:
+  [CONFIG]  Compile using this config file. If not provided, searches for a config in package.json under the `relay` key or `relay.config.json` files among other up from the current working directory
+
+Options:
+  -p, --project <project>  Compile only this project. You can pass this argument multiple times. to compile multiple projects. If excluded, all projects will be compiled
+  -h, --help               Print help
+```
+
+## Available codemods
+
+The compiler currently has these available codemods:
+
+### mark-dangerous-conditional-fragment-spreads
+
+This codemod finds fragment spreads that are _dangerously unaliased_; that is,
+the fragment might not be fetched due to a directive such as `@skip` or its
+inclusion on a mismatched type within a union. If such a conditional fragment is
+not aliased with [`@alias`](../alias-directive/), there is no way for the
+resulting generated Flow or TypeScript types to reflect its nullability. This
+codemod will add the `@dangerously_unaliased_fixme` directive to such fragment
+spreads, indicating to developers that there is a problem to be fixed. After
+applying this codemod, the `enforce_fragment_alias_where_ambiguous` feature flag
+can be enabled, which will ensure any future ambiguous fragment spreads must be
+aliased.
+
+Since this codemod can potentially modify many files, there is an optional
+`--rollout` parameter which, if used alongside the
+`enforce_fragment_alias_where_ambiguous` feature flag in rollout mode, allows
+progressive codemod and enforcement of this validation.
+
+### remove-unnecessary-required-directives
+
+Removes [@required](../api-reference/graphql/graphql-directives.mdx#required)
+directives from non-null fields within
+[@throwOnFieldError](../api-reference/graphql/graphql-directives.mdx#throwonfielderror)
+fragments and operations, or linked fields with
+[`@catch`](../guides/catch-directive.mdx), where the compiler is certain that the
+directive does not change the generated types for the data being fetched.