TypeGraphQL

Create GraphQL resolvers and schemas with TypeScript, using classes and decorators!

Design Goals

We all love GraphQL but creating GraphQL API with TypeScript is a bit of pain. We have to mantain separate GQL schemas using SDL or JS API and keep the related TypeScript interfaces in sync with them. We also have separate ORM classes representing our db entities. This duplication is a really bad developer experience.

What if I told you that you can have only one source of truth thanks to a little addition of decorators magic? Interested? So take a look at the quick intro to TypeGraphQL!

Getting started

Let's start at the begining with an example. We have API for cooking recipes and we love using GraphQL for it. At first we will create the Recipe type, which is the foundations of our API:

@GraphQLObjectType()
class Recipe {
  @Field(type => ID)
  readonly id: string;

  @Field()
  title: string;

  @Field({ nullable: true })
  description?: string;

  @Field(type => Rate)
  ratings: Rate[];

  @Field({ nullable: true })
  averageRating?: number;
}

Take a look at the decorators:

• @GraphQLObjectType() marks the class as the object shape known from GraphQL SDL as type
• @Field() marks the property as the object's field - it is also used to collect type metadata from TypeScript reflection system
• the parameter function in decorator @Field(type => ID) is used to declare the GraphQL scalar type like the builit-in ID
• due to reflection limitation, optional (nullable) fields has to be annotated with { nullable: true } decorator param
• we also have to declare (type => Rate) because of limitation of type reflection - emited type of ratings property is Array, so we need to know what is the type of items in the array

This will generate GraphQL type corresponding to this:

type Recipe {
  id: ID!
  title: String!
  description: String
  ratings: [Rate]!
  averageRating: Float
}

Next, we need to define what is the Rate type:

@GraphQLObjectType()
class Rate {
  @Field(type => Int)
  value: number;

  @Field()
  date: Date;

  @Field()
  user: User;
}

Again, take a look at @Field(type => Int) decorator - Javascript doesn't have integers so we have to mark that our number type will be Int, not Float (which is number by default).

So, as we have the base of our recipe related types, let's create a resolver!

We will start by creating a class with apropiate decorator:

@GraphQLResolver(objectType => Recipe)
export class RecipeResolver {
  // we will implement this later
}

@GraphQLResolver marks our class as a resolver of type Recipe (type info is needed for attaching field resolver to correct type).

Now let's create our first query:

@GraphQLResolver(objectType => Recipe)
export class RecipeResolver {
  constructor(
    // declare to inject instance of our repository
    private readonly recipeRepository: Repository<Recipe>,
  ){}

  @Query(returnType => Recipe, { nullable: true })
  async recipe(@Args() { recipeId }: FindRecipeArgs): Promise<Recipe | undefined> {
    return this.recipeRepository.findOneById(recipeId);
  }

• our query needs to communicate with database, so we declare the repository in constructor and the DI framework will do the magic and injects the instance to our resolver
• @Query decorator marks the class method as the query (who would have thought?)
• our method is async, so we can't infer the return type from reflection system - we need to define it as (returnType => Recipe) and also mark it as nullable because findOneById might not return the recipe (no document with the id in DB)
• @Args() marks the parameter as query arguments object, where FindRecipeArgs define it's fields - this will be injected in this place to this method

So, how the FindRecipeArgs looks like?

@GraphQLArgumentType()
class FindRecipeArgs {
  @Field(type => ID)
  recipeId: string;
}

This two will generate corresponding graphql schema:

type Query {
  recipe(recipeId: ID!): Recipe
}

It is great, isn't it? 😃

Ok, let's add another query:

class RecipeResolver {
  // ...
  @Query(() => Recipe, { array: true })
  recipes(): Promise<Array<Recipe>> {
    return this.recipeRepository.find();
  }
}

As you can see, the function parameter name @Query(returnType => Recipe) is only the convention and if you want, you can use the shorthand syntax like @Query(() => Recipe) which might be quite less readable for someone. We need to declare it as a function to help resolve circular dependencies.

Also, remember to declare { array: true } when your method is async or returns the Promise<Array<T>>.

So now we have two queries in our schema:

type Query {
  recipe(recipeId: ID!): Recipe
  recipes: [Recipe]!
}

Now let's move to the mutations:

class RecipeResolver {
  // ...
  @Mutation(returnType => Recipe)
  async rate(
    @Arg("rate") rateInput: RateInput,
    @Context() { user }: Context,
  ) {
    // implementation...
  }
}

• we declare the method as mutation using the @Mutation() with return type function syntax
• the @Arg() decorator let's you declare single argument of the mutation
• for complex arguments you can use as input types like RateInput in this case
• injecting the context is also possible - using @Context() decorator, so you have an access to request or user data - whatever you define on server settings

Here's how RateInput type looks:

@GraphQLInputType()
class RateInput {
  @Field(type => ID)
  recipeId: string;

  @Field(type => Int)
  value: number;
}

@GraphQLInputType() marks the class as the input in SDL, in oposite to type or scalar

The corresponding GraphQL schema:

input RateInput {
  recipeId: ID!
  value: Int!
}

And the rate mutation definition:

type Mutation {
  rate(rate: RateInput!): Recipe!
}

The last one we discuss now is the field resolver. As we declared earlier, we store array of ratings in our recipe documents and we want to expose the average rating value.

So all we need is to decorate the method with @FieldResolver() and the method parameter with @Root() decorator with the root value type of Recipe - as simple as that!

class RecipeResolver {
  // ...
  @FieldResolver()
  averageRating(@Root() recipe: Recipe) {
    // implementation...
  }
}

The whole RecipeResolver we discussed above with sample implementation of methods looks like this:

@GraphQLResolver(objectType => Recipe)
export class RecipeResolver {
  constructor(
    // inject the repository (or other services)
    private readonly recipeRepository: Repository<Recipe>,
  ){}

  @Query(returnType => Recipe, { nullable: true })
  recipe(@Args() { recipeId }: FindRecipeParams) {
    return this.recipeRepository.findOneById(recipeId);
  }

  @Query(() => Recipe, { array: true })
  recipes(): Promise<Array<Recipe>> {
    return this.recipeRepository.find();
  }

  @Mutation(Recipe)
  async rate(
    @Arg("rate") rateInput: RateInput,
    @Context() { user }: Context,
  ) {
    // find the document
    const recipe = await this.recipeRepository.findOneById(rateInput.recipeId);
    if (!recipe) {
      throw new Error("Invalid recipe ID");
    }

    // update the document
    recipe.ratings.push({
      date: new Date(),
      value: rateInput.value,
      user,
    });

    // and save it
    return this.recipeRepository.save(recipe);
  }

  @FieldResolver()
  averageRating(@Root() recipe: Recipe) {
    const ratingsCount = recipe.ratings.length;
    const ratingsSum = recipe.ratings
      .map(rating => rating.value)
      .reduce((a, b) => a + b, 0);

    return ratingsCount ? ratingsSum / ratingsCount : null;
  }
}

Real life example

As I mentioned, in real life we want to reuse as much TypeScript definition as we can. So the GQL type classes would be also reused by ORM or validation lib:

import { Entity, ObjectIdColumn, Column, OneToMany, CreateDateColumn } from "typeorm";

@Entity()
@GraphQLObjectType()
export class Recipe {
  @ObjectIdColumn()
  @Field(type => ID)
  readonly id: ObjectId;

  @Column()
  @Field()
  title: string;

  @Column()
  @Field()
  description: string;

  @OneToMany(type => Rate, rate => rate.recipe)
  @Field(type => Rate)
  ratings: Rate[];

  // note that this field is not stored in DB
  @Field()
  averageRating: number;

  // and this one is not exposed by GraphQL
  @CreateDateColumn()
  creationDate: Date;
}

import { IsMongoId, Min, Max } from "class-validator";

@GraphQLInputType()
class RateInput {
  @IsMongoId()
  @Field(type => ID)
  recipeId: string;

  @Min(1)
  @Max(5)
  @Field(type => Int)
  value: number;
}

Of course TypeGraphQL will automatically validate the input and params with class-validator for you too!

More details about this feature here.

How to use

Installation

1. Install module:

npm i type-graphql

2. reflect-metadata shim is required:

npm i reflect-metadata

and make sure to import it on top of your entry file (before you use/import type-graphql or your resolvers):

import "reflect-metadata";

3. Its important to set these options in tsconfig.json file of your project:

{
  "emitDecoratorMetadata": true,
  "experimentalDecorators": true
}

Usage

All you need to do is to import your resolvers and register them in schema builder:

import "reflect-metadata"; // remember about this!
import { buildSchema } from "type-graphql";

import { SampleResolver } from "./resolvers";

const schema = buildSchema({
  resolvers: [SampleResolver],
});

And that's it! You can also create a HTTP-based GraphQL API server:

// remember to install "express" and "express-graphql" modules!
const app = express();
app.use(
  "/graphql",
  graphqlHTTP({
    schema, // this is our schema from TypeGraphQL
    graphiql: true,
  }),
);
app.listen(4000, () => {
  console.log("Running a GraphQL API server at localhost:4000/graphql");
});

Examples

You can also check the examples folder on the repo for more example of usage: simple fields resolvers, DI Container support, TypeORM integration, automatic validation, etc.

Please notice that, do tue a ts-node bug an additional parameter is needed when running with ts-node:

ts-node --type-check ./examples/01-simple-usage/index.ts

Tests folder will also give you some tips how to make some things done.

Work in progress

Currently released version is an early alpha. However it's working quite well, so please feel free to test it and experiment with it.

More feedback = less bugs thanks to you! 😃

Contribution

PRs are welcome, but first check, test and build your code before committing it.

• Use commit rules: For more information checkout this commit rule guide.
• Allowing changes to a pull request branch created from a fork

Roadmap

You can keep track of development's progress on project board.

Stay tuned and come back later for more! 😉