Skip to content

Commit ac1e676

Browse files
committed
Update semantic nullability docs
Summary: Test Plan:
1 parent d8846a4 commit ac1e676

File tree

1 file changed

+11
-1
lines changed

1 file changed

+11
-1
lines changed

website/docs/05-guides/04-strict-semantic-nullability.mdx

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,15 @@ Strict Semantic Nullability can be enabled in your Grats config within your `tsc
6565
Grats aims to let the community experiment with Strict Semantic Nullability, this involves supporting some of the proposed RFC, but not all of it. In particular:
6666

6767
- Grats does not support using introspection to determine if a field is semantically non-null
68-
- Grats does not support declaring items within a list as being semantically non-null
68+
- Grats does not support declaring items within a list as being semantically non-null.
69+
70+
:::info
71+
Grats does not support marking list items as semantically non-null because most resolvers are not written in such a way that indiviudal items in the list can error in a way that does not result in the list resolver itself throwing. Generally this can only happen if you return an `Iterable` and it throws when calling `next()`.
72+
:::
73+
74+
## Runtime Validation
75+
76+
When Strict Semantic Nullability is enabled, Grats will insert runtime validation to ensure that fields marked as semantically non-null never return null. This validation will throw an error if the field returns null, indicating that the field is in an error state. This is nessesary because TypeScript is not fully sound, and it is possible to return null from a function that is typed as non-nullable:
6977

7078
```typescript
7179
/** @gqlField */
@@ -83,3 +91,5 @@ export function aString(_: Query): string {
8391
- [Apollo's specification for this directive](https://specs.apollo.dev/nullability/v0.2/)
8492
- [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)
8593
- [Example project showing this feature used with experimental support in Relay](https://github.com/captbaritone/grats-relay-example/pull/1)
94+
- [Semantic Nullability - A Path Toward Safe NonNull Fields](https://www.youtube.com/watch?v=kVYlplb1gKk) - My talk at GraphQL Conf. 2024 explaining Semantic Nullability
95+
- [Awesome Semantic Nullability](https://github.com/captbaritone/awesome-semantic-nullability/) - A list of projects and tools that support or implement Strict Semantic Nullability

0 commit comments

Comments
 (0)