Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update error handling and semantic nullability docs to include talks and links #4800

Closed
wants to merge 1 commit into from
Closed

Update error handling and semantic nullability docs to include talks and links #4800

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions website/docs/guides/catch-directive.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,3 +175,9 @@ default argument - which means you can write either `@catch` or

`@catch(to: NULL)` will provide you with the exact same behavior as existed
before `@catch` was possible. The field will be null if it contains an error.

## GraphQL Conf Talk

The Relay team gave a talk at GraphQL Conf 2024 about `@catch` and explicit error handling in Relay. You can watch it here:

<iframe src="https://www.youtube-nocookie.com/embed/_TSYKAtaK5A" width={640} height={360} allowFullScreen={true} frameBorder="0" />
6 changes: 6 additions & 0 deletions website/docs/guides/graphql-server-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -438,6 +438,12 @@ Relay uses all of this functionality to build out abstractions around connection

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.
Expand Down
12 changes: 8 additions & 4 deletions website/docs/guides/semantic-nullability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,6 @@ keywords:
- semanticNonNull
---

:::warning
**Experimental**: Because Strict Semantic Nullability is still in flux, the implementation and behavior within Relay are subject to change and may have unexpected behavior as we learn more about the idea and its implications.
:::

## Motivation

One of GraphQL's strengths is its field-granular error handling which can dramatically improve response resiliency. However, today that error handling depends upon field nullability, which is the reason it is a [recommended best practice](https://graphql.org/learn/best-practices/#nullability) to default all fields to being nullable. This creates a trade-off where __enabling maximum resiliency means client developers must manually handle all possible permutations of field nullability__ within their components. [`@required`](./required-directive.md) can help a bit, but is ultimately a very blunt tool.
Expand Down Expand Up @@ -79,6 +75,13 @@ function UserComponent(props: Props) {

For a hands on example, see [this example project](https://github.com/captbaritone/grats-relay-example/pull/1) showing Relay configured to use `@semanticNonNull` and `@throwOnFieldError` alongside [Grats](https://grats.capt.dev/) which [has support](https://grats.capt.dev/docs/guides/strict-semantic-nullability/) for automatically deriving a schema that includes the experimental `@semanticNonNull` directives.

## GraphQL Conf Talk

The Relay team gave a talk at GraphQL Conf 2024 about semantic nullability. You can watch it here:

<iframe src="https://www.youtube-nocookie.com/embed/kVYlplb1gKk" width={640} height={360} allowFullScreen={true} frameBorder="0" />


## Further Reading

- [True Nullability Schema](https://github.com/graphql/graphql-wg/discussions/1394)
Expand All @@ -87,3 +90,4 @@ For a hands on example, see [this example project](https://github.com/captbarito
- [Grat's support/documentation for `@SemanticNonNull`](https://grats.capt.dev/docs/guides/strict-semantic-nullability/)
- [Apollo's specification for this directive](https://specs.apollo.dev/nullability/v0.2/)
- [Support for `@SemanticNonNull` in Apollo Kotlin](https://www.apollographql.com/docs/kotlin/v4/advanced/nullability/#handle-semantic-non-null-with-semanticnonnull) added in [4.0.0-beta.3](https://github.com/apollographql/apollo-kotlin/releases/tag/v4.0.0-beta.3)
- [Awesome Semantic Nullability](https://github.com/captbaritone/awesome-semantic-nullability) a list of frameworks and stand alone tools that support semantic nullability
Loading