Skip to content

Commit

Permalink
Update error handling and semantic nullability docs to include talks …
Browse files Browse the repository at this point in the history
…and links (#4800)

Summary: Pull Request resolved: #4800

Reviewed By: evanyeung

Differential Revision: D63043507

Pulled By: captbaritone

fbshipit-source-id: dedba497bb0f03f86f31c52f886dbbc236738a9a
  • Loading branch information
captbaritone authored and facebook-github-bot committed Sep 20, 2024
1 parent 66fc7a0 commit 0cf0948
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 4 deletions.
6 changes: 6 additions & 0 deletions website/docs/guides/catch-directive.md
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
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
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

0 comments on commit 0cf0948

Please sign in to comment.