relay-runtime 20.1.1 → 21.0.0

package/llm-docs/guides/document-comparison.mdx

@@ -0,0 +1,106 @@
+---
+id: document-comparison
+title: Document Comparison
+slug: /guides/document-comparison/
+description: Relay guide to document comparison
+keywords:
+  - compare
+  - diff
+  - ir
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+:::note
+This feature is **experimental** and the API may change in future versions.
+:::
+
+The Relay compiler includes an experimental feature for comparing the intermediate representations (IR) of two GraphQL documents. This feature determines whether one document is a subset of another and reports any missing selections.
+
+This feature is particularly useful for comparing documents generated by LLMs where exact match of LLM generated documents and static expected documents is neither attainable or desirable, due to the nature of LLMs. In those cases, you could:
+* Specify (via `--left`) an expected document with minimally required selections, and determine if the LLM generated document (via `--right`) contains all required selections, via the subset test that the command performs.
+* Optionally, pass exepected document via `--right` and LLM generated document via `--left` to determine whether LLM generated documents contains extra selections than expected, aka. overfetching.
+
+## Usage
+
+```
+> relay experimental-compare-document-ir --help
+EXPERIMENTAL! Compare intermediate representations (IR) of documents passed via left and right, outputs selections that exists in left but not in right.
+
+Usage: relay experimental-compare-document-ir [OPTIONS] --left <LEFT> --right <RIGHT>
+
+Options:
+      --left <LEFT>                    Document in string, must contain exactly 1 operation
+      --right <RIGHT>                  Document in string, must contain exactly 1 operation
+      --schemaPaths <SCHEMA_PATHS>...  Path(s) to the full schema file(s) to convert documents to intermediate representation (IR) for comparison
+  -h, --help                           Print help
+```
+
+## Output
+
+Detailed information about missing selection(s) from the right document, including line number and path.
+
+## How It Works
+
+The 2 documents (left and right) are first transformed to their Intermediate Representation (IR), then to **Normalized Tree** form, for comparison. Each node of the tree corresponds to a selection in the original document, and is checked for its existence in the other tree.
+
+### Normalized Trees
+
+Each IR is transformed into a normalized tree structure that:
+- **Inlines fragments**: Fragment spreads and inline fragments are inlined, while type conditions specified by the fragment are encoded in the node.
+- **De-aliases fields**: Converts aliased fields to their original names (e.g., `my_id: id` → `id`)
+- **Deduplicates fields**: Removes duplicate identical fields
+- **Tracks type conditions**: Records which concrete object types can reach each scalar field at the leaf level
+
+The normalized tree mirrors the JSON response structure of the query.
+
+#### Tree Node Identity
+Consists of
+- Path from operation root to the corresponding selection
+- Field arguments of the corresponding selection (if applicable)
+- Type condition: the type that the enclosing object must be, for the corresponding selection to be included in the response. E.g. with `... on A { id }`, the type condition of selection `id` is `A` if `A` is a concrete type, or a set of types that are `A` if `A` is an abstract type.
+
+#### Tree Node Existence
+
+A selection exists in a tree if:
+- An identical selection is found
+- A superset of the selection is found. A selection is a superset of another if:
+  - It allows the same selection and more, with query variables. E.g. `user(id: $id)` is a superset of `user(id: 100)` because variable `$id` can be set to arbitrary values, including `100`, at runtime.
+  - Its type condition is a superset of another.
+
+## Example
+
+**Left document:**
+```graphql
+query A {
+  viewer {
+    timezone_estimate {
+      display_name
+      gmt_offset
+    }
+  }
+}
+```
+
+**Right document:**
+```graphql
+query A {
+  viewer {
+    timezone_estimate {
+      display_name
+    }
+  }
+}
+```
+
+**Output**
+```text
+[INFO] Found 1 missing selection(s):
+    4 │       display_name
+    5 │       gmt_offset
+      │       ^^^^^^^^^^
+    6 │     }
+* query -> viewer -> timezone_estimate -> gmt_offset
+```
+
+Explore [tests](https://github.com/facebook/relay/blob/main/compiler/crates/graphql-ir-diff/tests/ir_diff_test.rs) for more examples.

package/llm-docs/guides/graphql-server-specification.mdx

@@ -0,0 +1,453 @@
+---
+id: graphql-server-specification
+title: GraphQL Server Specification
+slug: /guides/graphql-server-specification/
+description: Relay GraphQL server specification guide
+keywords:
+- GraphQL
+- server
+- specification
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+The goal of this document is to specify the assumptions that Relay makes about a GraphQL server and demonstrate them through an example GraphQL schema.
+
+Table of Contents:
+
+-   [Preface](#preface)
+-   [Schema](#schema)
+-   [Object Identification](#object-identification)
+-   [Connections](#connections)
+-   [Further Reading](#further-reading)
+
+## Preface
+
+The two core assumptions that Relay makes about a GraphQL server are that it provides:
+
+1.  A mechanism for refetching an object.
+2.  A description of how to page through connections.
+
+This example demonstrates all two of these assumptions. This example is not comprehensive, but it is designed to quickly introduce these core assumptions, to provide some context before diving into the more detailed specification of the library.
+
+The premise of the example is that we want to use GraphQL to query for information about ships and factions in the original Star Wars trilogy.
+
+It is assumed that the reader is already familiar with [GraphQL](http://graphql.org/); if not, the README for [GraphQL.js](https://github.com/graphql/graphql-js) is a good place to start.
+
+It is also assumed that the reader is already familiar with [Star Wars](https://en.wikipedia.org/wiki/Star_Wars); if not, the 1977 version of Star Wars is a good place to start, though the 1997 Special Edition will serve for the purposes of this document.
+
+## Schema
+
+The schema described below will be used to demonstrate the functionality that a GraphQL server used by Relay should implement. The two core types are a faction and a ship in the Star Wars universe, where a faction has many ships associated with it.
+
+```graphql
+interface Node {
+  id: ID!
+}
+
+type Faction implements Node {
+  id: ID!
+  name: String
+  ships: ShipConnection
+}
+
+type Ship implements Node {
+  id: ID!
+  name: String
+}
+
+type ShipConnection {
+  edges: [ShipEdge]
+  pageInfo: PageInfo!
+}
+
+type ShipEdge {
+  cursor: String!
+  node: Ship
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type Query {
+  rebels: Faction
+  empire: Faction
+  node(id: ID!): Node
+}
+```
+
+## Object Identification
+
+Both `Faction` and `Ship` have identifiers that we can use to refetch them. We expose this capability to Relay through the `Node` interface and the `node` field on the root query type.
+
+The `Node` interface contains a single field, `id`, which is an `ID!`. The `node` root field takes a single argument, an `ID!`, and returns a `Node`. These two work in concert to allow refetching; if we pass the `id` returned in that field to the `node` field, we get the object back.
+
+Let's see this in action, and query for the ID of the rebels:
+
+```graphql
+query RebelsQuery {
+  rebels {
+    id
+    name
+  }
+}
+```
+
+returns
+
+```json
+{
+  "rebels": {
+    "id": "RmFjdGlvbjox",
+    "name": "Alliance to Restore the Republic"
+  }
+}
+```
+
+So now we know the ID of the Rebels in our system. We can now refetch them:
+
+```graphql
+query RebelsRefetchQuery {
+  node(id: "RmFjdGlvbjox") {
+    id
+    ... on Faction {
+      name
+    }
+  }
+}
+```
+
+returns
+
+```json
+{
+  "node": {
+    "id": "RmFjdGlvbjox",
+    "name": "Alliance to Restore the Republic"
+  }
+}
+```
+
+If we do the same thing with the Empire, we'll find that it returns a different ID, and we can refetch it as well:
+
+```graphql
+query EmpireQuery {
+  empire {
+    id
+    name
+  }
+}
+```
+
+yields
+
+```json
+{
+  "empire": {
+    "id": "RmFjdGlvbjoy",
+    "name": "Galactic Empire"
+  }
+}
+```
+
+and
+
+```graphql
+query EmpireRefetchQuery {
+  node(id: "RmFjdGlvbjoy") {
+    id
+    ... on Faction {
+      name
+    }
+  }
+}
+```
+
+yields
+
+```json
+{
+  "node": {
+    "id": "RmFjdGlvbjoy",
+    "name": "Galactic Empire"
+  }
+}
+```
+
+The `Node` interface and `node` field assume globally unique IDs for this refetching. A system without globally unique IDs can usually synthesize them by combining the type with the type-specific ID, which is what was done in this example.
+
+The IDs we got back were base64 strings. IDs are designed to be opaque (the only thing that should be passed to the `id` argument on `node` is the unaltered result of querying `id` on some object in the system), and base64ing a string is a useful convention in GraphQL to remind viewers that the string is an opaque identifier.
+
+Complete details on how the server should behave are available in the [GraphQL Object Identification](https://graphql.org/learn/global-object-identification/) best practices guide in the GraphQL site.
+
+## Connections
+
+A faction has many ships in the Star Wars universe. Relay contains functionality to make manipulating one-to-many relationships easy, using a standardized way of expressing these one-to-many relationships. This standard connection model offers ways of slicing and paginating through the connection.
+
+Let's take the rebels, and ask for their first ship:
+
+```graphql
+query RebelsShipsQuery {
+  rebels {
+    name
+    ships(first: 1) {
+      edges {
+        node {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+yields
+
+```json
+{
+  "rebels": {
+    "name": "Alliance to Restore the Republic",
+    "ships": {
+      "edges": [
+        {
+          "node": {
+            "name": "X-Wing"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+That used the `first` argument to `ships` to slice the result set down to the first one. But what if we wanted to paginate through it? On each edge, a cursor will be exposed that we can use to paginate. Let's ask for the first two this time, and get the cursor as well:
+
+```
+query MoreRebelShipsQuery {
+  rebels {
+    name
+    ships(first: 2) {
+      edges {
+        cursor
+        node {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+and we get back
+
+```json
+
+{
+  "rebels": {
+    "name": "Alliance to Restore the Republic",
+    "ships": {
+      "edges": [
+        {
+          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
+          "node": {
+            "name": "X-Wing"
+          }
+        },
+        {
+          "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
+          "node": {
+            "name": "Y-Wing"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Notice that the cursor is a base64 string. That's the pattern from earlier: the server is reminding us that this is an opaque string. We can pass this string back to the server as the `after` argument to the `ships` field, which will let us ask for the next three ships after the last one in the previous result:
+
+```
+
+query EndOfRebelShipsQuery {
+  rebels {
+    name
+    ships(first: 3 after: "YXJyYXljb25uZWN0aW9uOjE=") {
+      edges {
+        cursor
+        node {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+gives us
+
+```json
+
+
+{
+  "rebels": {
+    "name": "Alliance to Restore the Republic",
+    "ships": {
+      "edges": [
+        {
+          "cursor": "YXJyYXljb25uZWN0aW9uOjI=",
+          "node": {
+            "name": "A-Wing"
+          }
+        },
+        {
+          "cursor": "YXJyYXljb25uZWN0aW9uOjM=",
+          "node": {
+            "name": "Millennium Falcon"
+          }
+        },
+        {
+          "cursor": "YXJyYXljb25uZWN0aW9uOjQ=",
+          "node": {
+            "name": "Home One"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Sweet! Let's keep going and get the next four!
+
+```graphql
+query RebelsQuery {
+  rebels {
+    name
+    ships(first: 4 after: "YXJyYXljb25uZWN0aW9uOjQ=") {
+      edges {
+        cursor
+        node {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+yields
+
+```json
+{
+  "rebels": {
+    "name": "Alliance to Restore the Republic",
+    "ships": {
+      "edges": []
+    }
+  }
+}
+```
+
+Hm. There were no more ships; guess there were only five in the system for the rebels. It would have been nice to know that we'd reached the end of the connection, without having to do another round trip in order to verify that. The connection model exposes this capability with a type called `PageInfo`. So let's issue the two queries that got us ships again, but this time ask for `hasNextPage`:
+
+```graphql
+query EndOfRebelShipsQuery {
+  rebels {
+    name
+    originalShips: ships(first: 2) {
+      edges {
+        node {
+          name
+        }
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+    moreShips: ships(first: 3 after: "YXJyYXljb25uZWN0aW9uOjE=") {
+      edges {
+        node {
+          name
+        }
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+  }
+}
+```
+
+and we get back
+
+```json
+{
+  "rebels": {
+    "name": "Alliance to Restore the Republic",
+    "originalShips": {
+      "edges": [
+        {
+          "node": {
+            "name": "X-Wing"
+          }
+        },
+        {
+          "node": {
+            "name": "Y-Wing"
+          }
+        }
+      ],
+      "pageInfo": {
+        "hasNextPage": true
+      }
+    },
+    "moreShips": {
+      "edges": [
+        {
+          "node": {
+            "name": "A-Wing"
+          }
+        },
+        {
+          "node": {
+            "name": "Millennium Falcon"
+          }
+        },
+        {
+          "node": {
+            "name": "Home One"
+          }
+        }
+      ],
+      "pageInfo": {
+        "hasNextPage": false
+      }
+    }
+  }
+}
+```
+
+So on the first query for ships, GraphQL told us there was a next page, but on the next one, it told us we'd reached the end of the connection.
+
+Relay uses all of this functionality to build out abstractions around connections, to make these easy to work with efficiently without having to manually manage cursors on the client.
+
+Complete details on how the server should behave are available in the [GraphQL Cursor Connections](https://relay.dev/graphql/connections.htm) spec.
+
+## GraphQL Conf Talk
+
+Sabrina Wasserman, an engineer at Meta, gave a talk at GraphQL Conf 2024 deriving the GraphQL connection spec, and explaining how having the behavior of list pagination specified can enable powerful tooling for clients broadly, not just Relay.
+
+<iframe src="https://www.youtube-nocookie.com/embed/PGBC-0E-kco" width={640} height={360} allowFullScreen={true} frameBorder="0" />
+
+## Further Reading
+
+This concludes the overview of the GraphQL Server Specifications. For the detailed requirements of a Relay-compliant GraphQL server, a more formal description of the [Relay cursor connection](https://relay.dev/graphql/connections.htm) model, the [GraphQL global object identification](https://graphql.org/learn/global-object-identification/) model are all available.
+
+To see code implementing the specification, the [GraphQL.js Relay library](https://github.com/graphql/graphql-relay-js) provides helper functions for creating nodes and connections; that repository's [`__tests__`](https://github.com/graphql/graphql-relay-js/tree/main/src/__tests__) folder contains an implementation of the above example as integration tests for the repository.
+
+<DocsRating />

package/llm-docs/guides/network-layer.mdx

@@ -0,0 +1,69 @@
+---
+id: network-layer
+title: Network Layer
+slug: /guides/network-layer/
+description: Relay guide to the network layer
+keywords:
+- network
+- caching
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+In order to know how to access your GraphQL server, Relay requires developers to provide an object implementing the `INetwork` interface when creating an instance of a [Relay Environment](../api-reference/relay-runtime/relay-environment.mdx). The environment uses this network layer to execute queries, mutations, and (if your server supports them) subscriptions. This allows developers to use whatever transport (HTTP, WebSockets, etc) and authentication is most appropriate for their application, decoupling the environment from the particulars of each application's network configuration.
+
+Currently the easiest way to create a network layer is via a helper from the `relay-runtime` package:
+
+```javascript
+import {
+  Environment,
+  Network,
+  RecordSource,
+  Store,
+} from 'relay-runtime';
+
+// Define a function that fetches the results of an operation (query/mutation/etc)
+// and returns its results as a Promise:
+function fetchQuery(
+  operation,
+  variables,
+  cacheConfig,
+  uploadables,
+) {
+  return fetch('/graphql', {
+    method: 'POST',
+    headers: {
+      // Add authentication and other headers here
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify({
+      query: operation.text, // GraphQL text from input
+      variables,
+    }),
+  }).then(response => {
+    return response.json();
+  });
+}
+
+// Create a network layer from the fetch function
+const network = Network.create(fetchQuery);
+const store = new Store(new RecordSource())
+
+const environment = new Environment({
+  network,
+  store
+  // ... other options
+});
+
+export default environment;
+```
+
+:::warning
+This is just a basic example to help you get started. Features like `@stream`, `@defer` or Persisted Queries will require additional logic be added to your `fetchQuery` function.
+:::
+
+## Advanced Network Layer
+
+The network layer provides a place for developers to customize the data fetching behaviors. For example, adding network level caching, telemetry or support for uploading form data for mutations.
+
+<DocsRating />