@@ -21,8 +21,8 @@ explicitly marked as non-nullable.
21
21
22
22
When a non-nullable field resolves to ` null ` , the GraphQL execution engine
23
23
raises a runtime error and attempts to recover by replacing the nearest
24
- nullable parent field with ` null ` . This behavior is known
25
- as null bubbling.
24
+ nullable parent field with ` null ` . This behavior is known formally as "error
25
+ propagation" but more commonly as null bubbling.
26
26
27
27
Understanding nullability requires familiarity with the GraphQL type system,
28
28
execution semantics, and the trade-offs involved in schema design.
@@ -55,8 +55,7 @@ You can use `GraphQLNonNull` with:
55
55
56
56
- Field types
57
57
- Argument types
58
- - Input object fields
59
- - Return types for resolvers
58
+ - Input object field types
60
59
61
60
You can also combine it with other types to create more
62
61
specific constraints. For example:
@@ -134,9 +133,14 @@ field can affect large portions of the response.
134
133
135
134
Non-null constraints are part of a field's contract:
136
135
137
- - Changing a field from non-nullable to nullable is a breaking change.
138
- - Changing from nullable to non-nullable is also breaking unless you can
139
- guarantee that the field will never return ` null ` .
136
+ - Changing an output position (field type) from non-nullable to nullable is a
137
+ breaking change - clients may now receive ` null ` values which they do not have
138
+ handling code for.
139
+ - Changing an input position (argument or input field type) from nullable to
140
+ non-nullable is a breaking change - clients are now required to provide this
141
+ value, which they may not have been supplying previously.
142
+ - Changing an output position from nullable to non-nullable will not break
143
+ deployed clients since their null handling code will simply not be exercised.
140
144
141
145
To reduce the risk of versioning issues, start with nullable fields and add
142
146
constraints as your schema matures.
@@ -211,18 +215,21 @@ constraints when data consistency is guaranteed.
211
215
correctness.
212
216
- Validate early. Add checks in resolvers to prevent returning ` null ` for
213
217
non-null fields.
218
+ - Consider error boundaries. Were an error to occur, where should it stop
219
+ bubbling?
214
220
- Watch for nesting. Distinguish between:
215
- - ` [User]! ` - nullable list of non-null users
221
+ - ` [User!] ` - nullable list of non-null users
222
+ - ` [User]! ` - non-null list of nullable users
216
223
- ` [User!]! ` - non-null list of non-null users
217
224
218
225
## Additional resources
219
226
220
227
- [ GraphQL Specification: Non-null] ( https://spec.graphql.org/draft/#sec-Non-Null ) :
221
228
Defines the formal behavior of non-null types in the GraphQL type system and
222
229
execution engine.
223
- - [ Understanding GraphQL.js Errors] ( website\ pages\ docs\ graphql-errors.mdx ) : Explains
230
+ - [ Understanding GraphQL.js Errors] ( website/ pages/ docs/ graphql-errors.mdx ) : Explains
224
231
how GraphQL.js propagates and formats execution-time errors.
225
- - [ Anatomy of a Resolver] ( website\ pages\ docs\ resolver-anatomy.mdx ) : Breaks down
232
+ - [ Anatomy of a Resolver] ( website/ pages/ docs/ resolver-anatomy.mdx ) : Breaks down
226
233
how resolvers work in GraphQL.js.
227
- - [ Constructing Types] ( website\ pages\ docs\ constructing-types.mdx ) : Shows how
234
+ - [ Constructing Types] ( website/ pages/ docs/ constructing-types.mdx ) : Shows how
228
235
to define and compose types in GraphQL.js.
0 commit comments