Tutorial - Update Link.comments return type (#3547)

* Tutorial - Update Link.comments return type * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Valentin Cocaud <[email protected]> * Tutorial: Expand more on the different array types * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Jason Kuhrt <[email protected]> * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Valentin Cocaud <[email protected]> * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Valentin Cocaud <[email protected]> * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Valentin Cocaud <[email protected]> * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Valentin Cocaud <[email protected]> * Update website/src/pages/tutorial/basic/08-graph-relations.mdx Co-authored-by: Valentin Cocaud <[email protected]> * Prettier * chore(dependencies): updated changesets for modified dependencies --------- Co-authored-by: Valentin Cocaud <[email protected]> Co-authored-by: Jason Kuhrt <[email protected]> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
dotansimha · Dec 15, 2024 · 8fee214 · 8fee214
1 parent ea66fcc
commit 8fee214
Show file tree

Hide file tree

Showing 5 changed files with 61 additions and 16 deletions.
diff --git a/.changeset/@graphql-yoga_plugin-apollo-usage-report-3547-dependencies.md b/.changeset/@graphql-yoga_plugin-apollo-usage-report-3547-dependencies.md
@@ -0,0 +1,6 @@
+---
+"@graphql-yoga/plugin-apollo-usage-report": patch
+---
+dependencies updates:
+  - Removed dependency [`@graphql-tools/utils@^10.6.1` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.6.1) (from `peerDependencies`)
+  - Removed dependency [`@whatwg-node/fetch@^0.10.1` ↗︎](https://www.npmjs.com/package/@whatwg-node/fetch/v/0.10.1) (from `peerDependencies`)
diff --git a/.changeset/@graphql-yoga_plugin-apq-3547-dependencies.md b/.changeset/@graphql-yoga_plugin-apq-3547-dependencies.md
@@ -0,0 +1,5 @@
+---
+"@graphql-yoga/plugin-apq": patch
+---
+dependencies updates:
+  - Removed dependency [`@graphql-tools/utils@^10.6.1` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.6.1) (from `peerDependencies`)
diff --git a/.changeset/@graphql-yoga_plugin-persisted-operations-3547-dependencies.md b/.changeset/@graphql-yoga_plugin-persisted-operations-3547-dependencies.md
@@ -0,0 +1,5 @@
+---
+"@graphql-yoga/plugin-persisted-operations": patch
+---
+dependencies updates:
+  - Removed dependency [`@graphql-tools/utils@^10.6.1` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.6.1) (from `peerDependencies`)
diff --git a/.changeset/graphql-yoga-3547-dependencies.md b/.changeset/graphql-yoga-3547-dependencies.md
@@ -0,0 +1,8 @@
+---
+"graphql-yoga": patch
+---
+dependencies updates:
+  - Updated dependency [`@graphql-tools/executor@^1.3.7` ↗︎](https://www.npmjs.com/package/@graphql-tools/executor/v/1.3.7) (from `^1.3.5`, in `dependencies`)
+  - Updated dependency [`@graphql-tools/schema@^10.0.11` ↗︎](https://www.npmjs.com/package/@graphql-tools/schema/v/10.0.11) (from `^10.0.10`, in `dependencies`)
+  - Updated dependency [`@graphql-tools/utils@^10.6.2` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.6.2) (from `^10.6.1`, in `dependencies`)
+  - Updated dependency [`@whatwg-node/server@^0.9.63` ↗︎](https://www.npmjs.com/package/@whatwg-node/server/v/0.9.63) (from `^0.9.60`, in `dependencies`)
diff --git a/website/src/pages/tutorial/basic/08-graph-relations.mdx b/website/src/pages/tutorial/basic/08-graph-relations.mdx
@@ -399,32 +399,53 @@ type Link {
 On the Prisma API level, the method call for loading will always return an array. It does not
 distinguish between an empty array and an array with comments.
 
-On the GraphQL schema, we have three options:
+As we design our GraphQL schema we need to consider how we will model the concept of a Link without
+comments.
+
+We have a couple of options:
+
+First in terms of the array itself, we can define it as nullable or not. Then for the elements of
+the array, also there we can define them as nullable or not.
+
+Here are the 4 options, first two are for nullable array and the last two for none nullable array:
 
 1. `comments: [Comment]`
 2. `comments: [Comment!]`
-3. `comments: [Comment!]!`
+3. `comments: [Comment]!`
+4. `comments: [Comment!]!`
 
 Let's try to explain the differences between the options. We'll also describe the Typescript return
 value of each option (which will be automatically generated in the later Codegen chapter).
 
-Option 1, `[Comment]`, means that each element of the array can be Comment or null and the array
-itself can be null. The Typescript return type of that resolver would be
-`Array<Comment | null> | null`. It means there are too many ways and cases to describe when we
-return an empty array. The client will have to deal with many cases.
+Option 1, `[Comment]`, means that the elements both the array and its elements are nullable. The
+Typescript return type of that resolver would be `Array<Comment | null> | null`. Representing
+`there's no Comment related to the Link` in that option can be applied in many different ways - an
+empty array, a null as array or an array with null elements. That means that the client who consumes
+this will need to handle many cases.
+
+Option 2, `[Comment!]`, means that the elements of the array are none nullable, but the array can be
+empty or null. The Typescript return type of that resolver would be `Array<Comment> | null`.
+
+Representing `there's no Comment related to the Link` in that option can be applied in many
+different ways - the array can be null or be empty, but at least the array can't have null elements.
+Here also the client needs to handle a couple of different possibilities.
+
+Option 3, `[Comment]!`, means that the array is none nullable, but the elements can be null.
+
+Representing `there's no Comment related to the Link` in that option can be applied in many
+different ways - it can't be a null as array, but it can be an empty array or an array with null
+elements. Here also the client needs to handle a couple of the different possibilities.
+
+Option 4, `[Comment!]!`, means that the elements of the array are none nullable and the array itself
+must return a value. The Typescript return type for of resolver would be `Array<Comment>`.
 
-Option 2, `[Comment!]`, means each element of the array must be Comment, but the array can return
-empty or null. The Typescript return type of that resolver would be `Array<Comment> | null`. If the
-backend returns null or an empty array [], they can both mean
-`there's no Comment related to the Link`. Meaning we have two ways to represent the same concept -
-which makes it harder for the client to handle that case.
+With `[Comment!]!`, the only way for the server to represent
+`there's no Comment related to the Link` is to return an empty array `[]`.
 
-Option 3, `[Comment!]!`, means each element of the array must be Comment. The Typescript return type
-for of resolver would be `Array<Comment>`. With `[Comment!]!`, the server can only return an empty
-array `[]`. This means it's easier for the client to handle because there's only one way to
-represent the `there's no Comment related to the Link` concept.
+This means it's easier for the client to handle because there's **only one way** to represent the
+`there's no Comment related to the Link` concept.
 
-For the reasons above we'll chose option `3` for our implementation.
+For the reasons above we've chose option `4` for our implementation.
 
 Now let's implement the corresponding `Link.comments` resolver. For this, you need to touch the
 `Link` object types resolver map.