relay-runtime 20.1.1 → 21.0.1

package/llm-docs/guides/relay-resolvers/defining-types.mdx

@@ -0,0 +1,164 @@
+---
+id: defining-types
+title: "Defining Types"
+slug: /guides/relay-resolvers/defining-types/
+description: How to define types for your client state schema
+---
+
+import {FbInternalOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+You can think of client state resolvers as defining a GraphQL server that runs in the client. Just like with a server-defined GraphQL server you will need to define the _types_ that exist in your schema as well as the _fields_ on those types. Just like a GraphQL server, fields are defined as functions that compute the GraphQL value from the parent object. In Relay Resolvers we call this parent JavaScript object the "model" of the type.
+
+:::info
+Each client state GraphQL type is backed by a JavaScript object type which these docs will refer to as its "model type". Resolvers "on" this type will be passed an instance of this type as their first argument.
+:::
+
+Resolver types are defined using the `@relayType` tag followed by the name of the type you are defining. By default Relay assumes your client types are “strong”, meaning each instance has an ID which is unique within the type. This property allows Relay to apply a number of optimizations, such as memoizing resolver computation.
+
+### Defining a “strong” type
+Strong types are defined by a docblock followed by an exported function whose name matches the type's name, and which accepts an ID as its only argument and returns an instance of the type’s model. Resolvers that define edges to this type will simply need to return the ID of the object, rather than deriving the model themselves.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+
+```tsx
+/**
+ * @relayType User
+ */
+export function User(id: DataID): UserModel {
+  return UserService.getById(id);
+}
+```
+
+  </TabItem>
+
+  <TabItem value="Flow">
+
+  ```tsx
+  /**
+   * @relayType
+   */
+  export function User(id: DataID): UserModel {
+    return UserService.getById(id);
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+:::tip
+Elsewhere in the docs this function is referred to as the “model resolver” for the type.
+:::
+
+Generally objects in your client data store will be able to change over time. To support this Relay Resolvers support resolvers that subscribe to the underlying data source. To learn about this, see the page on [Live Fields](./live-fields.mdx).
+
+### Defining a “weak” type
+
+If your type does not have a unique identifier, you can define it as “weak” by adding the `@weak` docblock tag. Weak types are defined by a docblock followed by an exported type definition matching the types name. Resolvers that define edges to weak types will need to return a fully populated model object matching this type.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+```tsx
+/**
+ * @relayType ProfilePicture
+ * @weak
+ */
+export type ProfilePicture = { url: string, height: number, width: number };
+```
+  </TabItem>
+
+  <TabItem value="Flow">
+
+  ```tsx
+  /**
+   * @relayType
+   */
+  export type ProfilePicture = { url: string, height: number, width: number };
+  ```
+  </TabItem>
+
+</Tabs>
+
+:::tip
+Generally weak types are used for creating a namespace for a set of fields that ultimately "belong" to a parent object.
+:::
+
+### Implementing Abstract Types
+
+Relay Resolver types can implement [abstract types](https://relay.dev/docs/glossary/#abstract-type) defined in the graphql schema. Note, these abstract types can
+be defined on your GraphQL server schema OR a [client side schema extension](https://relay.dev/docs/next/guides/client-schema-extensions/).
+
+For example, given the following interface:
+
+```graphql
+# IUser.graphql
+interface IUser {
+  name: String
+}
+```
+
+You could define two (or more) concrete resolver types that implement the IUser interface by adding annotations in the docblock (the same applies for unions).
+<FbInternalOnly>
+
+Note, support for abstract types is not available for relay resolvers in Flow syntax (yet).
+
+</FbInternalOnly>
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+
+```tsx
+/**
+ * @relayType BasicUser implements IUser
+ */
+export function BasicUser(id: DataID): BasicUserModel {
+  return { ...BasicUserService.getById(id), name: 'BasicUser1'};
+}
+
+/**
+ * @relayType SpecialUser implements IUser
+ */
+export function SpecialUser(id: DataID): SpecialUserModel {
+  return { ...SpecialUserService.getById(id), name: 'SpecialUser1'};
+}
+```
+
+  </TabItem>
+</Tabs>

package/llm-docs/guides/relay-resolvers/deprecated.mdx

@@ -0,0 +1,27 @@
+---
+id: deprecated
+title: "Deprecated"
+slug: /guides/relay-resolvers/deprecated/
+description: Marking fields in your client state schema as @deprecated
+---
+
+GraphQL allows you to mark fields as `@deprecated` and provide an optional human-readable reason. Relay Resolvers bring this same convention to your client data. By marking fields in your client state schema as deprecated they will receive the same treatment as deprecated fields in your server GraphQL schema.
+
+Deprecated fields are surfaced as such in Relay's [VSCode extension](https://relay.dev/docs/editor-support/) in autocomplete and on hover. Additionally, they will be rendered as greyed out and ~~struck through~~ in the editor.
+
+:::info
+GraphQL deprecation reasons are expected to be written in markdown. Relay Resolvers will render these descriptions as markdown in the VSCode extension.
+:::
+
+You can mark a field as deprecated by adding the `@deprecated` docblock tag followed by optional text to specify the reason.
+
+```tsx
+/**
+ * @relayField Author.fullName: String
+ *
+ * @deprecated Google "Falsehoods Programmers Believe About Names"
+ */
+export function fullName(author: AuthorModel): string {
+  return `${author.firstName} ${author.lastName}`;
+}
+```

package/llm-docs/guides/relay-resolvers/derived-fields.mdx

@@ -0,0 +1,127 @@
+---
+id: derived-fields
+title: "Derived Fields"
+slug: /guides/relay-resolvers/derived-fields/
+description: Defining field which are a pure function of other fields
+---
+import {FbInternalOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+In addition to modeling client state, Relay Resolvers also allow you to define fields which are a pure function of other fields. These fields are called derived fields and can be defined on any type no matter if it's defined on the server or client.
+
+For globally relevant data, resolvers have a few advantages of alternative solutions like [React Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks):
+
+* **Global memoization** - Relay Resolvers automatically memoize derived fields. Unlike hooks, this cache is shared by all components in your application, so if two sibling components both read the same field, the computation will only be performed once.
+* **Efficient updates** - If your derived resolver recomputes but derives the same value, Relay can avoid rerendering components that read the field.
+* **Composable** - Derived fields can be composed with other derived fields, allowing you to build up complex, but explicit computation graphs.
+* **Discoverable** - Values in the graph are discoverable via the GraphQL schema and thus are more likely to be discovered and reused instead of reinvented.
+* **Documented** - GraphQL's field documentation and structured deprecation model make it easy to understand the purpose of a field and its intended use.
+
+## Defining a Derived Resolver
+
+Derived resolvers look like any other resolver except that they read GraphQL data instead of being computed from a parent model type. Derived resolvers read GraphQL data by defining a "root fragment" which is a GraphQL fragment defined on the parent type of the field.
+
+The root fragment is defined using the `@rootFragment` docblock tag followed by the name of the fragment. This tells Relay to pass the resolver function a fragment key for that fragment. The fragment data may then be read using `readFragment` imported from `relay-runtime`.
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+```tsx
+import {readFragment} from 'relay-runtime';
+
+/**
+ * @relayField User.fullName: String
+ * @rootFragment UserFullNameFragment
+ */
+export function fullName(key: UserFullNameFragment$key): string {
+  const user = readFragment(graphql`
+    fragment UserFullNameFragment on User {
+        firstName
+        lastName
+    }
+  `, key);
+  return `${user.firstName} ${user.lastName}`;
+}
+```
+  </TabItem>
+
+  <TabItem value="Flow">
+  <FbInternalOnly>
+
+```tsx
+import {readFragment} from 'relay-runtime';
+
+/**
+ * @relayField
+ */
+export function fullName(key: UserFullNameFragment$key): string {
+  const user = readFragment(graphql`
+    fragment UserFullNameFragment on User {
+        firstName
+        lastName
+    }
+  `, key);
+  return `${user.firstName} ${user.lastName}`;
+}
+```
+
+  </FbInternalOnly>
+  </TabItem>
+</Tabs>
+
+:::info
+Relay will track all the values read from the fragment and automatically recompute the resolver when any of those values change.
+:::
+
+## Composition
+
+One powerful feature of derived resolvers is that they can read other Relay Resolver fields. This means you can define a derived resolver that combines server data, client data and even other derived resolvers. This allows you to build up complex, but explicit, computation graphs.
+
+```tsx
+/**
+ * @relayField CheckoutItem.isValid: Boolean
+ * @rootFragment CheckoutItemFragment
+ */
+export function isValid(key): boolean {
+  const item = readFragment(graphql`
+    fragment CheckoutItemFragment on CheckoutItem {
+      product {
+        price
+      }
+      quantity
+    }
+  `, key);
+  return item.product.price * item.quantity > 0;
+}
+
+/**
+ * @relayField ShoppingCart.canCheckout: Boolean
+ * @rootFragment ShoppingCartFragment
+ */
+export function canCheckout(key): boolean {
+  const cart = readFragment(graphql`
+    fragment ShoppingCartFragment on ShoppingCart {
+      items {
+        isValid
+      }
+    }
+  `, key);
+  return cart.items.every(item => item.isValid);
+}
+```
+
+## Passing Arguments to your @rootFragment
+
+If a field in a derived resolver's root fragment requires arguments, you can pass them by adding an `@arguments` tag to the docblock tag. The `@argument` tag takes the name of the argument and the type of the argument. The argument type must be a valid GraphQL input type. For more information about arguments and Resolvers see [Field Arguments](./field-arguments.mdx).

package/llm-docs/guides/relay-resolvers/descriptions.mdx

@@ -0,0 +1,44 @@
+---
+id: descriptions
+title: "Descriptions"
+slug: /guides/relay-resolvers/descriptions/
+description: Adding human readable descriptions to your resolver schema
+---
+
+One killer feature of GraphQL is that makes the data in your schema discoverable. Relay Resolvers bring this structure to your client data. By adding descriptions to your resolvers you can make your client state schema self-documenting as well.
+
+Descriptions are surfaced by Relay's [VSCode extension](https://relay.dev/docs/editor-support/) in autocomplete and on hover.
+
+You can add a description to a type by adding free text to the docblock tag:
+
+:::info
+GraphQL descriptions are expected to be written in markdown. Relay Resolvers will render these descriptions as markdown in the VSCode extension.
+:::
+
+## Types
+
+```tsx
+/**
+ * @relayType Author
+ *
+ * An author in our **amazing** CMS. Authors can
+ * write posts but not necessarily change their permissions.
+ */
+export function Author(id: DataID): AuthorModel {
+  return AuthorService.getById(id);
+}
+```
+
+## Fields
+
+```tsx
+/**
+ * @relayField Author.fullName: String
+ *
+ * The author's first and last name. Does not include
+ * any [honorifics](https://en.wikipedia.org/wiki/Honorific).
+ */
+export function fullName(author: AuthorModel): string {
+  return `${author.firstName} ${author.lastName}`;
+}
+```

package/llm-docs/guides/relay-resolvers/enabling.mdx

@@ -0,0 +1,41 @@
+---
+id: enabling
+title: "Enabling Relay Resolvers"
+slug: /guides/relay-resolvers/enabling-resolvers
+description: Enabling experimental Relay Resolvers
+---
+
+## Runtime
+
+When using Relay Resolvers, we recommend configuring a `fieldLogger` in your Relay Environment in order to track errors which have been thrown within Relay resolver functions.
+
+```ts
+import { Environment, RecordSource, RelayFeatureFlags } from "relay-runtime";
+import RelayModernStore from "relay-runtime/lib/store/RelayModernStore";
+
+// It is recommended to log errors thrown by Resolvers
+function fieldLogger(event) {
+  if(event.kind === "relay_resolver.error") {
+    // Log this somewhere!
+    console.warn(`Resolver error encountered in ${event.owner}.${event.fieldPath}`)
+    console.warn(event.error)
+  }
+}
+
+const environment = new Environment({
+  network: Network.create(/* your fetch function here */),
+  store: new RelayModernStore(new RecordSource()),
+  relayFieldLogger: fieldLogger
+});
+
+// ... create your Relay context with your environment
+```
+
+<FbInternalOnly>
+
+## Enable new Flow based RelayResolver syntax
+To opt-in the new syntax in a file, add `//relay:enable-new-relay-resolver` to the file
+
+To convert files to the new syntax, run codemode: `flow-runner codemod relay/migrateResolver <path>`. The codemod doesn't support all cases, so you might need to modify some files manually after it runs.
+
+</FbInternalOnly>

package/llm-docs/guides/relay-resolvers/errors.mdx

@@ -0,0 +1,64 @@
+---
+id: errors
+title: "Error Handling"
+slug: /guides/relay-resolvers/errors/
+description: How Relay handles errors thrown by resolvers
+---
+
+Just like GraphQL servers, Relay Resolvers support field-level error handling. If an individual resolver throws an error, when that field is read, Relay will log that error to the environment's user-provided `relayFieldLogger` logger, and the field will become null.
+
+This provides important symmetry with GraphQL servers. Resolvers are designed to enable a smooth migration path to allow teams to start with fields defined client-side using Resolvers and then eventually migrate them to a server.
+
+If a resolver throws an error, Relay will log the error to the user-provided error logger, and will return null for the field which the resolver defines. To enable this behavior at runtime, the Relay compiler will not allow resolver fields to be typed as non-nullable.
+
+The object passed to the `relayFieldLogger` will have the following shape:
+
+```ts
+type ResolverErrorEvent = {
+  kind: 'relay_resolver.error',
+  // The name of the fragment/query in which the field was read
+  owner: string,
+  // The path from the owner root to the field which threw the error
+  fieldPath: string,
+  // The error thrown by the resolver
+  error: Error,
+}
+```
+
+An example logger might look like:
+
+```ts
+function fieldLogger(event) {
+  if(event.kind === "relay_resolver.error") {
+    // Log this somewhere!
+    console.warn(`Resolver error encountered in ${event.owner}.${event.fieldPath}`)
+    console.warn(event.error)
+  }
+}
+
+const environment = new Environment({
+  network: Network.create(/* your fetch function here */),
+  store: new RelayModernStore(new RecordSource()),
+  relayFieldLogger: fieldLogger
+});
+```
+
+:::note
+[Live Resolvers](./live-fields.mdx) can potentially throw errors when they are first evaluated or when their `.read()` method is called. Both types of errors will be handled identically by Relay.
+:::
+
+## Support for Semantic Nullability
+
+Relay resolver fields can be specified as [semantically non-null](../../semantic-nullability/) just like server schema fields. Developers can add the directive `@semanticNonNull` in the docblock of a relay resolver in order to indicate that the field is non-nullable in the semantic sense, but that the client should still be prepared to handle errors.
+
+For example:
+```ts
+/**
+ * @relayField RelayExample.semantic_non_null_field: String @semanticNonNull
+ */
+export function semantic_non_null_field(
+  model: RelayExampleModel,
+): string {
+  return model.someField ?? 'field was null, this is the default';
+}
+```

package/llm-docs/guides/relay-resolvers/field-arguments.mdx

@@ -0,0 +1,63 @@
+---
+id: field-arguments
+title: "Field Arguments"
+slug: /guides/relay-resolvers/field-arguments/
+description: Defining field arguments for resolver fields
+---
+
+## Runtime Arguments
+
+If your resolver needs access to argument data at runtime, you can simply define arguments in the field definition of your resolver's docblock, and then read the argument as a property on the second argument to your resolver function.
+
+```tsx
+/**
+ * @relayField User.greet(salutation: String!): String
+ */
+export function greet(user: UserModel, args: { salutation: string }): string {
+  return `${args.salutation}, ${user.name}!`;
+}
+```
+
+Consuming this field will require passing the argument to the field in your GraphQL query:
+
+```graphql
+query MyQuery($salutation: String!) {
+  me {
+    greet(salutation: $salutation)
+  }
+}
+```
+
+This, in turn will require passing the argument when you fetch the query.
+
+## Passing Arguments to your @rootFragment
+
+If you are defining a [derived resolver](./derived-fields.mdx) and one of the fields in its root fragment requires arguments, you must define an explicit fragment argument using [@argumentDefinitions](../../api-reference/graphql/graphql-directives.mdx#argumentdefinitions) in your fragment definition. Your resolver field will then expect this argument to be passed as a field argument.
+
+```tsx
+/**
+ * @relayField User.fancyGreeting: String
+ * @rootFragment UserFancyGreetingFragment
+ */
+export function fancyGreeting(key: UserFancyGreetingFragment$key): string {
+  const user = readFragment(graphql`
+    fragment UserFancyGreetingFragment on User @argumentDefinitions(
+      salutation: {type: "String"},
+    ) {
+      name
+      greet(salutation: $salutation)
+    }
+  `, key);
+  return `${user.name} says ${user.greet}`;
+}
+```
+
+Consuming this field will require passing the argument to the field in your GraphQL query:
+
+```graphql
+query MyQuery($salutation: String!) {
+  me {
+    fancyGreeting(salutation: $salutation)
+  }
+}
+```

package/llm-docs/guides/relay-resolvers/introduction.mdx

@@ -0,0 +1,62 @@
+---
+id: introduction
+title: "Introduction to Relay Resolvers"
+slug: /guides/relay-resolvers/introduction
+description: An introduction to Relay Resolvers
+---
+
+Relay Resolvers are a Relay feature which allow you to augment Relay’s GraphQL graph with values that are known only on the client. This allows you to schematize client state in the same way that you model server state, and to use Relay’s familiar data-fetching APIs to access that state. Client state can include both data from client-side data stores as well as derived data that is computed from other values in the graph.
+
+By modeling derived and client state in the graph, Relay can present a unified data access API for product developers. All globally relevant data that a product engineer wants to access can be discovered and efficiently obtained from the same structured GraphQL schema. Additionally resolvers provide a number of runtime benefits:
+
+- Global memoization with garbage collection
+- Efficient reactive recomputation of resolvers
+- Efficient UI updates when data changes
+
+You can think of resolvers as additional schema types and fields which are defined in your client code and are stitched into your server's schema. Just like you define resolver methods/functions which model your fields on the server, Relay Resolvers are defined using resolver functions.
+
+## Use Cases for Relay Resolvers
+
+Relay Resolvers are useful for modeling a number of different kinds of data. Here are some examples of types of data that can be schematized using Relay Resolvers and made available to product code:
+
+* **User-Created Data** - You can model complex form state, or other data that should outlive a specific component tree
+* **Client-Side Database** - Persistent data stores like IndexDB, localStorage, or SQLite
+* **Third-Party APIs** - Data that is fetched from a third-party API directly by the client, for example search results from a third-party search provider
+* **Encrypted Data** - End-to-end encrypted data that is opaque on the server and thus cannot be modeled in the server schema
+* **Legacy Data Stores** - During the adoption of Relay and GraphQL, data from pre-existing data layers, like Redux, can be exposed in the graph to ensure migrated and un-migrated portions of your app always remain in sync
+
+## Defining a Resolver
+
+Resolvers are defined using exported functions that are annotated with a special [`@relayType` or `@relayField` docblock](../../api-reference/relay-resolvers/docblock-format.mdx). These docblocks are visible to the Relay compiler, and allow the compiler to build up your client schema and automatically import your function in Relay's generated artifacts. Resolver functions may be defined in any file in your Relay project, though you may wish to define some convention for where they live within your codebase.
+
+The simplest resolver augments an existing type and does not have any inputs:
+
+```tsx
+/**
+ * @relayField Query.greeting: String
+ */
+export function greeting(): string {
+  return "Hello World";
+}
+```
+
+Consuming resolvers is identical to consuming a server field. Product code doesn't need to know which kind of field it is reading.
+
+```tsx
+import {useLazyLoadQuery, graphql} from 'react-relay';
+import {useClientQuery, graphql} from 'react-relay';
+
+function Greeting() {
+  const data = useClientQuery(graphql`
+    query GreetingQuery {
+      greeting
+    }`, {});
+  return <p>{data.greeting}</p>;
+}
+```
+
+:::note
+If your query contains only client-defined fields, you will need to use a a different query API to fetch data. Note how this example uses `useClientQuery` instead of `useLazyLoadQuery` or `usePreloadedQuery`. If your query also contains server data, you can use the standard `useLazyLoadQuery` or `usePreloadedQuery` APIs.
+
+We intend to remove this requirement in future versions of Relay.
+:::

package/llm-docs/guides/relay-resolvers/limitations.mdx

@@ -0,0 +1,30 @@
+---
+id: limitations
+title: "Limitations"
+slug: /guides/relay-resolvers/limitations/
+description: Limitations of Relay Resolvers
+---
+
+Relay Resolvers do have some limitations. Here we will collect a list of known limitations and provide alternatives where possible.
+
+## No info argument
+
+In a full GraphQL implementation, resolvers would have access to an `info` argument. This argument is not available in Relay Resolvers today.
+
+## Not all GraphQL constructs are supported
+
+Today Relay Resolvers only support a subset of GraphQL constructs. For example, it's not currently possible to define input types, enums or interfaces using Relay Resolvers.
+
+## No support for mutations
+
+Today Relay Resolvers only support the read path. Defining mutation fields is not yet supported. We are working to understand what it means to perform a mutation against a reactive schema, and hope to support them in the future.
+
+## Resolvers are always evaluated lazily
+
+Today Relay Resolvers are always evaluated lazily on a per-fragment basis. This has the advantage that if a resolver is not read, it will never be evaluated. However, it can lead to issues with waterfalls if your client schema ends up making async requests to fetch data as its read. We are actively exploring other execution strategies for Relay Resolvers, such as evaluating all fields in a query at request time, but expect the way resolvers are defined to remain stable.
+
+## Verbose/awkward docblock syntax
+
+Today defining a resolver requires defining a function with a docblock which uses special syntax and duplicates information already specified in the function's name and types. Further, in order to enforce that these values match up, Relay emits type assertions in its generated types. While these assertions do ensure safety, they are an awkward developer experience.
+
+To address these issues we are exploring a more streamlined approach where names and types can be inferred from your Flow or TypeScript code similar to the approach taken by [Grats](https://grats.capt.dev/). This syntax may become available in future versions of Relay.