relay-runtime 20.1.0 → 21.0.0

package/llm-docs/api-reference/relay-runtime/wait-for-fragment-data.mdx

@@ -0,0 +1,89 @@
+---
+id: wait-for-fragment-data
+title: waitForFragmentData
+slug: /api-reference/wait-for-fragment-data/
+description: Read the value of a fragment as a promise
+keywords:
+  - promise
+  - fragment
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+:::warning
+`waitForFragmentData` is still an experimental API. It currently has some limitations and may evolve slightly during this phase.
+:::
+
+## `waitForFragmentData`
+
+In some cases it can be useful to define data that you wish to read using a GraphQL fragment, but then consume it just once outside of React render function. `waitForFragmentData` allows you to wait for the data of a fragment to be available,
+
+To read a fragment's data as it changes over time, see [`observeFragment`](./observe-fragment.mdx).
+
+### Example: Deferring data used in an event handler
+
+One use case for `waitForFragmentData` is to defer fetching data that is needed inside an event handler, but is not needed to render the initial view.
+
+```tsx
+import { useCallback } from "react";
+import { useFragment } from "react-relay";
+import { graphql } from "relay-runtime";
+import { waitForFragmentData } from "relay-runtime/experimental";
+
+function MyComponent({ key }) {
+  const user = useFragment(
+    graphql`
+      fragment UserFragment on User {
+        name
+        # Page load can complete before this data has streamed in from the server.
+        ...EventHandlerFragment @defer
+      }
+    `,
+    key,
+  );
+
+  const onClick = useCallback(async () => {
+    // Once the user clicks, we may need to wait for the data to finish loading.
+    const userData = await waitForFragmentData(
+      graphql`
+        fragment EventHandlerFragment on User {
+          age
+        }
+      `,
+      user,
+    );
+
+    if (userData.age < 10) {
+      alert("Hello kiddo!");
+    } else if (userData.age < 18) {
+      alert("Hello young person!");
+    } else {
+      alert("Hello adult person!");
+    }
+  }, [user]);
+
+  return (
+    <div>
+      My name is {user.name}
+      <button onClick={onClick}>Greet</button>
+    </div>
+  );
+}
+```
+
+### Arguments
+
+* `environment`: `IEnvironment`. A Relay environment.
+* `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
+
+* A `Promise<T>` where `T` is the data defined in the fragment.
+
+The Promise will wait for all network data to become available as well as any [`@live` Relay Resolver](../../guides/relay-resolvers/live-fields.mdx) to be in a non-suspended state before it resolves.
+
+In the case of a network error, or a field-level error due to [`@throwOnFieldError`](../../guides/throw-on-field-error-directive.mdx) or [`@required(action: THROW)`](../../guides/required-directive.mdx), the Promise will reject with an error.
+
+<DocsRating />

package/llm-docs/api-reference/types/CacheConfig.mdx

@@ -0,0 +1,8 @@
+#### Type `CacheConfig`
+
+* An object with the following fields:
+  * `force`: *_[Optional]_* A boolean. If true, causes a query to be issued unconditionally, regardless of the state of any configured response cache.
+  * `poll`: *_[Optional]_* A number. Causes a query to live-update by polling at the specified interval, in milliseconds. (This value will be passed to `setTimeout`).
+  * `liveConfigId`: *_[Optional]_* A string. Causes a query to live-update by calling GraphQLLiveQuery; it represents a configuration of gateway when doing live query.
+  * `metadata`: *_[Optional]_* An object. User-supplied metadata.
+  * `transactionId`: *_[Optional]_* A string. A user-supplied value, intended for use as a unique id for a given instance of executing an operation.

package/llm-docs/api-reference/types/Disposable.mdx

@@ -0,0 +1,4 @@
+#### Interface `Disposable`
+
+* An object with the following key:
+  * `dispose`: `() => void`. Disposes of the resource.

package/llm-docs/api-reference/types/GraphQLSubscriptionConfig.mdx

@@ -0,0 +1,17 @@
+import SelectorStoreUpdater from './SelectorStoreUpdater.mdx';
+import CacheConfig from './CacheConfig.mdx';
+
+#### Type `GraphQLSubscriptionConfig<TSubscriptionPayload>`
+
+* An object with the following fields:
+  * `cacheConfig`: *_[Optional]_* [`CacheConfig`](#type-cacheconfig)
+  * `subscription`: `GraphQLTaggedNode`. A GraphQL subscription specified using a `graphql` template literal
+  * `variables`: The variables to pass to the subscription
+  * `onCompleted`: *_[Optional]_* `() => void`. An optional callback that is executed when the subscription is established
+  * `onError`: *_[Optional]_* `(Error) => {}`. An optional callback that is executed when an error occurs
+  * `onNext`: *_[Optional]_* `(TSubscriptionPayload) => {}`. An optional callback that is executed when new data is received
+  * `updater`: *_[Optional]_* [`SelectorStoreUpdater`](#type-selectorstoreupdater).
+
+<CacheConfig />
+
+<SelectorStoreUpdater />

package/llm-docs/api-reference/types/MutationConfig.mdx

@@ -0,0 +1,31 @@
+import CacheConfig from './CacheConfig.mdx';
+import SelectorStoreUpdater from './SelectorStoreUpdater.mdx';
+import UploadableMap from './UploadableMap.mdx';
+
+#### Type `MutationConfig<TMutationConfig: MutationParameters>`
+
+* An object with the following fields:
+  * `cacheConfig`: *_[Optional]_* [`CacheConfig`](#type-cacheconfig)
+  * `mutation`: `GraphQLTaggedNode`. A mutation specified using a GraphQL literal
+  * `onError`: *_[Optional]_* `(Error) => void`. An optional callback executed if the mutation results in an error.
+  * `onCompleted`: *_[Optional]_* `($ElementType<TMutationConfig, 'response'>) => void`. An optional callback that is executed when the mutation completes.
+    * The value passed to `onCompleted` is the the mutation fragment, as read out from the store, **after** updaters and declarative mutation directives are applied. This means that data from within unmasked fragments will not be read, and records that were deleted (e.g. by `@deleteRecord`) may also be null.
+  * `onUnsubscribe`: *_[Optional]_* `() => void`. An optional callback that is executed when the mutation is unsubscribed, which occurs when the returned `Disposable` is disposed.
+  * `optimisticResponse`: *_[Optional]_* An object whose type matches the raw response type of the mutation. Make sure you decorate your mutation with `@raw_response_type` if you are using this field.
+  * `optimisticUpdater`: *_[Optional]_* [`SelectorStoreUpdater`](#type-selectorstoreupdater). A callback that is executed when `commitMutation` is called, after the `optimisticResponse` has been normalized into the store.
+  * `updater`: *_[Optional]_* [`SelectorStoreUpdater`](#type-selectorstoreupdater). A callback that is executed when a payload is received, after the payload has been written into the store.
+  * `uploadables`: *_[Optional]_* [`UploadableMap`](#type-uploadablemap). An optional uploadable map.
+  * `variables`: `$ElementType<TMutationConfig, 'variables'>`. The variables to pass to the mutation.
+
+<CacheConfig />
+
+<SelectorStoreUpdater />
+
+<UploadableMap />
+
+#### Type `MutationParameters`
+
+* An object with the following fields:
+  * `response`: An object
+  * `variables`: An object
+  * `rawResponse`: An optional object

package/llm-docs/api-reference/types/SelectorStoreUpdater.mdx

@@ -0,0 +1,6 @@
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+#### Type `SelectorStoreUpdater`
+
+* A function with signature `(store: RecordSourceSelectorProxy, data) => void`
+* 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 subscription payload: you can *create entirely new records*, or *update or delete existing ones*. The full API for reading and writing to the Relay store is available <a href={useBaseUrl('docs/api-reference/store/#recordsourceselectorproxy')}>here</a>.

package/llm-docs/api-reference/types/UploadableMap.mdx

@@ -0,0 +1,3 @@
+#### Type `UploadableMap`
+
+* An object whose values are [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) or [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).

package/llm-docs/community/learning-resources.mdx

@@ -0,0 +1,64 @@
+---
+id: learning-resources
+title: Community Learning Resources
+slug: /community-learning-resources/
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## Guides and articles:
+
+-   [How to use @argumentsDefinitions to define local variables to your fragments](https://medium.com/entria/relay-modern-argumentdefinitions-d53769dbb95d) (by Entria)
+-   [Deep Dive of Updater Relay Store function. How to update your store properly after a mutation or subscription](https://medium.com/entria/wrangling-the-client-store-with-the-relay-modern-updater-function-5c32149a71ac) (by Entria)
+-   [Optimistic Update: how to update your UI before server responds](https://medium.com/entria/relay-modern-optimistic-update-a09ba22d83c9) (by Entria)
+-   [Relay Network Deep Dive - how to incrementally improve your network layer to manage complex data fetching requirements](https://medium.com/entria/relay-modern-network-deep-dive-ec187629dfd3) (by Entria)
+-   [Relay Modern with TypeScript - how to configure Relay Modern to make it with TypeScript](https://medium.com/@sibelius/relay-modern-migration-to-typescript-c26ab0ee749c) (by @sibelius)
+-   [Collection of random thoughts and discoveries around Relay](https://mrtnzlml.com/docs/relay)
+
+<OssOnly>
+
+## Relay example projects
+
+These projects serve as an example of how to use Relay in real world applications. Some of them are even with educational videos.
+
+-   [github.com/relayjs/relay-examples](https://github.com/relayjs/relay-examples)
+-   [github.com/adeira/relay-example](https://github.com/adeira/relay-example)
+-   [github.com/juffalow/react-relay-example](https://github.com/juffalow/react-relay-example)
+
+## Learn basics
+
+Here, you will find articles written by the Relay community. They touch on basic topics that are necessary for daily work.
+
+-   [What is a fragment? Basic explanation of what is a fragment and what it is used for](https://medium.com/@sibelius/relay-modern-what-is-a-fragment-c70f164c2469) (by @sibelius)
+-   [Relay anti-patterns. What you should avoid doing when using Relay concepts](https://medium.com/entria/relay-apollo-anti-pattern-d9f4dea47738) (by Entria)
+-   [Insights of how Relay Modern has improved a lot since Relay Classic](https://medium.com/entria/relay-is-just-getting-better-54112ffc1a9e) (by Entria)
+-   [How to use @argumentsDefinitions to define local variables to your fragments](https://medium.com/entria/relay-modern-argumentdefinitions-d53769dbb95d) (by Entria)
+-   [How to paginate using a Refetch Container. You can use a refetch container to paginate as well, just use renderVariables correctly](https://medium.com/entria/relay-modern-pagination-using-refetch-container-editing-a07c6b33ae4e) (by Entria)
+
+## About Relay Store
+
+-   [How Relay Modern stores your data](https://medium.com/@sibelius/relay-modern-the-relay-store-8984cd148798) (by @sibelius)
+-   [Deep Dive of Updater Relay Store function. How to update your store properly after a mutation or subscription](https://medium.com/entria/wrangling-the-client-store-with-the-relay-modern-updater-function-5c32149a71ac) (by Entria)
+-   [Optimistic Update: how to update your UI before server responds](https://medium.com/entria/relay-modern-optimistic-update-a09ba22d83c9) (by Entria)
+-   [Local State Management, part 1 - how to create a controlled input using Relay](https://babangsund.com/relay_local_state_management/) (by @babangsund)
+-   [Local State Management, part 2 - how to manage global state and localStorage persistence on the client, using Relay](https://babangsund.com/relay_local_state_management_2/) (by @babangsund)
+-   [Local State Management, part 3 - using LocalQueryRenderer and local state to manage nested fragments](https://babangsund.com/relay_local_state_management_3/) (by @babangsund)
+
+## Network Layer
+
+-   [Relay Network Deep Dive - how to incrementally improve your network layer to manage complex data fetching requirements](https://medium.com/entria/relay-modern-network-deep-dive-ec187629dfd3) (by Entria)
+
+## Relay Configuration
+
+-   [Relay Modern with TypeScript - how to configure Relay Modern to make it with TypeScript](https://medium.com/@sibelius/relay-modern-migration-to-typescript-c26ab0ee749c) (by @sibelius)
+
+## Miscellaneous
+
+-   [Relay Modern Learning Blog Posts Thread on Twitter](https://twitter.com/sseraphini/status/1078595758801203202)
+-   [Collection of random thoughts and discoveries around Relay](https://mrtnzlml.com/docs/relay)
+
+</OssOnly>
+
+<DocsRating />

package/llm-docs/debugging/declarative-mutation-directives.mdx

@@ -0,0 +1,34 @@
+---
+id: declarative-mutation-directives
+title: Debugging Declarative Mutation Directives
+slug: /debugging/declarative-mutation-directives/
+description: Debugging declarative mutation directives
+keywords:
+- debugging
+- troubleshooting
+- declarative mutation directive
+- deleteRecord
+- handlerProvider
+- appendEdge
+- prependEdge
+- appendNode
+- prependNode
+---
+
+// @fb-only
+
+If you see an error similar to:
+
+```
+RelayFBHandlerProvider: No handler defined for `deleteRecord`. [Caught in: An uncaught error was thrown inside `RelayObservable`.]
+```
+
+or
+
+```
+RelayModernEnvironment: Expected a handler to be provided for handle `deleteRecord`.
+```
+
+This probably means that you are using a Relay environment to which a `handlerProvider` is passed. However, the handler provider does not know how to accept the handles `"deleteRecord"`, `"appendEdge"` or `"prependEdge"`. If this is the case, you should return `MutationHandlers.DeleteRecordHandler`, `MutationHandlers.AppendEdgeHandler`, or `MutationHandlers.PrependEdgeHandler` respectively (these can be imported from `relay-runtime`).
+
+// @fb-only

package/llm-docs/debugging/disallowed-id-types-error.mdx

@@ -0,0 +1,43 @@
+---
+id: disallowed-id-types-error
+title: Disallowed Types for `id` Fields
+slug: /debugging/disallowed-id-types-error
+description: Disallowed types for `id` fields
+keywords:
+- debugging
+- troubleshooting
+- disallowed
+- id
+- Object Identification
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+If you see an error from the compiler that reads something like:
+
+```
+Disallowed type `String` of field `id` on parent type `Foo` cannot be used by Relay to identify entities
+```
+
+This means that your GraphQL schema defines an object with a field named `id` that doesn't have a valid type. Valid types for this field are `ID` or `ID!` unless configured otherwise. While there may be a valid reason in your application to have that field defined that way, the Relay compiler and runtime will mishandle that field and cause refresh or data updating issues.
+
+## Disallowing `id` fields without type `ID`
+
+Recall that Relay uses [Object Identification](../../guides/graphql-server-specification/#object-identification) to know which GraphQL objects to refetch. In the usual case, those GraphQL objects implement the [`Node` interface](https://graphql.org/learn/global-object-identification/#node-interface) and thus come with an `id` field with type `ID`. However, there are types in your GraphQL model that may not require unique identification. For that reason, Relay (by default) does not restrict object definitions, allowing `id` fields with non-`ID` types (e.g. `String`) to be defined.
+
+This poses a bit of difficulty to both Relay's compiler and runtime. In short, the runtime and compiler only properly handle `id` fields as defined by the `Node` interface. Any selections made with non-`Node` `id` fields will likely exhibit undesirable and unintended Relay behavior on your components (e.g. components not re-rendering on re-fetched data).
+
+### The significance of the `ID` type
+
+[Global Object Identification in GraphQL](https://graphql.org/learn/global-object-identification/)) is what underlies Relay's Object Identification. The `id` field supplied by the `Node` interface is specified to be a unique identifier that can be used for storage or caching.
+
+## Fix: Define your `id` fields as `ID`
+
+To ensure Relay correctly manages objects fetched to your application, here are two recommended courses of action:
+
+* Ensure all fields named `id` are typed with `ID`
+* Rename any fields named `id` (with a type that isn't `ID`) to a different name (e.g. `special_purpose_id`)
+
+If your application truly requires that `id` field's definition to remain as-is and you are aware of the problems that may arise, you can add your GraphQL type and the type of its `id` field to the allowlist in `nonNodeIdFields` of the [Relay Compiler's Configuration](https://github.com/facebook/relay/tree/main/packages/relay-compiler). Note that this will only bypass the error for that combination of object type and `id` field type.
+
+<DocsRating />

package/llm-docs/debugging/inconsistent-typename-error.mdx

@@ -0,0 +1,47 @@
+---
+id: inconsistent-typename-error
+title: Inconsistent Typename Error
+slug: /debugging/inconsistent-typename-error/
+description: Debugging inconsistent typename errors in Relay
+keywords:
+- debugging
+- troubleshooting
+- inconsistent typename
+- RelayResponseNormalizer
+- globally unique id
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## Inconsistent `__typename` error
+
+The GraphQL server likely violated the globally unique ID requirement by returning the same ID for different objects.
+
+If you're seeing an error like:
+
+```
+`RelayResponseNormalizer: Invalid record '543'. Expected __typename to be consistent, but the record was assigned conflicting types Foo and Bar. The GraphQL server likely violated the globally unique ID requirement by returning the same ID for different objects.`
+```
+
+the server implementation of one of the types is not spec compliant. We require the `id` field to be globally unique. This is a problem because Relay stores objects in a normalized key-value store and one of the object just overwrote the other. This means your app is broken in some subtle or less subtle way.
+
+## Common cause
+
+The most common reason for this error is that 2 objects backed by an ID are using the plain ID as the id field, such as a `User` and `MessagingParticipant`.
+
+Less common reasons could be using array indices or auto-increment IDs from some database that might not be unique to this type.
+
+## Fix: Make your type spec compliant
+
+The best way to fix this is to make your type spec compliant. For the case of 2 different types backed by the same ID, a common solution is to prefix the ID of the less widely used type with a unique string and then base64 encode the result. This can be accomplished fairly easily by implementing a `NodeTokenResolver` using the helper trait `NodeTokenResolverWithPrefix`.  When the `NodeTokenResolver` is registered it allows you to load your type using `node(id: $yourID)` GraphQL call and your type can return an encoded ID.
+
+<FbInternalOnly>
+
+### Example
+
+See [D17996531](https://www.internalfb.com/diff/D17996531) for an example on how to fix this. It created a `FusionPlatformComponentsCategoryNodeResolver` added the trait `TGraphQLNodeMixin` to the conflicting class so that it generates the base64 encoded ID.
+
+</FbInternalOnly>
+
+<DocsRating />

package/llm-docs/debugging/relay-devtools.mdx

@@ -0,0 +1,73 @@
+---
+id: relay-devtools
+title: Relay DevTools
+slug: /debugging/relay-devtools/
+description: Debugging guide for the Relay DevTools
+keywords:
+- debugging
+- troubleshooting
+- extension
+- devtools
+- browser
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## Installation
+
+<FbInternalOnly>
+
+### Internal version (preferred)
+
+The internal version of devtools has the latest updates and the process of installation will be much faster.
+
+1. Before downloading the new Devtools, make sure you've deleted all older versions of the extension.
+2. Join [Relay Support](https://fb.workplace.com/groups/relay.support) group and you will automatically be added to the `cpe_relay_devtools_extension` gatekeeper.
+3. Wait 20-30 minutes, and it should be downloaded on your Chrome browser
+4. Or run `sudo soloctl -i` on your machine to get the extension immediately
+
+### Internal Version for Edgium users
+
+1. On `C:\Users\<User>\AppData\Local\Google\Chrome\User Data\<Work Profile>\Extensions` search for files manifest.json with Relay Developer Tools on it
+2. Get the path to this folder e.g `...\Extensions\<blob>\<version>\`
+3. On edge://extensions/ click load upacked (you might need to Allow extensions for other stores).
+
+### External version (use at your own risk)
+
+The external version of Dev Tools does not always contain the latest updates, it may stop working, potentially being restricted to be used or removed by corp device admin (via MDM).
+We recommend using the internal installation, but if you prefer, you may download the extension from the [Chrome store](https://chrome.google.com/webstore/detail/relay-developer-tools/ncedobpgnmkhcmnnkcimnobpfepidadl).
+
+</FbInternalOnly>
+
+<OssOnly>
+
+Follow this link and install it from the [chrome store](https://chrome.google.com/webstore/detail/relay-developer-tools/ncedobpgnmkhcmnnkcimnobpfepidadl).
+
+</OssOnly>
+
+---
+
+## How to Navigate the Relay DevTools Extension
+
+You should have a new tab called Relay in your Chrome DevTools. In this tab, you will be able to select between 2 panels: the **network panel** and the **store panel**.
+
+### Network Panel
+
+The network panel allows users to view individual requests in an active environment. Users can scroll through these requests, search for the requests and view the details of each request. The details of each request includes the status, the variables, and the responses for the request.
+
+###  Store Panel
+
+The store panel allows users to view individual records from the store data in an active environment. Users can scroll through these records, search for the records, and view the details of each request. Users can also copy the store data in JSON format to the clipboard. The details of each record includes the ID, the typename, and all of the data in the record. If one of the fields in the data is a reference to another record, users can click on the reference, which will take them to that record.
+
+---
+
+## Multiple Environments
+
+As you switch through the store and network panels, you'll notice that there is also a dropdown menu on the left side of the developer tools. This dropdown allows users to switch between environments. The requests in the network tab and the store data are grouped by environment, so users can easily shuffle between active environments.
+
+## Give Feedback
+
+Look in the top-right corner of the extension panel!
+
+<DocsRating />

package/llm-docs/debugging/why-null.mdx

@@ -0,0 +1,116 @@
+---
+id: why-null
+title: "Why Is My Field Null?"
+slug: /debugging/why-null/
+description: Get help figuring out why a given field is unexpectedly null.
+keywords:
+- "null"
+- missing
+- optional
+- nullthrows
+---
+
+import {FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+import DocsRating from '@site/src/core/DocsRating';
+
+There are a number of reasons that a field read by Relay can be null and some of them are obscure or unintuitive. When debugging an unexpectedly null value, it can be helpful to understand both the common cases and edge cases that can cause a field to be read as null. This document enumerates the cases that can lead to null or missing values with tips for determining which case you are in.
+
+## Server Returned Null
+
+The simplest reason a field might be null is that the server explicitly returned null. This can happen in two cases:
+
+1. The server’s field resolver returned an explicit null
+2. The field resolver throws. In this case GraphQL will return null for that field. *This is true even if the server resolver’s return type is non-nullable.* The one exception is fields annotated as non-null. In that case server should *never* return null. If an exception is encountered the entire parent object will be nulled out.
+
+<FbInternalOnly>
+
+:::note
+At Meta, non-nullable fields are implemented using [`KillsParentOnException`](https://www.internalfb.com/intern/wiki/Graphql-for-hack-developers/fields/return-type/#non-nullable-fields).
+:::
+
+</FbInternalOnly>
+
+**🕵️‍♀️ How to tell:** Inspect the server’s response using Relay Dev tools, or in your browser’s dev tools’s network tab, to see if the field is null.
+
+## Graph Relationship Change
+
+If a different query/mutation/subscription observes a relationship change in the graph, you may end up trying to read fields off of an object which your query never fetched.
+
+Imagine you have a query that reads your best friend’s name:
+
+```graphql
+query MyQuery {
+  me {
+    best_friend {
+      # id: 1
+      name
+    }
+  }
+}
+```
+
+After you get your query response, *who* your best friend is *changes* on the server. Then a *different* query/mutation/subscription fetches a different set of fields off of `best_friend`.
+
+```graphql
+query OtherQuery {
+  me {
+    best_friend {
+      # new id: 2
+      # Note: name is not fetched here
+      age
+    }
+  }
+}
+```
+
+Because the Relay store is normalized, we will update the `me` record to indicate that `best_friend` linked field now points to the user with ID 2, and the only information we know about that user is their age.
+
+This will trigger a rerender of `MyQuery`. However, when we try to read the `name` field off of the user with ID 2, we won’t find it, since the only thing we know about the user with ID 2 is their `age`. Note that a relationship “change” in this case, could also mean a relationship that is new. For example, if you start with no best friend but a subsequent response returns *some* best friend, but does not fetch all fields your component needs.
+
+**Note**: In theory, Relay *could* refetch your query when this state is encountered, but some queries are not safe to re-issue arbitrarily, and more generally, UI state changing in a way that’s not tied to a direct user action can lead to confusion. For this reason, we have chosen not to perform refetches in this scenario.
+
+**🕵️‍♀️ How to tell:** You can place a breakpoint/`console.log` at the finale return statement of `readWithIdentifier` in `FragmentResource` ([code pointer](https://github.com/facebook/relay/blob/2b9876fcbf0845cd23728d4d720712525ff424c4/packages/react-relay/relay-hooks/FragmentResource.js#L475). This is the point in Relay at which we know that we are missing data, but there is not query in flight to get it.
+
+## Inconsistent Server Response
+
+This is a **rare edge case**, *but* if the server does not correctly implement the [field stability](https://graphql.org/learn/global-object-identification/#field-stability) semantics of the id field, it’s possible that a field could be present in one part of the response, but *explicitly null* in another.
+
+```graphql
+{
+  me {
+    id: 1
+    name: "Alice"
+  }
+  me_elsewhere_in_the_graph {
+    id: 1 # Note this is the same as the `me` field above...
+    name: null
+  }
+}
+```
+
+In this case, Relay first learns that user 1’s `name` is Alice, but later in the query finds that user 1’s `name` has now `null`. Because Relay stores data in a normalized store, user 1 can only have one value for `name` and Relay will end in a state where user 1’s `name` is `null`.
+
+**🕵️‍♀️ How to tell:** Relay is smart enough to detect when this has happened, and will [log an error to the console](https://github.com/facebook/relay/blob/2b9876fcbf0845cd23728d4d720712525ff424c4/packages/relay-runtime/store/RelayResponseNormalizer.js#L505) in dev that looks like: “RelayResponseNormalizer: Invalid record. The record contains two instances of the same id: 1 with conflicting field, name and its values: Alice and null.". Additionally, you can manually inspect the query response.
+
+Note that if the unstable field is a linked field (edge to another object), this type of bug can cause a Graph Relationship Change (described above) to occur *within a single response*. For example, if a user with the same `id` appears in two places in the response, but their `best_friend` is different in those two locations.
+
+**🕵️‍♀️ How to tell:** Relay is also smart enough to detect this case, and will show a [similar console warning](https://github.com/facebook/relay/blob/2b9876fcbf0845cd23728d4d720712525ff424c4/packages/relay-runtime/store/RelayResponseNormalizer.js#L844) in dev.
+
+<FbInternalOnly>
+
+:::note
+Because these errors exist in the codebase and can cause noisy console output, these warnings are [disabled](https://www.internalfb.com/code/www/[5b26a6bd37e8]/html/shared/core/WarningFilter.js?lines=559) in dev mode.
+:::
+
+</FbInternalOnly>
+
+
+## Client-side Deletion or Incomplete Update
+
+Imperative store updates, or optimistic updates could have deleted the record or field. If an imperative store update, or optimistic update, writes a new record to the store, it may not supply a value for a field which you expected to be able to read. This is a fundamental problem, since an updater cannot statically know all the data that might be accessed off of a new object.
+
+**🕵️‍♀️ How to tell:** Due to React and Relay’s batching, it’s not always possible to associate a component update with the store update that triggered it. Here, your best bet is to set a breakpoint in your component for when your value is null, and then use the Relay Dev Tools to look at the last few updates.
+
+This can happen due to a newly created object which did not supply a specific field or, as mentioned above, an update which causes a new or changed relationship in the graph. In this case, use the “How do tell” tip from that section.
+
+<DocsRating />

package/llm-docs/editor-support.mdx

@@ -0,0 +1,55 @@
+---
+id: editor-support
+title: Editor Support
+slug: /editor-support/
+keywords:
+- LSP
+- Language Server Protocol
+- VS Code
+- VSCode
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+*TL;DR: We have a [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=meta.relay)*
+
+---
+
+The Relay compiler has a rich understanding of the GraphQL embedded in your code. We want to use that understanding to improve the developer experience of writing apps with Relay. So, starting in [v14.0.0](https://github.com/facebook/relay/releases/tag/v14.0.0), the new Rust Relay compiler can provide language features directly in your code editor. This means:
+
+#### Relay compiler errors surface as red squiggles directly in your editor
+
+<img src={useBaseUrl('img/docs/editor-support/diagnostics.png')} />
+
+#### Autocomplete throughout your GraphQL tagged template literals
+
+<img src={useBaseUrl('img/docs/editor-support/autocomplete.png')} />
+
+#### Hover to see type information and documentation about Relay-specific features
+
+<img src={useBaseUrl('img/docs/editor-support/hover.png')} />
+
+#### `@deprecated` fields are rendered using ~~strikethrough~~
+
+<img src={useBaseUrl('img/docs/editor-support/deprecated.png')} />
+
+#### Click-to-definition for fragments, fields and types
+
+<img src={useBaseUrl('img/docs/editor-support/go-to-def.gif')} />
+
+#### Quick fix suggestions for common errors
+
+<img src={useBaseUrl('img/docs/editor-support/code-actions.png')} />
+
+## Language Server
+
+The editor support is implemented using the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) which means it can be used by a variety of editors, but in tandem with this release, [Terence Bezman](https://twitter.com/b_ez_man) from [Coinbase](https://www.coinbase.com/) has contributed an official VS Code extension.
+
+[**Find it here!**](https://marketplace.visualstudio.com/items?itemName=meta.relay)
+
+## Why Have a Relay-Specific Editor Extension?
+
+The GraphQL foundation has an official language server and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) which provides editor support for GraphQL generically. This can provide a good baseline experience, but for Relay users, getting this information directly from the Relay compiler offers a number of benefits:
+
+* Relay compiler errors can surface directly in the editor as “problems”, often with suggested quick fixes
+* Hover information is aware of Relay-specific features and directives and can link out to relevant documentation

package/llm-docs/error-reference/unknown-field.mdx

@@ -0,0 +1,36 @@
+---
+id: unknown-field
+title: "Why Is My Field Not Found?"
+slug: /error-reference/unknown-field/
+description: Get help figuring out why a given field is not found.
+keywords:
+- no such field on type
+- missing
+- field
+- type
+- compilation
+- error
+---
+
+import {FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+import DocsRating from '@site/src/core/DocsRating';
+
+## [ERROR] Error in the project `some_project`: ✖︎ The type `Some_Type` has no field `some_unknown_field`.
+
+### Field name typo
+
+In case of a missing field in a type, the Relay compiler tries to find and suggest a field replacement. For example: ```Error in the project `some_project`: ✖︎ The type `UserInfo` has no field `mail`. Did you mean `email`?```
+
+<FbInternalOnly>
+
+### The field exists in another schema
+
+Relay Compiler uses schemas in order to resolve types and their fields. The type's schema is determined by the file path and the mapping from file path to schema, which is configured in the "schema" or "schemaDir" properties of your Relay compiler config. If you expect this field to exist, make sure you're using the right schema.
+
+:::note
+At meta there are various project config files that are listed [here](https://www.internalfb.com/intern/wiki/Relay-team/Rust_compiler_resources/#where-are-the-project-co).
+:::
+
+</FbInternalOnly>
+
+<DocsRating />