Inline versioned tutorial (#1762)

* begin with v3 tutorial

* inline versioning

* no tutorial in docs

* error handling

* filtering and pagination

* point to v3

* micro adjustments

* drop empty code block

* use native details tag

Author: enisdenjo

website/src/pages/tutorial/basic/03-graphql-server.mdx

@@ -8,15 +8,18 @@ You are going to use the HTTP protocol to serve the GraphQL server, but note tha
 
 ## Creating a GraphQL HTTP Server with Yoga
 
-In this tutorial, we will be using `@graphql-yoga/node` for building our Node.js GraphQL HTTP server.
+In this tutorial, we will be using GraphQL Yoga for building our Node.js GraphQL HTTP server.
 
 <Callout>
   Yoga can also run on other platforms, such as Cloudflare Workers or Deno. We
   recommend checking out [the integrations
-  section](/docs/integrations/integration-with-cloudflare-workers) in our
+  section](/v3/integrations/integration-with-cloudflare-workers) in our
   documentation after finishing the tutorial.
 </Callout>
 
+<details>
+  <summary>v2</summary>
+
 You'll need the `@graphql-yoga/node` package available in your project, so install it using the following command:
 
 <PackageCmd packages={['--save-exact @graphql-yoga/node']} />
@@ -46,7 +49,35 @@ $ cross-env NODE_ENV=development ts-node-dev --exit-child --respawn src/main.ts
 [2022-02-25 14:40:17.818 +0000] INFO (13296 on DESKTOP-U72CGKK): GraphQL Server running at http://127.0.0.1:4000/graphql.
 ```
 
-Now open your browser and navigate to `http://localhost:4000/graphql`.
+</details>
+
+<details open>
+  <summary>v3</summary>
+
+You'll need the `graphql-yoga` package available in your project, so install it using
+the following command:
+
+<PackageCmd packages={['--save-exact graphql-yoga']} />
+
+Now, update `src/main.ts` to create a simple GraphQL HTTP server on port `4000`:
+
+```ts filename="src/main.ts"
+import { createYoga } from 'graphql-yoga'
+import { createServer } from 'http'
+import { schema } from './schema'
+
+function main() {
+  const yoga = createYoga({ schema })
+  const server = createServer(yoga)
+  server.listen(4000)
+}
+
+main()
+```
+
+Now, try to run your server again with `npm run dev` (or, `npm run start`), open your browser and navigate to `http://localhost:4000/graphql`.
+
+</details>
 
 Type in the following operation in the left editor section and press the `Play` button for executing the operation against the GraphQL server.
 

website/src/pages/tutorial/basic/07-connecting-server-and-database.mdx

@@ -32,8 +32,12 @@ export async function createContext(): Promise<GraphQLContext> {
 
 Now, you'll need to import the `createContext` function and make sure you add it as part of the GraphQL execution process:
 
+<details>
+  <summary>v2</summary>
+
 ```typescript
-// ... other imports ...
+import { createServer } from '@graphql-yoga/node'
+import { schema } from './schema'
 import { createContext } from './context'
 
 async function main() {
@@ -44,6 +48,28 @@ async function main() {
 main()
 ```
 
+</details>
+
+<details open>
+  <summary>v3</summary>
+
+```typescript
+import { createYoga } from 'graphql-yoga'
+import { createServer } from 'http'
+import { schema } from './schema'
+import { createContext } from './context'
+
+function main() {
+  const yoga = createYoga({ schema, context: createContext })
+  const server = createServer(yoga)
+  server.listen(4000)
+}
+
+main()
+```
+
+</details>
+
 In the next step, you'll connect the Prisma client and your GraphQL server!
 
 ## Updating the Resolver Functions to Use Prisma Client

website/src/pages/tutorial/basic/09-error-handling.mdx

@@ -121,6 +121,9 @@ This is great, but now we never know why our request failed 🤔 and the error m
 
 Let's change the implementation to expose the much more helpful message `Cannot post comment on non-existing link with id 'X'.` instead of `Unexpected error.`.
 
+<details>
+  <summary>v2</summary>
+
 For doing so you will use the `GraphQLYogaError` class that is exported from the `@graphql-yoga/node` package.
 
 Add the following catch handler for mapping a foreign key error into a `GraphQLYogaError`:
@@ -169,6 +172,61 @@ const resolvers = {
 The error code `P2003` indicates a foreign key constraint error. You can learn more about it in [the Prisma documentation](https://prisma.io/docs/reference/api-reference/error-reference#p2003).
 You use that code for identifying this edge case of a missing link and then throw a `GraphQLYogaError` with a useful error message instead.
 
+</details>
+
+<details open>
+  <summary>v3</summary>
+
+For doing so you will use the `GraphQLError` class that is exported from the `graphql` package.
+
+Add the following catch handler for mapping a foreign key error into a `GraphQLError`:
+
+```ts
+// ... other imports ...
+import { GraphQLError } from 'graphql'
+// ... other imports ...
+
+const resolvers = {
+  // ... other resolver maps ...
+  Mutation: {
+    // ... other Mutation object type field resolver functions ...
+    async postCommentOnLink(
+      parent: unknown,
+      args: { linkId: string; body: string },
+      context: GraphQLContext,
+    ) {
+      const comment = await context.prisma.comment
+        .create({
+          data: {
+            body: args.body,
+            linkId: parseInt(args.linkId),
+          },
+        })
+        .catch((err: unknown) => {
+          if (
+            err instanceof PrismaClientKnownRequestError &&
+            err.code === 'P2003'
+          ) {
+            return Promise.reject(
+              new GraphQLError(
+                `Cannot post comment on non-existing link with id '${args.linkId}'.`,
+              ),
+            )
+          }
+          return Promise.reject(err)
+        })
+
+      return comment
+    },
+  },
+}
+```
+
+The error code `P2003` indicates a foreign key constraint error. You can learn more about it in [the Prisma documentation](https://prisma.io/docs/reference/api-reference/error-reference#p2003).
+You use that code for identifying this edge case of a missing link and then throw a `GraphQLError` with a useful error message instead.
+
+</details>
+
 Restart the server using `npm run dev` and again execute the mutation operation using GraphiQL.
 
 ```graphql
@@ -200,9 +258,9 @@ You will receive a response with the `Cannot post comment on non-existing link w
 }
 ```
 
-As you might have noticed, GraphQLYoga will exclude `GraphQLYogaError` errors thrown within the resolvers from masking the error masking.
+As you might have noticed, GraphQL Yoga will exclude wrapped errors thrown within the resolvers from masking the error masking.
 
-That means every time you want to expose an error to the outside world you should throw a `GraphQLYogaError` error.
+That means every time you want to expose an error to the outside world you should throw such an error.
 
 At the same time, any other unexpected error will automatically be masked from the outside world, bringing you sensible and safe defaults for a GraphQL Yoga production deployment!
 
@@ -306,8 +364,12 @@ There are multiple mathematical numeral systems. The implementation tries to be
 
 Add the following code to the `src/schema.ts` file.
 
+<details>
+  <summary>v2</summary>
+
 ```ts filename="src/schema.ts"
 // ... other code ...
+import { GraphQLYogaError } from '@graphql-yoga/node'
 
 const parseIntSafe = (value: string): number | null => {
   if (/^(\d+)$/.test(value)) {
@@ -359,6 +421,67 @@ const resolvers = {
 }
 ```
 
+</details>
+
+<details open>
+  <summary>v3</summary>
+
+```ts filename="src/schema.ts"
+// ... other code ...
+import { GraphQLError } from 'graphql'
+
+const parseIntSafe = (value: string): number | null => {
+  if (/^(\d+)$/.test(value)) {
+    return parseInt(value, 10)
+  }
+  return null
+}
+
+const resolvers = {
+  // ... other resolver maps ...
+  Mutation: {
+    // ... other field resolver functions
+    async postCommentOnLink(
+      parent: unknown,
+      args: { linkId: string; body: string },
+      context: GraphQLContext,
+    ) {
+      const linkId = parseIntSafe(args.linkId)
+      if (linkId === null) {
+        return Promise.reject(
+          new GraphQLError(
+            `Cannot post comment on non-existing link with id '${args.linkId}'.`,
+          ),
+        )
+      }
+
+      const comment = await context.prisma.comment
+        .create({
+          data: {
+            body: args.body,
+            linkId,
+          },
+        })
+        .catch((err: unknown) => {
+          if (err instanceof PrismaClientKnownRequestError) {
+            if (err.code === 'P2003') {
+              return Promise.reject(
+                new GraphQLError(
+                  `Cannot post comment on non-existing link with id '${args.linkId}'.`,
+                ),
+              )
+            }
+          }
+          return Promise.reject(err)
+        })
+      return comment
+    },
+  },
+}
+```
+
+</details>
+
 The regex `/^(\d+)$/` simply verifies that every character within the `value` is a digit. In case the value includes a non-digit character, you simply return `null` and then reject the resolver with a `GraphQLYogaError` error.
 
 Returning `null` instead of returning `NaN` is the better choice here, as it allows nice TypeScript checks (`linkId === null`).

website/src/pages/tutorial/basic/10-filtering-and-pagination.mdx

@@ -178,7 +178,11 @@ Let's use the value 30 as the default value and 50 as the upper limit and 1 as t
 
 Adjust the current schema resolver implementation according to the following.
 
+<details>
+  <summary>v2</summary>
+
 ```ts
+import { GraphQLYogaError } from '@graphql-yoga/node'
 // ... other code ...
 
 const applyTakeConstraints = (params: {
@@ -228,6 +232,64 @@ const resolvers = {
 }
 ```
 
+</details>
+
+<details open>
+  <summary>v3</summary>
+
+```ts
+// ... other code ...
+import { GraphQLError } from 'graphql'
+
+const applyTakeConstraints = (params: {
+  min: number
+  max: number
+  value: number
+}) => {
+  if (params.value < params.min || params.value > params.max) {
+    throw new GraphQLError(
+      `'take' argument value '${params.value}' is outside the valid range of '${params.min}' to '${params.max}'.`,
+    )
+  }
+  return params.value
+}
+
+const resolvers = {
+  // ... other resolvers maps ...
+  Query: {
+    // ... other Query object type resolver functions ...
+    async feed(
+      parent: unknown,
+      args: { filterNeedle?: string; skip?: number; take?: number },
+      context: GraphQLContext,
+    ) {
+      const where = args.filterNeedle
+        ? {
+            OR: [
+              { description: { contains: args.filterNeedle } },
+              { url: { contains: args.filterNeedle } },
+            ],
+          }
+        : {}
+
+      const take = applyTakeConstraints({
+        min: 1,
+        max: 50,
+        value: args.take ?? 30,
+      })
+
+      return context.prisma.link.findMany({
+        where,
+        skip: args.skip,
+        take,
+      })
+    },
+  },
+}
+```
+
+</details>
+
 Cool! Now we can try executing an operation with a `take` argument value outside the range!
 
 Execute the following query operation via GraphiQL:

website/src/pages/tutorial/basic/11-summary.mdx

@@ -2,7 +2,7 @@
 
 In this tutorial, you learned how to build a simple HackerNews clone GraphQL server from scratch using GraphQL Yoga!
 
-You can find the code of full [code of the tutorial on GitHub](https://github.com/dotansimha/graphql-yoga/tree/v2/examples/hackernews).
+You can find the code of full [code of the tutorial on GitHub](https://github.com/dotansimha/graphql-yoga/tree/v3/examples/hackernews).
 
 Congratulations on completing the tutorial! We can't wait to see what you build next.
 

website/src/pages/tutorial/basic/index.mdx

@@ -27,7 +27,7 @@ You are going to use the following technologies:
 
 <Callout>
   You can find the [code of the tutorial in this
-  repository](https://github.com/dotansimha/graphql-yoga/tree/v2/examples/hackernews).
+  repository](https://github.com/dotansimha/graphql-yoga/tree/v3/examples/hackernews).
 </Callout>
 
 ## What to Expect