relay-runtime 20.1.1 → 21.0.1

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

@@ -0,0 +1,164 @@
+---
+id: live-fields
+title: "Live Fields"
+slug: /guides/relay-resolvers/live-fields/
+description: Modeling data that changes over time in Relay Resolvers
+---
+import {FbInternalOnly, fbContent} from 'docusaurus-plugin-internaldocs-fb/internal';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+One critical difference between client state and server state is that as client state changes over time, those changes will need to be reflected in your UI. To address this, Relay Resolvers support the ability to be marked as `@live`. Live resolvers are expected to return a `LiveState` shaped object which includes methods which allow Relay to both `read()` the current value and also to `subscribe()` to changes to the value.
+
+As this value changes over time, Relay will automatically recompute any [derived fields](./derived-fields.mdx) that depend on this field (including transitive dependencies if the changes cascade), and also efficiently trigger the update of any components/subscribers which have read fields that updated as a result of this change.
+
+## @live
+
+<Tabs
+  groupId="resolver"
+  defaultValue="Docblock"
+  values={fbContent({
+    internal: [
+      {label: 'Docblock', value: 'Docblock'},
+      {label: 'Flow', value: 'Flow'},
+    ],
+    external: [
+      {label: 'Docblock', value: 'Docblock'},
+    ]
+  })}>
+  <TabItem value="Docblock">
+
+To mark a resolver as live, add the `@live` docblock tag to the resolver definition. For example:
+
+```tsx
+import type { LiveState } from 'relay-runtime';
+
+/**
+ * @relayField Query.counter: Int
+ * @live
+ */
+export function counter(): LiveState<number> {
+  return {
+    read: () => store.getState().counter,
+    subscribe: (callback) => {
+      return store.subscribe(callback);
+    },
+  };
+}
+```
+
+  </TabItem>
+
+  <TabItem value="Flow">
+  <FbInternalOnly>
+
+live is determined by the usage of `LiveState` in the Flow return type
+
+```tsx
+import type { LiveState } from 'relay-runtime';
+
+/**
+ * @relayField
+ */
+export function counter(): LiveState<number> {
+  return {
+    read: () => store.getState().counter,
+    subscribe: (callback) => {
+      return store.subscribe(callback);
+    },
+  };
+}
+```
+
+  </FbInternalOnly>
+  </TabItem>
+</Tabs>
+
+:::note
+Both field resolvers and strong model resolvers, which map an ID to a model, may be annotated as `@live`.
+:::
+
+## The LiveState Type
+
+The return type of a Live Resolver is known as a `LiveState`. It is conceptually similar to an observable or a signal, if you are familiar with those concepts. Unlike an observable, when a `LiveState` notifies its subscriber of an update, it does not include the new value. Instead, the subscriber (Relay) is expected to call `read()` to get the new value.
+
+While over-notification (subscription notifications when the read value has not actually changed) is supported, for performance reasons, it is recommended that the provider of the LiveState value confirms that the value has indeed changed before notifying Relay of the change.
+
+The type of a LiveState is defined as follows:
+
+```ts
+export type LiveState<T> = {
+  /**
+   * Returns the current value of the live state.
+   */
+  read(): T,
+  /**
+   * Subscribes to changes in the live state. The state provider should
+   * call the callback when the value of the live state changes.
+   */
+  subscribe(cb: () => void): () => void,
+};
+```
+
+## Creating a LiveState Object
+
+In most cases, you will want to define a helper function that reads your reactive data store and returns a `LiveState` object. For example, you for a Redux store you might write a wrapper that exposes a `LiveState` for a given selector:
+
+```ts
+type Selector<T> = (state: State) => T;
+
+function selectorAsLiveState<T>(selector: Selector<T>): LiveState<T> {
+  let currentValue = selector(store.getState());
+  return {
+    read: () => currentValue,
+    subscribe: (cb) => {
+      return store.subscribe(() => {
+        const newValue = selector(store.getState());
+        if (newValue === currentValue) {
+          return;
+        }
+        currentValue = newValue;
+        cb();
+      });
+      return unsubscribe;
+    },
+  };
+}
+```
+
+A Live Resolver that uses this helper might look like this:
+
+```tsx
+/**
+ * @relayField Query.counter: Int
+ * @live
+ */
+export function counter(): LiveState<number> {
+  return selectorAsLiveState(getCounter);
+}
+
+function getCounter(state) {
+  return state.counter;
+}
+```
+
+## Batching
+
+When state changes in your data layer, it's possible that one change could result in notifying many `@live` resolver subscriptions about updates. By default each of these updates will require Relay to do work to determine which components need to be updated. This can lead to significant duplicate work being performed.
+
+When possible, it is recommended that you batch updates to `@live` resolvers. This can be done by wrapping your state updates in a `batchLiveStateUpdates()` call on your `RelayStore` instance.
+
+A typical use with a Redux store might look like this:
+
+```ts
+const store = createStore(reducer);
+const originalDispatch = store.dispatch;
+
+function wrapped(action) {
+  relayStore.batchLiveStateUpdates(() => {
+    originalDispatch(action);
+  })
+}
+
+store.dispatch = wrapped;
+```

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

@@ -0,0 +1,161 @@
+---
+id: return-types
+title: "Return Types"
+slug: /guides/relay-resolvers/return-types/
+description: Showing the different types of return values for Relay Resolvers
+keywords:
+- resolvers
+- derived
+- selectors
+- reactive
+---
+
+Relay Resolvers support a number of different return types, each of which has different semantics. This page will walk through the different types of supported return values and how they are used.
+
+## Scalar Types
+
+The simplest type for a resolver to return is a built-in GraphQL scalar value. Scalar values are values that can be represented as a primitive value in GraphQL, such as a string, number, or boolean. To return a scalar simply define your resolver as returning the scalar type and then return the corresponding JavaScript value from your resolver function.
+
+```tsx
+/**
+ * @relayField Post.isValid: Boolean
+ */
+export function isValid(post: PostModel): boolean {
+  return post.content !== "" && post.author != null;
+}
+```
+
+## List Types
+
+Resolvers may also return a list of values. To do so, define your resolver as returning a list of the corresponding type and return an array from your resolver function.
+
+```tsx
+/**
+ * @relayField User.favoriteColors: [String]
+ */
+export function favoriteColors(user: UserModel): string[] {
+  return user.favoriteColors;
+}
+```
+
+This pattern can be used for the other types, with the exception of server types, which don't yet support lists.
+
+## Client-defined GraphQL Types
+
+Resolvers can also model edges to other GraphQL types in your Resolver schema. If the type was defined as a "strong" type, the resolver function must return an object `{ id: DataID }` where `DataID` is the ID of the object. Relay will take care of invoking the type's model resolver function.
+
+```tsx
+import {DataID} from 'relay-runtime';
+/**
+ * @relayField Post.author: User
+ */
+export function author(post: PostModel): { id: DataID } {
+  return { id: post.authorId };
+}
+```
+
+If the type was defined as `@weak`, the resolver function must return an object matching the type's model type.
+
+```tsx
+/**
+ * @relayField User.profilePicture: ProfilePicture
+ */
+export function profilePicture(user: UserModel): ProfilePicture {
+  return {
+    url: user.profilePicture.url,
+    width: user.profilePicture.width,
+    height: user.profilePicture.width,
+  }
+}
+```
+
+:::tip
+Relay will emit type assertions in its generated code to help catch errors where a resolver implementation does not match whats declared in its docblock.
+:::
+
+## Server Types
+
+Relay Resolvers also support modeling edges to types defined on your server schema that implement the [`Node` specification](https://graphql.org/learn/global-object-identification/#node-root-field). Since objects which implement Node each have a globally unique ID, resolvers modeling edges to these server types simply need to return that unique ID.
+
+At compile-time Relay derives a GraphQL query for each selections on this field and will lazily fetch that data on render.
+
+```tsx
+import {DataID} from 'relay-runtime';
+/**
+ * @relayField Post.author: User
+ */
+export function author(post: PostModel): DataID {
+  return post.authorId;
+}
+```
+
+:::warning
+Edges to server types that are only known the client force Relay to fetch data lazily which will force an additional cascading network roundtrip. This is generally not optimal and should be avoided where possible.
+:::
+
+To highlight this point, at compile time, Relay requires that selection that reads client to server edge field annotate the field with the `@waterfall` directive. This is intended to remind the author and reviewer that a tradeoff is being made here and to carefully consider the implications.
+
+```tsx
+function Post() {
+  const data = useLazyLoadQuery(graphql`
+    query PostQuery {
+      post {
+        author @waterfall {
+          name
+        }
+      }
+    }`, {});
+  return <p>{data.post.author.name}</p>;
+}
+```
+
+## Abstract Types
+
+Resolvers may return some permutations of "abstract" types (GraphQL unions and interfaces). To use this feature simply use the abstract type's name in the docblock field description and include the typename in the object returned from your resolver. For "strong" types, that will look like: `{id: DataID, __typename: string}`. For "weak" types that will look like: `{__relay_model_instance: T, __typename: string}`.
+
+```tsx
+import {DataID} from 'relay-runtime';
+
+type AnimalTypenames = "Cat" | "Dog";
+/**
+ * @relayField User.pet: Animal
+ */
+export function pet(user: User): {id: DataID, __typename: AnimalTypenames } {
+  return {id: "5", __typename: "Dog" }
+}
+```
+
+:::tip
+Relay will generate type assertions to ensure your resolver function returns the expected type. However, not all combinations are supported. For example, Relay does not yet support the following permutations of abstract types: Unions including weak types, abstract types which mix strong and weak types, and abstract types which include server-backed types.
+:::
+
+While abstract types themselves cannot be defined using Resolver syntax today, you may define interfaces and unions, as well as their members, using [Client Schema Extensions](../client-schema-extensions.mdx). For example:
+
+```graphql title="client-schema.graphql"
+interface Animal {
+ legs: Int
+}
+
+extend type Cat implements Animal {
+  __do_not_use: String # Placeholder because GraphQL does not allow empty field sets.
+}
+```
+
+## JavaScript Values
+
+There are rare cases where you want to return an arbitrary JavaScript value from your Resolver schema, one which cannot not have a corresponding GraphQL type. As an escape hatch Relay supports a custom return type `RelayResolverValue` that allows you to return any JavaScript value from your resolver. **JavaScript values returned from resolvers should be immutable.**
+
+Consumers of this field will see a TypeScript/Flow type that is derived from your resolver function's return type.
+
+```tsx
+/**
+ * @relayField Post.publishDate: RelayResolverValue
+ */
+export function metadata(post: PostModel): Date {
+  return post.publishDate;
+}
+```
+
+:::warning
+Use of `RelayResolverValue` should be considered an "escape hatch" and may be deprecated in future versions of Relay. In most cases a preferable pattern is to define a custom scalar in your [client schema extensions](../client-schema-extensions.mdx) and add a type definition for that custom scalar in your Relay config.
+:::

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

@@ -0,0 +1,41 @@
+---
+id: suspense
+title: "Suspense"
+slug: /guides/relay-resolvers/suspense/
+description: Handling loading states for live data
+---
+
+With [Live Resolvers](./live-fields.mdx), it's possible that the data you are exposing in the graph may not be synchronously available. For example, if you are fetching data from a remote API, it may take some time for the data to be fetched. Relay Resolvers provide a mechanism for handling this loading state.
+
+If a Live Resolver returns the "suspense sentinel" value, all consumers of that field will suspend until that field updates with a non-suspense value.
+
+## Suspense Sentinel
+
+If a Live Resolver is in a loading state, it may return a special sentinel value to indicate that the data is not yet available.
+
+```ts
+import {suspenseSentinel} from 'relay-runtime';
+
+/**
+ * @relayField Query.myIp: String
+ * @live
+ */
+export function myIp(): LiveState<string> {
+  return {
+    read: () => {
+      const state = store.getState();
+      const ipLoadObject = state.ip;
+      if (ipLoadObject.status === "LOADING") {
+        return suspenseSentinel();
+      }
+      return state.ip;
+    },
+    subscribe: (cb) => {
+      return store.subscribe(cb);
+    },
+  };
+}
+```
+
+:::note
+If a query or fragment will suspend if it reads any resolver field that is in a suspended state, even if it reads that resolver field indirectly via another resolvers `@rootFragment`.

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

@@ -0,0 +1,240 @@
+---
+id: required-directive
+title: "@required Directive"
+slug: /guides/required-directive/
+description: Relay guide to @required
+keywords:
+- required
+- directive
+- optional
+- nullthrows
+---
+
+import DocsRating from '@site/src/core/DocsRating';
+
+The `@required` directive can be added to fields in your Relay queries to declare how null values should be handled at runtime. You can think of it as saying "if this field is ever null, its parent field is invalid and should be null".
+
+When you have a GraphQL schema where many fields are nullable, a considerable amount of product code is needed to handle each field's potential "nullness" before the underlying data can be used. With `@required`, Relay can handle some types of null checks before it returns data to your component, which means that **any field you annotate with** **`@required`** **will become non-nullable in the generated types for your response**.
+
+If a `@required` field is null at runtime, Relay will "bubble" that nullness up to the field's parent. For example, given this query:
+
+```graphql
+query MyQuery {
+  viewer {
+    name @required(action: LOG)
+    age
+  }
+}
+```
+
+If `name` is null, Relay would return `{ viewer: null }`. You can think of `@required` in this instance as saying "`viewer` is useless without a `name`".
+
+## Action
+
+The `@required` directive has a required `action` argument which has four possible values:
+
+### `NONE` (expected)
+
+This field is expected to be null sometimes. The field's nullability will "bubble up" to make the parent field null if this field is missing, allowing the component to check the parent field instead of this specific field.
+
+### `LOG` (recoverable)
+
+This value is not expected to ever be null, but the component **can still render** if it is. If a field with `action: LOG` is null, the [Relay field logger](../api-reference/relay-runtime/field-logger.mdx) will receive a `missing_required_field.log` event. The field's nullability will "bubble up" to make the parent field null.
+
+### `THROW` (unrecoverable)
+
+This value should not be null, and the component **cannot render without it**. If a field with `action: THROW` is null at runtime, the component which reads that field **will throw during render**. The error message includes both the owner and field path. Only use this option if your component is contained within an [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary).
+
+**Note**: If you have opted into the optional `disallow_required_action_throw_on_semantically_nullable_fields` [compiler feature flag](../../docs/getting-started/compiler-config.mdx), this can only be used on fields that are non-nullable (`!` in the schema) or are marked with `@semanticNonNull` (an optional [semantic nullability](./semantic-nullability.mdx) feature that indicates fields should never be null in normal operation).
+
+### `DANGEROUSLY_THROW_ON_SEMANTICALLY_NULLABLE_FIELD` (unrecoverable, bypass validation)
+
+:::warning
+This option is included mostly as a migration path for existing codebases that used `@required(action: THROW)` on nullable fields. It is strongly discouraged to add new usages of this option.
+:::
+
+This action behaves identically to `THROW` but can be used on nullable fields. This is only needed when the optional [compiler feature flag](https://relay.dev/docs/getting-started/compiler-config/#FeatureFlags) `disallow_required_action_throw_on_semantically_nullable_fields` is enabled, which prevents using THROW on semantically nullable fields.
+
+
+## Locality
+
+A field's `@required` status is **local to the fragment where it is specified**. This allows you to add/remove the directive without having to think about anything outside the scope of your component.
+
+This choice reflects the fact that some components may be able to recover better from missing data than others. For example, a `<RestaurantInfo />` component could probably render something sensible even if the restaurant's address is missing, but a `<RestaurantLocationMap />` component might not.
+
+However, all usages of the `@required` directive on the same field in a single fragment must be consistent with their usage. This situation mostly occurs when selecting fields in inline fragments. For example, the following fragment would fail to compile:
+
+```graphql
+fragment UserInfo on User {
+  job {
+    ... on Actor {
+      certifications
+    }
+    ... on Lawyer {
+      certifications @required(action: LOG)
+    }
+  }
+}
+```
+
+The Relay compiler will give you an error like `All references to a field must have matching @required declarations.`. To fix this, either set the `@required` directive on each of the fields selected in the inline fragment or remove the directive entirely.
+
+## Chaining
+
+`@required` directives can be chained to make a deeply nested field accessible after just one null check:
+
+```javascript
+const user = useFragment(graphql`
+  fragment MyUser on User {
+    name @required(action: LOG)
+    profile_picture @required(action: LOG) {
+      url @required(action: LOG)
+    }
+  }`, key);
+ if(user == null) {
+   return null;
+ }
+ return <img src={user.profile_picture.url} alt={user.name} />
+```
+
+**Note**: If you use `@required` on a top level field of a fragment, the object returned from `useFragment` itself may become nullable. The generated types will reflect this.
+
+When chaining `@required` directives, the Relay compiler will help you from unintentionally creating a chain with a more severe action than intended. Consider the following fragment
+
+```graphql
+fragment MyUser on User {
+  profile_picture @required(action: THROW) {
+    url @required(action: LOG)
+  }
+}
+```
+
+In this example we want the component to THROW if the `profile_picture` field is null but we only want to LOG an error if the `url` field is null. But recall, Relay will "bubble" nullness up to the parent field, if the `url` field is null it will then cause the `profile_picture` field to become null as well. And once that happens, the component will THROW. If you implement a pattern like this, the Relay compiler will give you an error
+
+```
+A @required field may not have an `action` less severe than that of its @required parent. This @required directive should probably have `action: LOG` so that it can match its parent
+```
+
+To fix this, either change the `profile_picture` to use `action: LOG` or change the `url` field to use `action: THROW`.
+
+## Caveats with Connections
+
+There are currently some limitations in using the `@required` and `@connection` directives together. When you use the `@connection` directive, Relay  automatically inserts some additional fields into the connection, and those fields won't be generated with the `@required` directive. This can result in inconsistencies if you use the `@required` directive on fields in a Connection type. Consider the following example:
+
+```graphql
+fragment FriendsList on User @refetchable(queryName: "FriendsListQuery") {
+  friends(after: $cursor, first: $count) @connection(key: "FriendsList_friends") {
+    edges {
+      node @required(action: LOG) {
+        job @required(action: LOG) {
+          title @required(action: LOG)
+        }
+      }
+    }
+  }
+}
+```
+
+Any usages of `@required` on the `node` field or any of its direct child fields will cause the Relay compiler to give you an error saying `All references to a field must have matching @required declarations.`. In order to bypass this you'll need to remove the `@required` directives on those fields.
+
+In the above example, we'd need to remove the `@required` directives on both the `node` and `job` fields, but the usage on the `title` field would not create an error.
+
+```graphql
+fragment FriendsList on User @refetchable(queryName: "FriendsListQuery") {
+  friends(after: $cursor, first: $count) @connection(key: "FriendsList_friends") {
+    edges {
+      node {
+        job {
+          title @required(action: LOG)
+        }
+      }
+    }
+  }
+}
+```
+
+## FAQ
+
+### Why did @required make a non-nullable field/root nullable?
+
+When using the `LOG` or `NONE` actions, Relay will "bubble" a missing field up to its parent field or fragment root. This means that adding `@required(action: LOG)` (for example) to a child of a non-nullable fragment root will cause the type of the fragment root to become nullable.
+
+### What happens if you use `@required` in a plural field
+
+If a `@required(action: LOG)` field is missing in a plural field, the _item_ in the list will be returned as null. It will _not_ cause the entire array to become null.. If you have any question about how it will behave, you can inspect the generated Flow types.
+
+### Why are @required fields in an inline fragment still nullable?
+
+Imagine a fragment like this:
+
+```graphql
+fragment MyFrag on Actor {
+  ... on User {
+    name @required(action: THROW)
+  }
+}
+```
+
+It's possible that your `Actor` will not be a `User` and therefore not include a `name`. To represent that in types, we generate a Flow type that looks like this: `{name?: string}`.
+
+If you encounter this issue, you can add a `__typename` like this:
+
+```graphql
+fragment MyFrag on Actor {
+  __typename
+  ... on User {
+    name @required(action: THROW)
+  }
+}
+```
+
+In this situation Relay will generate a union type like: `{__typename: 'User', name: string} | {__typename: '%ignore this%}`. Now you can check the `__typename` field to narrow your object's type down to one that has a non-nullable `name`.
+
+<FbInternalOnly>
+
+Example diff showing the adoption of this strategy: D24370183
+
+</FbInternalOnly>
+
+### Why not implement this at the schema/server level?
+
+The "requiredness" of a field is actually a product decision and not a schema question. Therefore we need to implement the handling of it at the product level. Individual components need to be able to decide for themselves how to handle a missing value.
+
+For example, if a notification is trying to show the price for a Marketplace listing, it could probably just omit the price and still render. If payment flow for that same listing is missing the price, it should probably blow up.
+
+Another issue is that changes to the server schema are much more difficult to ship since they affect all existing clients across all platforms.
+
+Basically every value returned by Relay is nullable. This is intentional since we want to be able to handle field-level errors whenever possible. If we lean into KillsParentOnException we would end up wanting to make basically every field use it and our apps would be becomes more brittle since errors which used to be small, become large.
+
+<FbInternalOnly>
+
+_Extracted from [this comment thread](https://fb.workplace.com/groups/cometeng/permalink/937671436726844/?comment_id=937681186725869)._
+_Further discussion in [this comment thread](https://fb.workplace.com/groups/cometeng/permalink/937671436726844/?comment_id=938335873327067)._
+
+</FbInternalOnly>
+
+### Can `(action: NONE)` be the default?
+
+On one hand action: NONE makes the most sense as a default (omitted action == no action). However, we are aware that whichever value we choose as the default will be considered the default action for engineers to choose since it's the path of least resistance.
+
+We actually believe that in most cases LOG is the most ideal choice. It gives the component a chance to gracefully recover while also giving us signal that a part of our app is rendering in a sub-optimal way.
+
+We debated making LOG the default action for that reason, but I think that's confusing as well.
+
+So, for now we are planning to not offer a default argument. After all, it's still much less to write out than the equivalent manual null checks. Once we see how people use it we will consider what value (if any) should be the default.
+
+<FbInternalOnly>
+
+### Does @required change anything about the logger project field?
+
+When using recoverableViolation or unrecoverableViolation, the second argument is the FBLogger project name ([defined on Comet here](https://fburl.com/diffusion/rn99dl4s)):
+
+```javascript
+recoverableViolation('My error string', 'my_logger_project');
+```
+
+When you switch to using `@required`, any `THROW` or `LOG` actions will log to the `relay-required` logger project instead ([see here in logview](https://fburl.com/logview/l40t7cjv)).
+
+For most teams, this shouldn't be an issue; care has been taken to ensure tasks still get routed to the correct owner of the file that is using `@required`. However, if your team has any queries that utilize the logger project field, you may want to consider the implications.
+
+</FbInternalOnly>