relay-runtime 20.1.0 → 21.0.0

package/llm-docs/glossary/glossary.mdx

@@ -0,0 +1,1040 @@
+---
+id: glossary
+title: Glossary
+slug: /glossary/
+description: Relay terms glossary
+keywords:
+- glossary
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
+
+## 3D
+
+Data-Driven Dependencies. Facebook's way of including the code to render a particular component if and only if it will actually be rendered. Canonical use cases are
+
+* **Fields that are typically null**, and which are only rendered when not null.
+* **Unions**. For example, the core news feed item has many different variants, each of which is a separate React component. Which one we render depends on the data (i.e. is "data-driven"). On a given feed, it is likely that most variants will not be rendered, and need not be downloaded.
+* **Component can have different rendering strategies, depending on the data.**
+
+<FbInternalOnly>
+
+See the [@match](#match) directive, [@module](#module) directive and [the 3D guide](../guides/data-driven-dependencies/server-3d).
+
+</FbInternalOnly>
+
+<OssOnly>
+
+See the [@match](#match) directive and the [@module](#module) directive.
+
+</OssOnly>
+
+## Abstract Type
+
+GraphQL unions and interfaces are abstract types. See [interface](#interface-graphql).
+
+## Abstract Type Refinement
+
+See [type refinement](#type-refinement). If type refinement is a way of conditionally including fields if a type implements a particular concrete type (such as `... on User { name }`), abstract type refinement refers to conditionally including fields if a type implements a particular abstract type (i.e. interface). So, `... on Actor { field }`.
+
+## @arguments
+
+A [directive](#directive) that modifies a [fragment spread](#fragment-spread) and is used to pass arguments (defined with [`@argumentDefinitions`](#argumentdefinitions)) to that fragment.
+
+```graphql
+...Story_story @arguments(storyId: "1234")
+```
+
+## @argumentDefinitions
+
+A directive that modifies a fragment definition and defines the names of the local arguments that the fragment can take, as well as their type.
+
+```graphql
+fragment Store_story on Story
+  @argumentDefinitions(storyId: {type: "ID!"}) {
+  # etc
+}
+```
+
+If a variable is used in a fragment but not included in an `@argumentDefinitions` directive, Relay will require that the fragment is only spread in queries which declare these variables, or in fragments which ultimately are spread in such a query.
+
+Compare with [variables](#variables) and see the [relevant section](../guided-tour/rendering/variables) in the guided tour.
+
+## Artifact
+
+Files that are generated by the [Relay compiler](../getting-started/compiler.mdx), typically ending in `.graphql.js`.
+
+<FbInternalOnly>
+
+See [a guide to Relay artifacts](https://www.internalfb.com/intern/wiki/Relay-team/generated-artifacts/).
+
+</FbInternalOnly>
+
+## AST
+
+Abstract Syntax Tree. In Relay, there are two types of ASTs, [normalization](#normalization-ast) and [reader](#reader-ast) ASTs.
+
+The default export of a `.graphql.js` file is an AST.
+
+The Relay compiler parses and transforms GraphQL literals, and generates Relay ASTs (see [artifact](#artifact)). Doing this work at compile time allows the Relay runtime to be faster.
+
+## Availability
+
+The concept of availability refers to whether there is enough non-stale, non-invalidated data in the store to fulfill a particular request immediately, or whether a request to server needs to be made in order to fulfill that request.
+
+## Babel Transform
+
+A build-time transformation of the Javascript codebase, which turns calls to
+
+```javascript
+graphql`...`
+```
+
+into `require(NAME_OF_GENERATED_ARTIFACT)` calls. See [Babel Plugin](../getting-started/babel-plugin.mdx).
+
+## Client Schema Extension
+
+[The GraphQL spec](https://spec.graphql.org/June2018/#sec-Schema-Extension) allows you to define new types, new fields on types, new directives, etc. locally.
+
+Relay supports adding types and fields in client schema extension files. Developers use this feature to add fields that contain purely local state that is associated with items on the graph. For example, an `is_selected` field on a `User`.
+
+## CacheConfig
+
+A value used to control how a query's response may be cached. Ultimately passed to `environment.execute`.
+
+## Check
+
+One of the core functions of the store. Given an operation, determines whether the store has all of the data necessary to render that operation. Calls `DataChecker.check`, which synchronously starts with the root node associated with the operation and walks the data in the store.
+
+In practice, exposed as a method on `environment`.
+
+In conjunction with the fetch policy, used by `loadQuery` (and other methods) to determine whether it is necessary to make a network request call to fulfill a query.
+
+## Commit
+
+After receiving a network response, the payload is committed, or written to the store.
+
+Commit is also the verb used to describe initiating a mutation and writing its data to the store.
+
+## Compiler
+
+The piece of code which scans your Javascript files for `graphql` tagged nodes and generates the appropriate files (`.graphql.js` files, `$Parameters.js` files, etc.)
+
+The generated output from the compiler is committed and checked into the repository.
+
+## Concrete Request
+
+An Abstract Syntax Tree representing a query, subscription or mutation.
+
+The default export of a `.graphql.js` file corresponding to a query, subscription or mutation.
+
+In addition, calls to `graphql`...`` are turned into concrete requests at build time via the Relay Babel transform.
+
+**See the important safety notes at Preloadable Concrete Request.**
+
+## Config
+
+A [file or javascript object](../getting-started/compiler-config.mdx) which controls, among other things, which files are scanned by the Relay [compiler](#compiler) for your project.
+
+## @connection
+
+A directive which declares that a field implements the [connection](#connection) spec.
+
+## Connection
+
+<FbInternalOnly>
+
+A field implementing the [connection spec](https://relay.dev/graphql/connections.htm). See <a href="https://www.internalfb.com/intern/wiki/Graphql-connections-for-hack-developers/Connection-spec/">here</a> for more details on the spec, and the section of the guided tour on <a href="../guided-tour/list-data/pagination/">rendering list data and pagination</a>.
+
+</FbInternalOnly>
+
+<OssOnly>
+
+A field implementing the [connection spec](https://relay.dev/graphql/connections.htm). See the section of the guided tour on <a href="../guided-tour/list-data/pagination/">rendering list data and pagination</a>.
+
+</OssOnly>
+
+See also [`usePaginationFragment`](../api-reference/use-pagination-fragment).
+
+## Container
+
+A term for a higher order component that provided a child component with the data from queries and fragments. Associated with Relay Modern.
+
+You should use the Relay hooks API when possible.
+
+## Data Checker
+
+A class exposing a single method, `check`, which synchronously starts with the root node associated with the operation and walks the data in the store. It determines whether the data in the store suffices to fulfill a given operation.
+
+Called by `store.check`.
+
+## DataID
+
+The globally-unique identifier of a record. Can be generated on the client with [missing field handlers](#missing-field-handler). Usually corresponds to an Ent's ID (if available), but guaranteed to equal the value of the `__id` field.
+
+[`updater`](#updater) and [`optimisticUpdater`](#optimisticupdater) functions are passed instances of [`RelaySourceSelectorProxy`](#recordproxy). Calling `.get(id)` with the DataID on a `RelaySourceSelectorProxy` will look up that item in the store, and return a proxy of it.
+
+## Data Masking
+
+Refers to the idea that a component should not be able to access any data it does declare in its fragment or query, even inadvertently. This prevents accidental coupling of data between components, and means that every component can be refactored in isolation. It negates the risk that removing a field in a child component will accidentally break a different component, allowing components to *move fast, with stable infrastructure*.
+
+Also refers to the practice of hiding the data of child components from their parents, in keeping with the idea.
+
+In Relay, a query declared like `query FooQuery { viewer { ...subcomponent_``viewer_name } }` will not be able to access the data declared by `subcomponent_viewer_name` without access to the `ReaderFragment` representing the `subcomponent_viewer_name` fragment.
+
+See the [Thinking in Relay guide](../principles-and-architecture/thinking-in-relay#data-masking).
+
+## @defer
+
+A directive which can be added to a fragment spread or inline fragment to avoid blocking on that fragment's data. For more detail refer to GraphQL's [documentation on the @defer directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.mdx#defer).
+
+<FbInternalOnly>
+
+See [Incremental Data Delivery](https://www.internalfb.com/intern/staticdocs/relay/docs/guides/incremental-data-delivery/).
+
+</FbInternalOnly>
+
+## Definition
+
+In the compiler, a definition refers to the text within a GraphQL literal where an operation or fragment was defined.
+
+## Descriptor
+
+Can refer to an `OperationDescriptor` or `RequestDescriptor`. Descriptors are types used internally to the Relay codebase, and generally, refer to an object containing the minimum amount of information needed to uniquely identify an operation or request, such as (for a `RequestIdentifier`), a node, identifier and variables.
+
+## DevTools
+
+An awesome Chrome extension for debugging Relay network requests, the Relay store and Relay events. Helpful for answering questions like "Why am I not seeing the data I expect to see?" "Why did this component suspend?" etc.
+
+See the [documentation](https://relay.dev/docs/debugging/relay-devtools/).
+
+## Document
+
+In the compiler, a Document refers to a GraphQL literal that contains one or more operation or fragment [definitions](#definition). Relay requires that GraphQL literals in JavaScript files contain a single definition.
+
+## Directive
+
+A special instruction, starting with `@` and contained in a `graphql` literal or graphql file, which provides special instructions to the Relay compiler or to the server. Examples include `@defer`, `@stream` and `@match`.
+
+## Disposable
+
+Any object which contains a `.dispose` method which takes no parameters and provides no return value. Many objects in Relay (such query references and entrypoint references) and the return value of many methods (such as calls to `.subscribe` or `.retain`) are disposables.
+
+## Entrypoint
+
+A lightweight object containing information on the components which need to be loaded (as in the form of calls to `JSResource`) and which queries need to be loaded (in the form of preloadable concrete requests) before a particular route, popover or other piece of conditionally loaded UI can be rendered.
+
+All queries which are required for the initial rendering of a piece of UI should be included in that UI's entrypoint.
+
+Entrypoints can contain queries and other entrypoints.
+
+See also [preloadable concrete request](#preloadable-concrete-request) and [JSResource](#jsresource).
+
+## Environment
+
+An object bringing together many other Relay objects, most importantly a store and a network. Also, includes a publish queue, operation loader, scheduler and [missing fields handlers](#missing-field-handler).
+
+Set using a `RelayEnvironmentProvider` and passed down through React context.
+
+All non-internal Relay hooks require being called within a Relay environment context.
+
+## Execute
+
+Executing a query, mutation or subscription (collectively, an operation) roughly means "create a lazy observable that, when subscribed to, will make a network request fulfilling the operation and write the returned data to the store."
+
+A variety of `execute` methods are exposed on the Relay environment.
+
+## Fetch Policy
+
+A string that determines in what circumstances to make a network request in which circumstances to fulfill the query using data in the store, if available. Either `network-only`, `store-and-network`, `store-or-network` or `store-only`. (Some methods do not accept all fetch policies.)
+
+## Field
+
+Basically, anything you can select using a query, mutation, subscription or fragment. For example, `viewer`, `comment_create(input: $CommentCreateData)` and `name` are all fields.
+
+The GraphQL schema comprises many fields.
+
+## Fragment
+
+Fragment is an overloaded term, and has at least two distinct meanings in Relay.
+
+### Fragments as a GraphQL concept
+
+The fundamental reusable unit of GraphQL. Unlike queries, subscriptions and mutations, fragments cannot be queried on their own and must be embedded within a request.
+
+Fragments can be spread into queries, mutations, subscriptions and other fragments.
+
+Fragments can be standalone (as in `fragment Component_user on User { name }`) or inline, as in the `... on User { name }` in `query MyQuery { node(id: $id) { ... on User { name } } }`.
+
+Fragments are always defined on a particular type (`User` in the example), which defines what fields can be selected within it.
+
+### Fragments within Relay
+
+Within Relay, a fragment refers to the fields that are read out for a given fragment/operation. The term is also used colloquially to refer to reader ASTs. So, e.g. the following query and fragment might have identical reader ASTs:
+
+```graphql
+query Foo {
+  actor { name }
+}
+```
+
+```
+fragment Bar on Query {
+  actor { name }
+}
+```
+
+## Fragment Identifier
+
+A string, providing enough information to provide the data for a particular fragment. For example:
+
+`1234{"scale":2}/Story_story/{"scale":2}/"4567"`
+
+This identifies by its persist ID (`1234`), followed by the variables it accepts, followed by the `Story_story` fragment (which does not have a persist id) and the variables it uses, followed by the Data ID (likely, the `id` field) of whatever Story happened to be referenced.
+
+## Fragment Reference
+
+A parameter passed to `useFragment`. Obtained by accessing the value onto which a fragment was spread in another [query](#query), fragment, subscription or mutation. For example,
+
+```javascript
+const queryData = usePreloadedQuery(
+  graphql`query ComponentQuery { viewer { account_user { ...Component_name } } }`,
+  {},
+);
+
+// queryData.viewer is the FragmentReference
+// Though this would usually happen in another file, you can
+// extract the value of Component_name as follows:
+const fragmentData = useFragment(
+  graphql`fragment Component_name on User { name }`,
+  queryData?.viewer?.account_user,
+);
+```
+
+Just like a query reference and a graphql tagged literal describing a query (i.e. a concrete request) can be used to access the data from a query, a fragment reference and a graphql tagged literal describing a fragment (i.e. a reader fragment) can be used to access the data referenced from a fragment.
+
+## Fragment Resource
+
+An internal class supporting lazily loaded queries. Exposes two important methods:
+
+* `read`, which is meant to be called during a component's render phase. It will attempt to fulfill a query from the store (by calling `environment.lookup`) and suspend if the data is not available. It furthermore writes the results from the attempted read (whether a promise, error or result) to an internal cache, and updates that cached value when the promise resolves or rejects.
+* `subscribe`, which is called during the commit phase, and establishes subscriptions to the Relay store.
+
+If the component which calls `.read` successfully loads a query, but suspends on a subsequent hook before committing, the data from that query can be garbage collected before the component ultimately renders. Thus, components which rely on `FragmentResource` are at risk of rendering null data.
+
+Compare to [query resource](#query-resource).
+
+## Fragment Spread
+
+A fragment spread is how one fragment is contained in a query, subscription, mutation or other fragment. In the following example, `...Component_name` is a fragment spread:
+
+```graphql
+query ComponentQuery {
+  viewer {
+    account_user {
+      ...Component_name
+    }
+  }
+}
+```
+
+In order for a fragment to be spread in a particular location, the types must match. For example, if `Component_name` was defined as follows: `fragment Component_name on User { name }`, this spread would be valid, as `viewer.account_user` has type `User`.
+
+## Garbage Collection
+
+Relay can periodically garbage collect data from queries which are no longer being retained.
+
+See more information in the [guided tour](https://relay.dev/docs/guided-tour/reusing-cached-data/presence-of-data/#garbage-collection-in-relay).
+
+## GraphQLTaggedNode
+
+This is the type of the call to
+
+```js
+graphql`...`
+```
+
+It is the union of ReaderFragment, ReaderInlineDataFragment, ConcreteRequest, and ConcreteUpdatableQuery.
+
+<OssOnly>
+
+Note that Flow can be configured to understand that the type of a GraphQL literal is the type of the default export of the generated `.graphql.js` file.
+
+</OssOnly>
+
+<FbInternalOnly>
+
+Note that Flow is configured to understand that the type of a GraphQL literal is the type of the default export of the generated `.graphql.js` file.
+
+</FbInternalOnly>
+
+## ID
+
+Relay treats ids specially. In particular, it does the following two things:
+
+* The compiler automatically adds a selection of the `id` field on every type where the `id` field has type `ID` or `ID!`.
+* When [normalizing](#normalization) data, if an object has an `id` property, that field is used as its ID in the store.
+
+There are types in the schema where the `id` field does not have type `ID` or `ID!` (e.g. has the type `string` or `number`). If a user selects this field themselves, this field is used as an id. This is unexpected and incorrect behavior.
+
+## @include
+
+A directive that is added to fields, inline fragments and fragment spreads, and allows for conditional inclusion. It is the opposite of the [`@skip`](#skip) directive.
+
+In the compiler, the `@include`/`@skip` directives are treated specially, and produce `Condition` nodes.
+
+## @inline
+
+A directive that applies to fragments which enables developers to pass masked data to functions that are executed outside of the React render phase.
+
+Normally, data is read out using `useFragment`. However, this function can only be called during the render phase. If store data is needed outside of the render phase, a developer has several options:
+
+* read that data during the render phase, and pass it to the function/have the function close over that data. (See also [#relay])
+* pass a reference to an `@inline` fragment, which can then be accessed (outside of the render phase) using the `readInlineData` function.
+
+This directive causes them to be read out when the parent fragment is read out, and unmasked by the call to `readInlineData`.
+
+## Interface (GraphQL)
+
+An *Interface* is an abstract type that includes a certain set of fields that a type must include to implement the interface.
+
+You can spread a fragment on an interface onto a concrete type (for example `query MyQuery { viewer { account_user { ...on Actor { can_viewer_message } } }`) or a fragment on a concrete type onto an interface (for example `query MyQuery { node(id: 4) { ... on User { name } } }`). You are no longer allowed to spread a fragment on an interface onto an interface.
+
+See also abstract type refinement.
+
+## Invalidation
+
+In certain cases, it is easy to determine the outcome of a mutation. For example, if you "like" a Feedback, the like count will increment and `viewer_did_like` will be set to true. However, in other cases, such as when you are blocking another user, the full impact on the data in your store is hard to determine.
+
+For situations like these, Relay allows you to invalidate a record (or the whole store), which will cause the data to be re-fetched the next time it is rendered.
+
+See the [section in the guide](https://relay.dev/docs/guided-tour/reusing-cached-data/staleness-of-data/).
+
+## JSResource
+
+A lightweight API for specifying that a React component should be loaded on demand, instead of being bundled with the first require (as would be the case if you imported or required it directly.)
+
+This API is safe to use in entrypoint files.
+
+<OssOnly>
+
+See [the npm module](https://www.npmjs.com/package/jsresource).
+
+</OssOnly>
+
+## Lazy Loading
+
+A query or entry point is lazy loaded if the request for the data occurs at render time.
+
+Lazy loaded queries and entry points have performance downsides, are vulnerable to being over- and under-fetched, and can result in components being rendered with null data. They should be avoided.
+
+## Linked Record
+
+A linked record is a record that is directly accessible from another record. For example, in the query `query MyQuery { viewer { account_user { active_instant_game { id } } } }`, `active_instant_game` (which has the type `Application` is a linked record of `account_user`.
+
+A linked record cannot be queried by itself, but must be queried by selecting subfields on it.
+
+Compare to [value](#value).
+
+## Literal
+
+A GraphQL literal is a call to
+
+```javascript
+graphql`...`
+```
+
+in your code. These are pre-processed, and replaced at build time with a [GraphQLTaggedNode](#graphqltaggednode) containing an [AST](#ast) representation of the contents of the literal.
+
+## @live
+
+A docblock tag that can be added to mark a Relay resolver as live. To learn more, refer to the [live fields section](https://relay.dev/docs/guides/relay-resolvers/live-fields/) of the Relay resolver documentation.
+
+<FbInternalOnly>
+
+## @live_query
+A directive used on GraphQL queries that enables data updates to be delivered over time without any custom server-side code. This directive provides a more efficient and maintainable alternative to polling (running the same query over and over again).
+
+Live queries are a feature of GraphQL within Meta and supported by the [Real-Time GraphQL team](https://www.internalfb.com/omh/view/real_time_graphql/oncall_profile). To learn more about GraphQL live queries, refer to the [GraphQL Live Queries wiki](https://www.internalfb.com/intern/wiki/GraphQL_Live_Queries/Overview/).
+
+You can learn more about how to use @live_query with Relay on Web with server-polling [here](https://www.internalfb.com/intern/wiki/GraphQL_Live_Queries/Live_Queries_for_Relay/) and client-polling [here](https://www.internalfb.com/intern/wiki/GraphQL_Live_Queries/Live_Queries_for_Relay_(Client_Polling)/).
+</FbInternalOnly>
+
+## Lookup
+
+One of the main methods exposed by the Relay store. Using a [reader selector](#reader-selector), traverses the data in the store and returns a [snapshot](#snapshot), which contains the data being read, as well as information about whether data is missing and other pieces of information. Also exposed via the Relay environment.
+
+Calls [`Reader.read`](#reader).
+
+## @match
+
+A directive that, when used in combination with [@module](#module), allows users to download specific JS components alongside the rest of the GraphQL payload if the field decorated with @match has a certain type. See [3D](#3d).
+
+## MatchContainer
+
+A component that renders the component returned in conjunction with a field decorated with the [@match](#match) directive. See [3D](#3d).
+
+## Missing Field Handler
+
+A function that provides a [DataID](#dataid) for a field (for singular and plural linked fields) and default values (for scalar fields).
+
+For example, you may have already fetched an item with id: 4, and are executing a query which selects `node(id: 4)`. Without a missing field handler, Relay would not know that the item with id: 4 will be returned by `node(id: 4)`, and would thus attempt to fetch this data over the network. Providing a missing field handler can inform Relay that the results of this selection are present at id: 4, thus allowing Relay to avoid a network request.
+
+`getRelayFBMissingFieldHandlers.js` provides this and other missing field handlers.
+
+## @module
+
+A directive that, when used in combination with [@match](#match), allows users to specify which JS components to download if the field decorated with @match has a certain type. See [3D](#3d).
+
+## Module
+
+A ["Module"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) refers to a React component or a piece of JavaScript code.
+
+In the context of Relay, modules can by dynamically loaded with the @module directive. This directive allows developers to specify which JavaScript components should be downloaded (from a CDN for example) based on the type of a field decorated with the @match directive. This approach is part of Relay's [data-driven dependencies](#3d) strategy, where components are only loaded if they are actually needed for rendering.
+
+## Mutation
+
+A mutation is a combination of two things: a mutation on the backend, followed by query against updated data.
+
+<FbInternalOnly>
+
+See the [guide on mutations](../guided-tour/updating-data/graphql-mutations), and [this article](https://www.internalfb.com/intern/wiki/Graphql-for-hack-developers/mutation-root-fields/) on defining mutations in your hack code.
+
+</FbInternalOnly>
+
+<OssOnly>
+
+See the [guide on mutations](../guided-tour/updating-data/graphql-mutations).
+
+</OssOnly>
+
+## Mutation Root Query
+
+The root object of a mutation query. In an `updater` or `optimisticUpdater`, calling `store.getRootField('field_name')` will return the object from the mutation root query named `field_name`.
+
+The fields exposed on this object are **not** the same as those available for queries, and differ across mutations.
+
+## Network
+
+Relay environments contain a `network` object, which exposes a single `execute` function. All network requests initiated by Relay will go through this piece of code.
+
+This provides a convenient place to handle cross-cutting concerns, like authentication and authorization.
+
+## Node
+
+A Node is an object that implements the Node interface in GraphQL, which requires an `id` field of type `ID`. This is part of the [Global Object Identification specification](https://relay.dev/graphql/objectidentification.htm) that provides a standardized way to fetch and identify objects in a GraphQL schema.
+
+In Relay, the Node interface is fundamental to how data normalization and caching work. When Relay encounters an object with an `id` field, it uses that ID as the key for storing the object in its normalized cache. This enables efficient data deduplication, updates, and garbage collection.
+
+Nodes can be refetched using the `node` field on the Query root type by passing their global ID: `query { node(id: "abc123") { ... } }`. This allows Relay to fetch data for any object implementing the Node interface without needing to know the specific field path to that object.
+
+## Normalization
+
+Normalization is the process of turning nested data (such as the server response) and turning it into flat data (which is how Relay stores it in the store.)
+
+See the [response normalizer](#response-normalizer).
+
+## Normalization AST
+
+An [AST](#ast) that is associated with an [operation](#operation) that (in combination with [variables](#variables)) can be used to:
+* write a network payload to the store,
+* write an optimistic response to the store,
+* determine whether a query can be fulfilled from data in the store, and
+* determine which records in the store are reachable (used in [garbage collection](#garbage-collection)).
+
+Unlike the [reader AST](#reader-ast), the normalization AST includes information on the contents of nested fragments.
+
+The generated artifact associated with an operation (e.g. `FooQuery.graphql.js`) contains both a normalization AST and a reader AST.
+
+## Normalization Selector
+
+A selector defines the starting point for a traversal into the graph for the purposes of targeting a subgraph, combining a GraphQL fragment, variables, and the Data ID for the root object from which traversal should progress.
+
+## Notify
+
+A method exposed by the store which will notify each [subscriber](#subscribe) whose data has been modified. Causes components which are rendering data that has been modified to re-render with new data.
+
+## Observable
+
+The fundamental abstraction in Relay for representing data that may currently be present, but may also only be available in the future.
+
+Observables differ from promises in that if the data in an observable has already been loaded, you can access it synchronously as follows:
+
+```javascript
+const completedObservable = Observable.from("Relay is awesome!");
+let valueFromObservable;
+observable.subscribe({
+  next: (value) => {
+    valueFromObservable = value;
+    /* this will execute in the same tick */
+  },
+});
+console.log(valueFromObservable); // logs out "Relay is awesome!"
+```
+
+This is advantageous, as it allows Relay hooks to not suspend if data is already present in the store.
+
+In Relay, observables are a partial implementation of [RxJS Observables](https://rxjs-dev.firebaseapp.com/guide/observable).
+
+## Operation
+
+In [GraphQL](https://spec.graphql.org/June2018/#sec-Language.Operations), a query, subscription or mutation.
+
+In Relay, every operation also has an associated [fragment](#fragments-within-relay). So, an accurate mental model is that operations are fragments whose [type condition](#type-condition) is that they are on [Query/Mutation/Subscription](#root-type) and for which Relay knows how to make a network request.
+
+## Operation Descriptor
+
+Colloquially, an operation descriptor is an operation and variables.
+
+The operation descriptor flowtype contains the three pieces of information that Relay needs to work with the data: [a reader selector](#reader-selector), a [normalization selector](#normalization-selector) and a [request descriptor](#request-descriptor).
+
+The variables are filtered to exclude unneeded variables and are populated to include default values for missing variables, thus ensuring that requests that differ in irrelevant ways are cached using the same request ID.
+
+## Operation Mock Resolver
+
+A function taking an operation descriptor and returning a network response or error, used when testing.
+
+## Operation Tracker
+
+The Relay Operation Tracker is a component within the Relay runtime that manages and tracks the lifecycle of [operations](#operation) (queries, subscriptions, and mutations), in the Relay store. It maintains mappings between operations and affected data owners, manages promises for asynchronous updates, and resolves dependencies by notifying subscribers when data changes, ensuring components render with the latest data. For more implementation details of the Operation Tracker, see the [OSS code here](https://github.com/facebook/relay/blob/main/packages/relay-runtime/store/RelayOperationTracker.js).
+
+## Optimistic Update
+
+An Optimistic Update in Relay is a technique used to immediately reflect the expected outcome of a mutation in the UI before the server response is received.
+
+This approach enhances user experience by providing instant feedback for actions, such as liking a post, without waiting for the server to confirm the change.
+
+Optimistic updates assume the mutation will succeed and temporarily update the store with the anticipated result. If the mutation fails, the optimistic update is rolled back to maintain data consistency. This is typically achieved by providing an optimisticResponse in the mutation configuration, which specifies the expected changes to the data.
+
+See the [documentation on optimistic updates](../guided-tour/updating-data/graphql-mutations/#optimistic-updates) for examples of how to use this feature.
+
+## Optimistic Updater
+
+An Optimistic Updater in Relay is a function that allows developers to imperatively modify the store's data in anticipation of a mutation's success.
+
+Unlike [optimistic responses](../guided-tour/updating-data/graphql-mutations/#optimistic-response), which are declarative, optimistic updaters provide more control and flexibility, enabling updates to data not directly selected in the mutation or complex changes that cannot be handled by declarative mutation directives.
+
+Optimistic updaters are executed when a mutation is triggered and are rolled back if the mutation fails. They are particularly useful for scenarios where multiple optimistic responses affect the same store value, and fine grained control is needed by the developer to ensure that the store remains consistent.
+
+See the documentation on [optimistic updaters](../guided-tour/updating-data/graphql-mutations/#optimistic-updaters) for examples of how to use them.
+
+## Pagination
+
+Querying a list of data (a [connection](#connection)) in parts is known as pagination.
+
+See the [graphql docs](https://graphql.org/learn/pagination/) and our [guided tour](../guided-tour/list-data/pagination).
+
+## Payload
+
+The value returned from the GraphQL server as part of the response to a request.
+
+## Plural Field
+
+A field for which the value is an array of [values](#value) or [records](#record).
+
+## @preloadable
+
+A directive that modifies queries and which causes Relay to generate `$Parameters.js` files and preloadable concrete requests. Required if the query is going to be used as part of an entry point.
+
+## Preloadable Concrete Request
+
+A small, lightweight object that provides enough information to initiate the query and fetch the full query AST (the `ConcreteRequest`.) This object will only be generated if the query is annotated with `@preloadable`, and is the default export of `$parameters.js` files. It is only generated for queries which are annotated with `@preloadable`.
+
+Unlike concrete requests (the default export of `.graphql.js` files), preloadable concrete requests are extremely light weight.
+
+Note that entrypoints accept either preloadable concrete requests or concrete requests in the `.queries[queryName].parameters` position. However, ***because a concrete request is not a lightweight object, you should only include preloadable concrete requests here.***
+
+Note also that preloadable queries have `id` fields, whereas other queries do not.
+
+## Preloadable Query Registry
+
+A central registry which will execute callbacks when a particular Query AST (concrete request) is loaded.
+
+Required because of current limitations on dynamically loading components in React Native.
+
+## Project
+
+For Relay to process a file with a GraphQL literal, it must be included in a project. A project specifies the folders to which it applies and the schema against which to evaluate GraphQL literals, and includes other information needed by the Relay compiler.
+
+<FbInternalOnly>
+
+Projects are defined in a single [config](#config) file, found [here](https://www.internalfb.com/intern/diffusion/WWW/browse/master/scripts/relay/compiler-rs/config.www.json) and [here](https://www.internalfb.com/intern/diffusion/FBS/browse/master/xplat/relay/compiler-rs/config.xplat.json).
+
+</FbInternalOnly>
+
+## Publish
+
+One of the main methods exposed by the `store`. Accepts a [record source](#record-source), from which the records in the store are updated. Also updates the mapping of which records in the store have been updated as a result of publishing.
+
+One or more calls to `publish` should be followed by a call to [`notify`](#notify).
+
+## Publish Queue
+
+A class used internally by the environment to keep track of, apply and revert pending (optimistic) updates; commit client updates; and commit server responses.
+
+Exposes mutator methods like `commitUpdate` that only add or remove updates from the queue, as well as a `run` method that actually performs these updates and calls `store.publish` and `store.notify`.
+
+## Query
+
+A [GraphQL query](https://graphql.org/learn/queries/) is a request that can be sent to a GraphQL server in combination with a set of [variables](../guided-tour/rendering/variables), in order to fetch some data. It consists of a [selection](#selection) of fields, and potentially includes other [fragments](#fragment).
+
+## Query Executor
+
+A class that normalizes and publishes optimistic responses and network responses from a network observable to the store.
+
+After each response is published to the store, `store.notify` is called, updating all components that need to re-render.
+
+Used by `environment` in methods such as `execute`, `executeWithSource` and `executeMutation`, among others.
+
+## Query Reference
+
+A Query Reference is an opaque token that represents a query that we have started fetching, but may not have been returned by the network yet. It's returned by functions like `loadQuery` and serves as an identifier for which query we want to render.
+
+Query references are intentionally opaque to the user - they don't expose the query's internal state or data directly. Instead, they are passed to `usePreloadedQuery` to access the data from a preloaded query.
+
+The query reference pattern enables efficient data loading by allowing queries to be initiated early (such as in response to user interactions like hovering or route changes) and then consumed later when the component actually renders.
+
+Query references are disposable objects - they should be disposed of when no longer needed to prevent memory leaks and allow proper cleanup of network requests and subscriptions.
+
+## Query Resource
+
+A class for helping with lazily loaded queries and exposing two important methods: `prepare` and `retain`.
+
+* `prepare` is called during a component's render method, and will either read an existing cached value for the query, or fetch the query and suspend. It also stores the results of the attempted read (whether the data, a promise for the data or an error) in a local cache.
+* `retain` is called after the component has successfully rendered.
+
+If the component which calls `.prepare` successfully loads a query, but suspends on a subsequent hook before committing, the data from that query can be garbage collected before the component ultimately renders. Thus, components which rely on `QueryResource` are at risk of rendering null data.
+
+Compare to [fragment resource](#fragment-resource).
+
+## `@raw_response_type`
+
+A directive added to queries which tells Relay to generate types that cover the `optimisticResponse` parameter to `commitMutation`.
+
+See the [guided tour on updating data](../guided-tour/updating-data/graphql-mutations/#optimistic-response) for more.
+
+## Reader
+
+A core component of the Relay runtime responsible for reading data from the store. The Reader traverses the normalized data in the store using a [reader AST](#reader-ast) and constructs the denormalized data structure that matches the shape expected by components.
+
+The Reader is called by the store's [lookup](#lookup) method and is fundamental to how Relay provides data to React components. It handles data masking by only exposing the fields that were explicitly selected in fragments and queries, ensuring components can only access the data they declared dependencies for.
+
+The Reader also manages missing data detection, determining when insufficient data is available in the store to fulfill a request, which helps Relay decide when network requests are necessary.
+
+## Reader AST
+
+An [AST](#AST) that is used to read the data selected in a given fragment.
+
+Both [operations](#operation) and [fragments](#fragment) have reader ASTs.
+
+A reader AST contains information about which fragments are spread at a given location, but unlike a [normalization AST](#normalization-ast), does not include information about the fields selected within these fragments.
+
+## Reader Fragment
+
+TODO
+
+See [GraphQLTaggedNode](#graphqltaggednode).
+
+## Reader Selector
+
+An object containing enough information for the store to traverse its data and construct an object represented by a query or fragment. Intuitively, this "selects" a portion of the object graph.
+
+See also [lookup](#lookup).
+
+## Record
+
+A record refers to any item in the Relay [store](#store) that is stored by [ID](#id). [Values](#value) are not records; most everything else is.
+
+## Record Source
+
+An abstract interface for storing [records](#record), keyed by [DataID](#dataid), used both for representing the store's cache for updates to it.
+
+## Record Source Selector Proxy
+
+See [record proxy](#record-proxy).
+
+## Record Proxy
+
+See the [store documentation](../api-reference/store).
+
+## Ref Counting
+
+The pattern of keeping track of how many other objects can access a particular object, and cleaning it up or disposing of it when that number reaches zero. This pattern is implemented throughout the Relay codebase.
+
+## Reference Marker
+
+The Relay Reference Marker is a component within the Relay runtime responsible for traversing the data graph and marking references to data that should be retained in the Relay store. It ensures data consistency by preventing premature garbage collection of data required for operations or fragments. The marker handles various data selections, manages variables, and interacts with the operation loader to process module imports, ensuring that all necessary data dependencies are retained.
+See the [OSS code](https://github.com/facebook/relay/blob/main/packages/relay-runtime/store/RelayReferenceMarker.js) for implementation details.
+
+## @refetchable
+
+A directive that modifies a fragment, and causes Relay to generate a query for that fragment.
+
+This yields efficiency gains. The fragment can be loaded as part of a single, larger query initially (thus requiring only a single request to fetch all of the data), and yet refetched independently.
+
+## @relay
+
+A directive that allows you to turn off data masking and is used on plural types.
+
+See [the documentation](../api-reference/graphql-and-directives/#relaymask-boolean).
+
+## Relay Classic
+
+An even older version of Relay.
+
+## Relay Hooks
+
+The easiest-to-use, safest Relay API. It relies on suspense, and is safe to use in React concurrent mode.
+
+You should not write new code using Relay Classic or Relay Modern.
+
+## Relay Modern
+
+An older version of Relay. This version of Relay had an API that was heavily focused on Containers.
+
+## Relay Resolvers
+
+Relay Resolvers is an experimental Relay feature which enables modeling derived state as client-only fields in Relay’s GraphQL graph.
+
+See also [the Relay Resolvers Introduction](../guides/relay-resolvers/introduction.mdx).
+
+## Release Buffer
+
+As queries are released (no longer [retained](#retain)), their root nodes are stored in a release buffer of fixed size, and only evicted by newly released queries when there isn't enough space in the release buffer. When Relay runs garbage collection, queries that are present in the release buffer and not disposed.
+
+The size of the release buffer is configured with the `gcReleaseBufferSize` parameter.
+
+## `@required`
+
+A Relay directive that makes handling potentially `null` values more ergonomic.
+
+See also [the `@required` guide](../guides/required-directive/).
+
+## Request
+
+A request refers to an API call made over the network to access or mutate some data, or both.
+
+A query, when initiated, may or may not involve making a request, depending on whether the query can be fulfilled from the store or not.
+
+## Request Descriptor
+
+An object associating a [concrete request](#concrete-request) and [variables](#variables), as well as a pre-computed request ID. The variables should be filtered to exclude unneeded variables and are populated to include default values for missing variables, thus ensuring that requests that differ in irrelevant ways are cached using the same request ID.
+
+## Resolver
+
+An overloaded term, mostly referring to virtual fields, but also occasionally referring to other things.
+
+### When describing a field
+
+A resolver field is a "virtual" field that is backed by a function from a fragment reference on the same type to some arbitrary value.
+
+A live resolver is a "virtual" field that is backed by an external data source. e.g. one might use an external resolver to expose some state that is stored in local storage, or in an external Flux store.
+
+### Other meanings
+
+It can also be a [fragment spec resolver](#fragment-spec-resolver) or a [operation mock resolver](#operation-mock-resolver).
+
+## Response
+
+The data returned by a GraphQL server in response to a query, mutation, or subscription. A GraphQL response typically contains a `data` field with the requested information, and may also include an `errors` field if any errors occurred during execution.
+
+In Relay, responses are processed by the [Response Normalizer](#response-normalizer), which transforms the nested response data into a flat, normalized format suitable for storage in the Relay store. This normalization process enables efficient data deduplication, caching, and updates.
+
+Responses can also include extensions and other metadata depending on the GraphQL server implementation. Relay handles both successful responses and error responses, providing appropriate error handling and data consistency guarantees.
+
+## Response Normalizer
+
+A class, exposing a single method `normalize`. This will traverse the denormalized response from the API request, normalize it and write the normalized results into a given `MutableRecordSource`. It is called from the query executor.
+
+## Restore
+
+TODO
+
+## Retain
+
+TODO
+
+## Render Policy
+
+The "Render Policy" in Relay determines how data is rendered in components, specifically whether to use "full" or "partial" rendering. This policy integrates with React's Suspense to manage when components should suspend based on data availability.
+* Full Rendering: This approach waits until all required data is available before rendering a component. It ensures that components do not render with incomplete data, which can prevent flickering or unexpected UI changes.
+* Partial Rendering: This approach allows components to render with the data that is currently available, even if some data is missing. It can improve perceived performance by displaying parts of the UI sooner, but may lead to components rendering with null or incomplete data.
+
+The choice between full and partial rendering can be configured per environment or query, allowing developers to optimize for specific use cases.
+<FbInternalOnly>
+For example, Comet defaults to partial rendering to accommodate certain product behaviors, while other environments may use full rendering to ensure data consistency.
+</FbInternalOnly>
+
+## Revert
+
+TODO
+
+## Root Field
+
+A root field is a top-level field on a GraphQL root type — Query, Mutation, or Subscription. These fields serve as entry points for GraphQL operations, allowing clients to fetch, modify, or subscribe to data.
+
+
+## Root Type
+
+The [GraphQL spec](https://spec.graphql.org/June2018/#sec-Root-Operation-Types) defines three special root types: Query, Mutation and Subscription. Queries must select fields off of the Query root type, etc.
+
+## Root
+
+Outermost React Component for a given page or screen. Can be associated with an entrypoint.
+
+Roots for entrypoints are referred to by the [`JSResource`](#JSResource) to the root React component module.
+
+## Scalar
+
+A scalar in GraphQL is a primitive, indivisible leaf value that cannot have subfields. Scalars represent basic data types, such as numbers, strings, booleans, and identifiers, which are returned directly to the client without further selection or nesting.
+
+GraphQL defines several built-in scalar types:
+* Int: A signed 32‐bit integer
+* Float: A signed double-precision floating-point value
+* String: A UTF‐8 character sequence
+* Boolean: true or false
+* ID: A unique identifier, often serialized as a string
+
+In addition to these built-in types, GraphQL servers may define custom scalars for values like dates, times, or other domain-specific primitive types.
+
+Relay represents GraphQL scalars as corresponding primitive JavaScript values (such as numbers, booleans, and strings). For custom scalars, Relay treats them as opaque values, providing support for their representation and use, but does not interpret their content.
+
+For more details, see:
+* [The GraphQL Specification on Scalars](https://spec.graphql.org/October2021/#sec-Scalars)
+* [Relay Return Types Guide](../guides/relay-resolvers/return-types/#scalar-types)
+
+
+## Scheduler
+
+TODO
+
+## Schema
+
+A collection of all of the GraphQL types that are known to Relay, for a given [project](#project).
+
+<FbInternalOnly>
+
+## Schema Sync
+
+The GraphQL [schema](#schema) is derived from annotations on Hack classes in the www repository.
+
+Periodically, those changes are synced to fbsource in a schema sync diff. If the updated schema would break Relay on fbsource, these schema sync diffs will not land.
+
+If a field is removed from www, but is only used in fbsource, the application developer may not notice that the field cannot be removed. This is a common source of schema breakages.
+
+For more info, look [here](https://www.internalfb.com/intern/wiki/GraphQL/Build_Infra/Schema_Sync/) and [here](https://www.internalfb.com/intern/wiki/Relay-team/GraphQL_Schema_Sync/).
+</FbInternalOnly>
+
+## Selection
+
+A "selection of fields" refers to the fields you are requesting on an object that you are accessing, as part of a query, mutation, subscription or fragment.
+
+## Selector
+
+See [normalization selector](#normalization-selector).
+
+## @skip
+
+A directive that is added to fields, inline fragments and fragment spreads, and allows for conditional inclusion. It is the opposite of the [`@include`](#include) directive.
+
+## Snapshot
+
+The results of running a reader selector against the data currently in the store. See [lookup](#lookup).
+
+## Stale
+
+In Relay, "stale" describes cached data in the client store that is no longer considered fresh or up-to-date. By default, Relay treats cached data as valid indefinitely unless it is explicitly marked as stale through invalidation APIs (`invalidateRecord`, `invalidateStore`) or if it exceeds the configured query cache expiration time. When data is stale, Relay triggers a network refetch on the next query evaluation to ensure the UI reflects the most current information. Components can also subscribe to invalidation events to respond immediately when data becomes stale (`useSubscribeToInvalidationState` hook). This mechanism helps maintain data consistency and timely updates after changes such as mutations.
+
+For more details, see the [Relay Staleness of Data documentation](../guided-tour/reusing-cached-data/staleness-of-data.mdx).
+
+## Store
+
+The Relay Store is a local cache in the Relay runtime that manages the lifecycle of records fetched from a GraphQL server, as well as client-side data. It normalizes and de-dupes data, supports subscriptions and [optimistic updates](#optimistic-update), and handles garbage collection and data retention to ensure efficient data access and consistency.
+
+In addition to server-fetched data, the Relay Store can manage client-side data, including data from resolvers and local state. Client-side resolvers compute derived data based on existing records, allowing components to access both server and client data seamlessly. The store also supports the integration of local state by adding client-specific fields to the GraphQL schema, enabling developers to query and manage local state using Relay.
+
+## @stream
+
+A directive which can be added to a field of `List` type that enables the individual items in the list to be delivered incrementally. The client can render the initial
+set of items while waiting for the server to deliver the rest of the items. For more detail refer to GraphQL's [documentation on the @stream directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.mdx#stream).
+
+## @stream_connection
+
+A directive that is like the @connection directive for pagination, except modified to enable items in the pagination queue to be delivered incrementally. It has the additional parameter `initial_count` to specify how many items to deliver in the initial payload. To learn more about how to use this directive refer to the [Streaming Pagination page](https://relay.dev/docs/guided-tour/list-data/streaming-pagination/).
+
+## Subscribe
+
+A method exposed by the Relay store. Accepts a callback and a snapshot (see [lookup](#lookup)). The Relay store will call this callback when [`notify`](#notify) is called, if the data referenced by that snapshot has been updated or invalidated.
+
+## Subscription
+
+[GraphQL Subscriptions](../guided-tour/updating-data/graphql-subscriptions) are a mechanism which allow clients to subscribe to changes in a piece of data from the server, and get notified whenever that data changes.
+
+A GraphQL Subscription looks very similar to a query, with the exception that it uses the subscription keyword:
+
+```graphql
+subscription FeedbackLikeSubscription($input: FeedbackLikeSubscribeData!) {
+  feedback_like_subscribe(data: $input) {
+    feedback {
+      id
+      like_count
+    }
+  }
+}
+```
+
+<FbInternalOnly>
+
+See also [the guide](../guides/writing-subscriptions).
+
+</FbInternalOnly>
+
+## Transaction ID
+
+A unique id for a given instance of a call to `network.execute`. This ID will be consistent for the entire duration of a network request. It can be consumed by custom log functions passed to `RelayModernEnvironment`.
+
+## Traversal
+
+There are four tree traversals that are core to understanding the internal behavior of Relay.
+
+* Using the normalization AST:
+  * When Relay normalizes the payload it receives from the GraphQL server in the Response Normalizer;
+  * When Relay determines whether there is enough data for to fulfill an operation, in the Data Checker; and
+  * When Relay determines what data is no longer accessible during garbage collection, in the [Reference Marker](#reference-marker).
+* Using the reader AST:
+  * When Relay reads data for rendering, in the Reader.
+
+## Type
+
+The GraphQL type of a field is a description of a field on a schema, in terms of what subfields it has, or what its representation is (String, number, etc.).
+
+See also [interface](#interface-graphql), [abstract type](#abstract-type) and [the GraphQL docs](https://graphql.org/learn/schema/#type-language) for more info.
+
+## Type Refinement
+
+The inclusion of a fragment of particular type in a location only known to potentially implement that type. This allows us to select fields if and only if they are defined on that particular object, and return null otherwise.
+
+For example, `node(id: 4) { ... on User { name } }`. In this case, we do not know ahead of time whether `node(id: 4)` is a User. If it is, this fragment will include the user name.
+
+See also [abstract type refinement](#abstract-type-refinement).
+
+## Updater
+
+A callback passed to `commitMutation`, which provides the application developer with imperative control over the data in the store.
+
+See [the documentation](../guided-tour/updating-data/introduction.mdx) and also [optimistic updater](#optimistic-updater).
+
+## Value
+
+A single value on a record, such as `has_viewer_liked`, or `name`.
+
+Compare with [linked record](#linked-record).
+
+## Variables
+
+GraphQL variables are a construct that allows referencing dynamic values inside a GraphQL query. They must be provided when the query is initiated, and can be used throughout nested fragments.
+
+See the [variables section of the guided tour](../guided-tour/rendering/variables) and compare with [@argumentDefinitions](#argumentdefinitions).
+
+<DocsRating />