Skip to content
Create GraphQL schema and resolvers with TypeScript, using classes and decorators!
TypeScript JavaScript Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github chore(repo): create FUNDING.yml with Open Collective entry Sep 6, 2019
.vscode chore: configure vscode to debug single test May 4, 2019
docs Update all urls and mentions of old github account name Sep 8, 2019
examples docs(examples): update deps and code of apollo-client example Sep 8, 2019
img docs(readme): add Redo to sponsors section Sep 14, 2019
src feat(omit-types): add support for emiting only explicit types Sep 7, 2019
tests feat(omit-types): add support for emiting only explicit types Sep 7, 2019
website docs(website): add Redo to sponsors section Sep 14, 2019
.editorconfig chore: add editor config file Feb 17, 2018
.gitignore docs(examples): create Apollo client state example Apr 6, 2019
.prettierrc chore(format): update prettier and tslint settings Apr 14, 2018
.travis.yml chore: drop support for Node.js v6 Mar 10, 2019
CHANGELOG.md Update all urls and mentions of old github account name Sep 8, 2019
LICENSE Initial commit Jan 9, 2018
README.md docs(readme): add Redo to sponsors section Sep 14, 2019
dev.js docs(examples): add custom decorators to middlewares example May 6, 2019
gulpfile.ts chore: fix gulp config and others after deps update Feb 21, 2019
jest.config.js chore(jest): add tdd task for vscode Feb 9, 2019
package-lock.json chore(deps): update deps and fix examples types Sep 8, 2019
package.json Update all urls and mentions of old github account name Sep 8, 2019
publish-website.sh docs(website): Configure website autodeploy Apr 5, 2018
tsconfig.json docs(examples): create Apollo client state example Apr 6, 2019
tsconfig.package.json chore: update dev deps and fix issues with new gulp Feb 21, 2019
tslint.json docs(examples): add Typegoose integration example Mar 24, 2019

README.md

logo

TypeGraphQL

npm version Build Status codecov dependencies install size gitter

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

https://typegraphql.ml/

Motivation

We all know that GraphQL is great and solves many problems we have with REST APIs, like overfetching and underfetching. But developing a GraphQL API in Node.js with TypeScript is sometimes a bit of a pain. Why? Let's take a look at the steps we usually have to take.

First, we create all the GraphQL types in schema.gql using SDL. Then we create our data models using ORM classes, which represent 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:

export const getRecipesResolver: GraphQLFieldResolver<void, Context, GetRecipesArgs> =
  async (_, args, ctx) => {
    // common tasks repeatable for almost every resolver
    const repository = TypeORM.getRepository(Recipe);
    const auth = Container.get(AuthService);
    await joi.validate(getRecipesSchema, args);
    if (!auth.check(ctx.user)) {
      throw new NotAuthorizedError();
    }

    // our business logic, e.g.:
    return repository.find({ skip: args.offset, take: args.limit });
  };

The biggest problem is redundancy in our codebase, which makes it difficult to keep things in sync. To add a new field to our entity, we have to jump through all the files - modify an entity class, the schema, as well as the interface. The same goes for 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.

Tools like GraphQL Code Generator or graphqlgen only solve the first part - they generate the corresponding interfaces (and resolvers skeletons) for our GraphQL schema but they don't fix the schema <--> models redundancy and developer experience (F2 rename won't work, you have to remember about the codegen watch task in background, etc.), as well as common tasks like validation, authorization, etc.

TypeGraphQL comes to address these issues, based on experience from a few years of developing GraphQL APIs in TypeScript. The main idea is to have only one source of truth by defining the schema using classes and some help from decorators. Additional features like dependency injection, validation and auth guards help with common tasks that normally we would have to handle ourselves.

Introduction

As mentioned, TypeGraphQL makes developing GraphQL APIs an enjoyable process, i.e. by defining the schema using only classes and a bit of decorator magic.

So, to create types like object type or input type, we use a kind of DTO classes. For example, to declare Recipe type we simply create a class and annotate it with decorators:

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

  @Field()
  title: string;

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

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

And we get the corresponding part of the schema in SDL:

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

Then we can create queries, mutations and field resolvers. For this purpose we use controller-like classes that are called "resolvers" by convention. We can also use awesome features like dependency injection and auth guards:

@Resolver(Recipe)
class RecipeResolver {
  // dependency injection
  constructor(private recipeService: RecipeService) {}

  @Query(returns => [Recipe])
  recipes() {
    return this.recipeService.findAll();
  }

  @Mutation()
  @Authorized(Roles.Admin) // auth guard
  removeRecipe(@Arg("id") id: string): boolean {
    return this.recipeService.removeById(id);
  }

  @FieldResolver()
  averageRating(@Root() recipe: Recipe) {
    return recipe.ratings.reduce((a, b) => a + b, 0) / recipe.ratings.length;
  }
}

And in this simple way we get this part of the schema in SDL:

type Query {
  recipes: [Recipe!]!
}

type Mutation {
  removeRecipe(id: String!): Boolean!
}

Getting started

A full getting started guide with a simple walkthrough (tutorial) can be found at getting started docs.

Video tutorial

If you prefer video tutorials, you can watch Ben Awad's TypeGraphQL video series on YouTube.

Documentation

The documentation, installation guide, detailed description of the API and all of its features is available on the website.

Examples

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

The Tests folder might also give you some tips how to get various things done.

Towards v1.0

The 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 still work to be done before the 1.0.0 release and it's mostly about documentation (website, api reference and jsdoc) and compatibility with the GraphQL spec and other tools.

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

I encourage you to give TypeGraphQL a try and experiment with. If you have any questions, you can ask on gitter. If you find a bug, please report it as an issue on GitHub. If you have any interesting feature requests, I would be happy to hear about them.

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.

Gold Sponsors 🏆

Please ask your company to also support this open source project by becoming a gold sponsor and getting your company logo on our README on Github as well as on the landing page of the official documentation site with a link to your company site.

Sponsors 🚀

Become a Sponsor

Gorrion Software House Demid Nikitin Redo

Backers ☕ and Members 💪

Contribution

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

If you want to add a new big feature, please create a proposal first, where we can discuss the idea and implementation details. This will prevent wasted time if the PR be rejected.

You can’t perform that action at this time.