Fullstack GraphQL The Complete Guide to Writing GraphQL Servers and Clients with TypeScript (Gaetano Checinskil Roy Derks (ed) Nate Murray) (Z-Library)

📄 File Format: PDF

💾 File Size: 7.0 MB

📖 Read Online ⬇️ Download

Registered users can read the full content for free

Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.

📄 Page 1

(This page has no text content)

📄 Page 2

Fullstack GraphQL The Complete Guide to Building GraphQL Clients and Servers Written by Gaetano Checinski and Roy Derks Edited by Nate Murray © 2020 newline All rights reserved. No portion of the book manuscript may be reproduced, stored in a retrieval system, or transmitted in any form or by any means beyond the number of purchased copies, except for a single backup or archival copy. The code may be used freely in your projects, commercial or otherwise. The authors and publisher have taken care in preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damagers in connection with or arising out of the use of the information or programs container herein. Published by newline

📄 Page 3

Contents What to Expect from this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 What is GraphQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Why GraphQL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Usage driven and Intuitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Self-descriptive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Other advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Join Our Discord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Hello GraphQL - GraphiQL and Github’s GraphQL Playground . . . . . . . 11 Enter GraphiQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Our First Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Named Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Multiple Queries and Renaming Result fields . . . . . . . . . . . . . . . . . . 24 Fragments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Union Types and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Mutations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 GraphQL queries over HTTP - fetching with fetch and curl . . . . . . . . 37 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Hello GraphQL from Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 A GraphQL Hello World from Node . . . . . . . . . . . . . . . . . . . . . . . 39 Making Changes with Mutations . . . . . . . . . . . . . . . . . . . . . . . . . 41

📄 Page 4

CONTENTS Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Hello GraphQL in the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 A GraphQL Hello World from Localhost . . . . . . . . . . . . . . . . . . . . 43 Putting the Query in the App . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Creating a Custom Hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Making Updates with Mutations . . . . . . . . . . . . . . . . . . . . . . . . . 49 Handling User Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Picking a GraphQL Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 GraphQL is just JSON over HTTP (well, usually) . . . . . . . . . . . . . . . 54 Why You Might Want a Dedicated GraphQL Client . . . . . . . . . . . . . . 55 So What Are The Options? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 graphql-request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 urql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Relay Modern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Apollo Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 What to Choose? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 The Basics of Apollo Client and React . . . . . . . . . . . . . . . . . . . . . . . . 62 Apollo Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Getting Hooked on useQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Getting hooked on useMutation . . . . . . . . . . . . . . . . . . . . . . . . . . 66 How to use Apollo Client across your app . . . . . . . . . . . . . . . . . . . . 67 ApolloClient and Testing Components . . . . . . . . . . . . . . . . . . . . . . 67 Remember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Building a TypeSafe GraphQL React Client App - Part 1 . . . . . . . . . . . . 72 What are we building? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Tooling and Project Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 TypeScript and GraphQL Types - There is a difference . . . . . . . . . . . . 75 Generating Types with graphql-codegen . . . . . . . . . . . . . . . . . . . . . 76 Generating Types for Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Generating Helper Functions for Apollo . . . . . . . . . . . . . . . . . . . . . 79 Building the Issue Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Creating the Search Component . . . . . . . . . . . . . . . . . . . . . . . . . . 83

📄 Page 5

CONTENTS Visualizing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Pagination with cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Tracking our cursorState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Building a TypeSafe GraphQL React Client App - Part 2 . . . . . . . . . . . . 93 What are we building? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Loading Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Mutations - Modifying Existing Data . . . . . . . . . . . . . . . . . . . . . . . 103 Mutations - Creating New Data . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Refetching Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Manually Updating the Apollo Cache . . . . . . . . . . . . . . . . . . . . . . 110 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 What’s Next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Your First GraphQL Server with Apollo Server . . . . . . . . . . . . . . . . . . 115 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 The Obligatory Boilerplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Mocking the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Resolvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Chaining Resolvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Passing Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Using GraphQL Servers with A Database . . . . . . . . . . . . . . . . . . . . . 137 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Using GraphQL with a Database . . . . . . . . . . . . . . . . . . . . . . . . . 138 Queries with pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Writing Mutation Resolvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Caching and Batching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Optimized queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

📄 Page 6

CONTENTS Batching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Cost computation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Authentication and Authorization in GraphQL . . . . . . . . . . . . . . . . . . 178 JWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Resolver Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Context Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Schema Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Code First GraphQL with TypeORM and TypeGraphQL . . . . . . . . . . . . 205 TypeGraphQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Implementing Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Using Context in a Resolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 TypeORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Authorization with TypeGraphQL . . . . . . . . . . . . . . . . . . . . . . . . 221 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 More on TypeGraphQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Where to Go From Here? Advanced GraphQL . . . . . . . . . . . . . . . . . . 224 What did you think? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Awesome GraphQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Say Hello . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

📄 Page 7

What to Expect from this book Fullstack GraphQL will give you a use-case driven, hands-on introduction to the GraphQL ecosystem. This book intends to present GraphQL to you in a problem- oriented and pragmatic fashion - and ultimately give you the confidence to use GraphQL in your everyday full-stack challenges. This book shows both theoretical and conceptual aspects of GraphQL, including code examples book using React, Node.js, and Typescript to showcase how to use GraphQL to generate and render data. The structure of this book is loosely inspired by the workflow of a Fullstack Engineer and will reveal GraphQL specific concepts through the life-cycle of a real-world app. GraphQL is an opinionated query language, with an ecosystem that will change the way you write frontend and backend solutions.

📄 Page 8

Motivation What is GraphQL “A query language for your API” - The GraphQL Foundation GraphQL is a specification to query APIs, and provides a server-side runtime to execute those queries using a strongly typed system based on your data. Based on the data model, GraphQL can return you the data in exactly the same format as you request it in. It can be used language and framework agnostic, and connected to any database or storage engine. In 2015 the specification for GraphQL was first publicly shared with the world by Facebook, after it was developed internally. To guarantee the continuation of GraphQL by the community, the project was moved into the GraphQL Foundation in 2019. Why GraphQL? Before we present you the problems that inspired the creation of GraphQL, let us have a look at this famous quote: “A language that doesn’t affect the way you think about programming, is not worth knowing.” - Alan Perlis GraphQL changed the way how data was transferred between applications in a fixed format, to a new approach to dynamically transfer data between a “frontend” and a “backend”. This allowed Facebook to tackle many problems with data fetching for mobile applications, without having to create a new REST API for every application.

📄 Page 9

Motivation 3 As you will work through this book, we hope you won’t just add GraphQL to your toolbox, but also develop a new way of thinking about data models, APIs and full- stack development. The ecosystem surrounding GraphQL gives you the tools to start building and querying APIs, that are: Usage Driven It encourages users to define queries that specify what data to fetch in a granular way. Intuitive GraphQL delivers you only the data that you request, in the exact same format that you requested it in Self-descriptive GraphQLs schemas are strongly typed and define a strict contract between a query and its response. It makes GraphQL responses very predictable and also suitable for documentation. GraphQL embodies many lessons learned from API design that enforces several best practices into one solution. As engineers, we’re facing the challenge of not just building systems, but also evolving these systems to fit new requirements. Usage driven and Intuitive REST APIs were designed with specific use-cases in mind, making the development of “backend” and “frontend” loosely coupled or even independent. The design of a REST API is often directly linked to the data model of the database that it’s reading and mutating, making it a mere abstraction layer over this database.

📄 Page 10

Motivation 4 In this example, we see a wire-frame of posts, how the underlying REST API, and a direct comparison with GraphQL. When the RESTAPI was created to serve the UI of a specific frontend application, the design of the REST API (and consequentially the data model of the database) should always match that UI. When the UI changes, the data flow and the data model of that database no longer match. This can lead to a problem that often arises when you’re used to working with REST APIs, that is called the n+1 problem. If you need to querymultiple endpoints to collect enough data to render a page, then you are already facing the n+1 problem. The n+1 problem This problem describes the cascade of independent requests triggered by the lack of data in one response. For the Developer Experience (DX) and performance reasons, it’s therefore often desirable to fetch all of the data we need in one HTTP request to serve the UI. However, as your application grows in size, you find that you often end up creating a unique REST endpoint for every change in either the UI or the data model of the database. For example, you created an endpoint that returns user information. This information was at first used to display a profile page but is also used to display a short overview of a user profile. Even later, you even use this information to display the user’s avatar somewhere else. This raises the following questions: 1) Should the backend grow with the require- ments of each of it’s clients? 2) Should the backend endpoints be changed as the client’s requirements change? 3) Should the backend endpoints take configuration parameters to suit every client? As we think through each of those options, we will notice that they all have their pros and cons. Building a custom endpoint for a specific client allows you to fine-tune the backend for maximal performance. However, this will increase the number of endpoints to maintain.

📄 Page 11

Motivation 5 Constantly adapting one endpoint to fit new requirements won’t suffer the same issue but it will introduce a host of other questions: - How do we migrate old clients to the newer version? - Will we need to support both versions? The last option combines the best of both worlds but introduces a level of indirection and requires a custom implementation. GraphQL implements and standardizes this approach, as you’ll discover in the first chapters of this book. As you see, in GraphQL there is not only an intuitive mapping between queries and data but also it encodes the domain-specific language of your application. Self-descriptive REST is very minimalistic and does not enforce any types or schemas, and as a result, validation of input and output and documentation are complementary aspects of a REST API. Consequently, validation and documentation is a maintenance burden. That is a potential source of bugs if the proper discipline isn’t exhibited at all times. GraphQL has been designed with this in mind, leading to a more robust API and less overhead for developers. All this is based on a GraphQL schema, a strongly typed and object-orientated representation of the data model for the application. The schema is used to both validate the requests and statically check the types of the operations and responses. Being schema-driven also has an interesting side-effect, as the schema is always tied to the operations and responses and as a result, the schema is never out of date. We can always generate up-to-date documentation. Other advantages GraphQL provides many other advantages over a “traditional” approach for handling data flows between applications, as you’ll discover in this book

📄 Page 12

Motivation 6 Prerequisites In this book we assumed that you have at least the following skills: • basic JavaScript knowledge (working with functions, objects, and arrays) • a basic React understanding (at least general idea of component based approach) • some command line skill (you know how to run a command in terminal) Here we mostly focus on specifics of using GraphQL with Node.js, TypeScript, and React. The instructions we give in this book are very detailed, so if you lack some of the listed skills - you can still follow along with the tutorials and be just fine. Running Code Examples Each section has an example app shipped with it. You can download code examples from the same place where you purchased this book. If you have any trouble finding or downloading the code examples, email us at us@fullstack.io¹. In the beginning of each section you will find instructions of how to run the example app. In order to run the examples you need a terminal app and NodeJS installed on your machine. Make sure you have NodeJS installed. Run node -v, it should output your current NodeJS version: $ node -v v10.19.0 Anything between Node 10 through 14+ should be fine. Here are instructions for installing NodeJS on different systems: ¹mailto:us@fullstack.io

📄 Page 13

Motivation 7 Windows To work with examples in this book we recommend installing Cmder² as a terminal application. We recommend installing node using nvm-windows³. Follow the installation instruc- tions on the Github page. Then run nvm to get the latest LTS version of NodeJS: nvm install --lts It will install the latest available LTS version. Mac Mac OS has a Terminal app installed by default. To launch it toggle Spotlight, search for terminal and press Enter. Run the following command to install nvm⁴: curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/inst\ all.sh | bash Then run nvm to get the latest LTS version of NodeJS: nvm install --lts This command will also set the latest LTS version as default, so you should be all set. If you face any issues follow the troubleshooting guide for Mac OS⁵. Linux Most Linux distributions come with some terminal app provided by default. If you use Linux - you probably know how to launch terminal app. Run the following command to install nvm⁶: ²https://cmder.net/ ³https://github.com/coreybutler/nvm-windows ⁴https://github.com/nvm-sh/nvm ⁵https://github.com/nvm-sh/nvm#troubleshooting-on-macos ⁶https://github.com/nvm-sh/nvm

📄 Page 14

Motivation 8 curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/inst\ all.sh | bash Then run nvm to get the latest LTS version of NodeJS: nvm install --lts In case of problems with installation follow the troubleshooting guide for Linux⁷. Code Blocks And Context Code Block Numbering In this book, we build example applications in steps. Every time we achieve a runnable state - we put it in a separate step folder. 1 01-first-app/ 2 ├── step1 3 ├── step2 4 ├── step3 5 ... // other steps If at some point in the chapter we achieve the state that we can run - we will tell you how to run the version of the app from the particular step. Some files in that folders can have numbered suffixes with *.example word in the end: 1 src/AddNewItem0.tsx.example If you see this - it means that we are building up to something bigger. You can jump to the file with same name but without suffix to see a completed version of it. Here the completed file would be src/AddNewItem.tsx. ⁷https://github.com/nvm-sh/nvm#troubleshooting-on-linux

📄 Page 15

Motivation 9 Reporting Issues We’ve done our best to make sure that our instructions are correct and code samples don’t contain errors. There is still a chance that you will encounter problems. If you find a place where a concept isn’t clear or you find an inaccuracy in our explanations or a bug in our code, you should leave a comment inline on newline.co. If you are reading this via PDF, did you know you can read all of newline’s books online? You can either sync your purchases from your Gumroad account or read them via newline Pro⁸ You can also try emailing us⁹ In either case, we want to make sure that our book is precise and clear. Getting Help If you have any problems working through the code examples in this book, you should try: • leaving a comment • joining our Discord and asking or • send us an email. To make it easier for us to help you include the following information: • What revision of the book are you referring to? • What operating system are you on? (e.g. Mac OS X 10.13.2, Windows 95) • Which chapter and which example project are you on? • What were you trying to accomplish? • What have you tried already? • What output did you expect? • What actually happened? (Including relevant log output.) Ideally also provide a link to a git repository where we can reproduce an issue you are having. ⁸https://newline.co/pricing ⁹mailto:us@newline.co

📄 Page 16

Motivation 10 Join Our Discord We have a community Discord which you can join here¹⁰ and join the #graphql channel ¹⁰https://newline.co/discord

📄 Page 17

Hello GraphQL - GraphiQL and Github’s GraphQL Playground In this chapter, we will be getting familiar with GraphQL by using Github’s GraphQL explorer. To get the most out of this chapter, we suggest you head over to The Github API Explorer¹¹ and follow along. Below, we’ll present code examples will guide you through GraphQL’s intuitive, rich query language. After this chapter you will be able to: • Understand GraphQL schemas • Read and write GraphQL Queries • Explore APIs using the GraphQL Playground • Send queries using fetch and curl Enter GraphiQL Once you navigate to The Github API Explorer and Sign-In you’ll be welcomed with the online IDE that looks like this: ¹¹https://developer.github.com/v4/explorer/

📄 Page 18

Hello GraphQL - GraphiQL and Github’s GraphQL Playground 12 This is one of the most useful developer tools GraphQL offers and is known as GraphiQL - notice the i in the middle of that previous word. It stands for “interactive” and it’s the GraphQL explorer. It’s your first stop when developing and exploring any GraphQL endpoint. GraphiQL provides an IDE experience with autocompletion, documentation and a simple query editor. 1. it syntax checks your queries 2. you can run queries and see the results 3. you can explore the types as you work The documentation for exploring the types might be a little intimidating at first, but don’t worry, we’ll walk through how to make sense of it.

📄 Page 19

Hello GraphQL - GraphiQL and Github’s GraphQL Playground 13 Our First Query GraphQL queries look a little like JSON, here’s our first query: query { viewer { login } } Above you’ll see this isn’t quite JSON though, we don’t have any values! (Only keys). The response, however is in JSON. Let’s take a look: Here’s the response for our query above: { "data": { "viewer": { "login": "nikhedonia", } } } Notice that the shape of our request matches the shape of our response. AndGraphQL fills in the values for the keys that we requested. This shape-matching is a powerful feature of GraphQL. But another powerful feature of GraphQL is it’s type system. Let’s investigate what a viewer is and open the Documentation by hitting the “Docs” button on the right-hand side.

📄 Page 20

Hello GraphQL - GraphiQL and Github’s GraphQL Playground 14 In GraphQL every field has a type associated and can be inspected in GraphiQL by clicking on it. If you click on “Query” then you’ll see all available fields that you can query - and among them you’ll find viewer: User! In English this means “the field viewer returns a User” and the exclamation mark means it will never return null. The field user on the other hand is a function that takes a login of type string and returns a User but may return null if the User doesn’t exist. I think this is a noteworthy language choice: all field declarations are considered optional by default. The documentation is generated directly from the schema. The GraphQL schema roughly looks like this: