GraphQL + TypeScript = TypeGraphQL
We all love GraphQL! It’s so great and solves many problems that we have with REST API, like overfetching and underfetching. But developing a GraphQL API in Node.js with TypeScript is sometimes a bit of pain.
TypeGraphQL makes that process enjoyable, i.a. by defining the schema using only classes and a bit of decorators magic.
Motivation
As I mentioned, developing a GraphQL API in Node.js with TypeScript might be a painful process. Why? Let’s take a look at the steps we usually have to make.
At first, we create the all the GraphQL types in schema.gql file using SDL. We also create our data models using ORM classes, which represents our db entities. Then we start to write resolvers for our queries, mutations and fields, but this forces us to first create TS interfaces for all arguments, inputs, and even object types.
Only then can we actually implement the resolvers using weird generic signatures and manually performing common tasks, like validation, authorization and loading dependencies:
The biggest problem is the redundancy in our codebase, which makes difficult to keep this things in sync. To add a new field to our entity, we have to jump through all the files — modify an entity class, then modify part of the schema , as well as the interface. The same goes with inputs or arguments. It’s easy to forget to update one piece or make a mistake with a single type. Also, what if we’ve made a typo in field name? The rename feature (F2) won’t work correctly.
TypeGraphQL comes to address this issues, based on experience from over a dozen months of developing GraphQL APIs in TypeScript. The main idea is to have only one source of truth by defining the schema using classes and a bit of decorators help. Additional features like dependency injection, validation or auth guards helps with common tasks that normally we would have to handle by ourselves.
Getting started
To explore all powerful capabilities of TypeGraphQL, we will create a sample GraphQL API for cooking recipes.
Let’s start with the Recipe type, which is the foundations of our API.
We want to get equivalent of this type described in SDL:
So we create the Recipe class with all properties and types:
Then we annotate the class and its properties with decorators:
The detailed rules when to use nullable, [] and other options are described in fields and types docs.
Resolvers
After that we want to create typical crud queries and mutation. To do that we create the resolver (controller) class that will have injected RecipeService in constructor:
We use @Authorized() decorator to restrict access only for authorized users or the one that fulfill the roles requirements. The detailed rules when and why we declare returns => Recipe functions and others are described in resolvers docs.
Inputs and arguments
Ok, but what are theNewRecipeInput and RecipesArgs? There are of course classes that declares input type and arguments:
@Length, @Min or @ArrayMaxSize are decorators from class-validator that automatically perform fields validation in TypeGraphQL.
Building schema
The last step that we have to do is to actually build the schema from TypeGraphQL definition. We use buildSchema function for this:
Et voilà! Now we have fully working GraphQL schema! If we print it, we would receive exactly this:
Want more?
That was only a tip of the iceberg — a very simple example with basic GraphQL types. Do you use interfaces, enums, unions and custom scalars? That’s great because TypeGraphQL fully supports them too!
If you want to see how it looks in more complicated case, you can go to the Examples section where you can find how nice TypeGraphQL integrates with TypeORM. Want to learn about more advanced concepts like authorization checker, inheritance support, field resolvers or middlewares? Check out the Docs section.
Towards v1.0
TypeGraphQL 1.0 has been released in 2020:
https://dev.to/michallytek/announcing-typegraphql-1-0-1d7h
The following section is for archival reference from 2018.
Currently released version is a MVP (Minimum Viable Product). It is well tested (96% coverage, 8000 lines of test code) and has 95% of the planned features already implemented.
However there’s some work to do before 1.0.0 release and it’s mostly about documentation (website, api reference and jsdoc) and compatibility with GraphQL spec or other tools.
There are also plans for more features like better TypeORM, Prisma and dataloader integration or custom decorators and metadata annotations support — the full list of ideas is available on the GitHub repo. You can also keep track of development’s progress on project board.
Spread the word
I strongly encourage you to give it a try and experiment with TypeGraphQL.
I promise, it will reduce your codebase by a half or more!
If you find this framework interesting, please star the GitHub repository, clap for this article and share it on your social media, if you don’t mind.
Support
TypeGraphQL is an MIT-licensed open source project. This framework is a result of the tremendous amount of work — sleepless nights, busy evenings and weekends.
It doesn’t have a large company that sits behind — its ongoing development is possible only thanks to the support by the community.
