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.

Shiny new logo thanks to Paweł Kosiec

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 schema types in 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, e.g.:

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 @MaxArraySize 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.

Work in progress

Currently released version is a MVP (Minimum Viable Product). It is well tested (95% coverage, 4400 lines of test code) and has 90% of the planned features already implemented. However there’s some work to be done before 1.0.0 release and it’s mostly about documentation (website, api reference and jsdoc).

There are also plans for more features like better TypeORM and dataloader integration or custom decorators 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.

The more feedback I receive, the more time I will devote to continue the development of TypeGraphQL!