type-graphql

What is type-graphql?

type-graphql is a library that allows you to create GraphQL APIs using TypeScript. It leverages TypeScript's type system to define the schema and resolvers, making it easier to maintain and understand. The library provides decorators and other utilities to simplify the creation of GraphQL schemas and resolvers.

What are type-graphql's main functionalities?

Schema Definition

This feature allows you to define your GraphQL schema using TypeScript classes and decorators. The example demonstrates how to create a simple object type and a resolver with a query.

const { buildSchema } = require('type-graphql');
const { Resolver, Query, ObjectType, Field } = require('type-graphql');

@ObjectType()
class SampleObject {
  @Field()
  id: number;

  @Field()
  name: string;
}

@Resolver()
class SampleResolver {
  @Query(() => SampleObject)
  sampleQuery() {
    return { id: 1, name: 'Sample' };
  }
}

async function main() {
  const schema = await buildSchema({
    resolvers: [SampleResolver],
  });
  // Use the schema in your GraphQL server setup
}
main();

Resolvers

Resolvers are used to handle the logic for fetching and manipulating data. This example shows how to create a resolver with a query to get users and a mutation to add a user.

const { Resolver, Query, Arg, Mutation } = require('type-graphql');

@Resolver()
class UserResolver {
  private users = [];

  @Query(() => [String])
  getUsers() {
    return this.users;
  }

  @Mutation(() => String)
  addUser(@Arg('name') name: string) {
    this.users.push(name);
    return name;
  }
}

async function main() {
  const schema = await buildSchema({
    resolvers: [UserResolver],
  });
  // Use the schema in your GraphQL server setup
}
main();

Custom Scalars

Custom scalars allow you to define custom data types in your GraphQL schema. This example demonstrates how to create a custom scalar for handling Date objects.

const { Scalar, CustomScalar } = require('type-graphql');
const { GraphQLScalarType, Kind } = require('graphql');

@Scalar('Date')
class DateScalar implements CustomScalar<string, Date> {
  description = 'Date custom scalar type';

  parseValue(value: string): Date {
    return new Date(value); // value from the client input variables
  }

  serialize(value: Date): string {
    return value.toISOString(); // value sent to the client
  }

  parseLiteral(ast: any): Date {
    if (ast.kind === Kind.STRING) {
      return new Date(ast.value); // value from the client query
    }
    return null;
  }
}

async function main() {
  const schema = await buildSchema({
    resolvers: [],
    scalarsMap: [{ type: Date, scalar: DateScalar }],
  });
  // Use the schema in your GraphQL server setup
}
main();

Other packages similar to type-graphql

apollo-server

Apollo Server is a community-driven, open-source GraphQL server that works with any GraphQL schema built with GraphQL.js. It provides a more flexible and powerful way to build GraphQL APIs but does not integrate TypeScript as tightly as type-graphql.

graphql-tools

graphql-tools is a set of utilities from Apollo that helps you create and manipulate GraphQL schemas in a more flexible way. It allows you to build schemas using a schema-first approach, but it does not provide the same level of TypeScript integration as type-graphql.

nexus

Nexus is a code-first GraphQL schema construction library for TypeScript & JavaScript. It provides a similar experience to type-graphql but with a different API and philosophy. Nexus focuses on a more functional approach compared to the decorator-based approach of type-graphql.

README

TypeGraphQL

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

https://19majkel94.github.io/type-graphql/

Motivation

We all know that GraphQL is 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. 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.:

export const recipesResolver: GraphQLFieldResolver<void, Context, RecipesArgs> =
  async (_, args) => {
    // our business logic, e.g.:
    const repository = getRepository(Recipe);
    return repository.find();
  }

The biggest problem is the 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 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 decorator help. Additional features like dependency injection, validation or auth guards helps with common tasks that normally we would have to handle by ourselves.

Introduction

As I mentioned, TypeGraphQL makes developing a GraphQL API and 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 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 corresponding part of 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 or auth guards:

@Resolver(Recipe)
class RecipeResolver {
  constructor(
    private recipeService: RecipeService,
  ) {}

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

  @Mutation()
  @Authorized(Roles.Admin)
  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 schema in SDL:

type Query {
  recipes: [Recipe!]!
}
type Mutation {
  removeRecipe(id: String!): Boolean!
}

Getting started

Full getting started guide with a simple walkthrough/tutorial can be found in getting started docs.

Documentation

The documentation with detailed description of the API and the features is available on the website.

Below you can find installation instructions that are also important.

How to use

Installation

1. Install module:

npm i type-graphql

1. 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";

TypeScript configuration

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

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

1. TypeGraphQL is designed to work with Node.js 6, 8 and latest stable. It uses features from ES7 (ES2016) so you should set your tsconfig.json appropriately:

{
  "target": "es2016" // or newer if your node.js version supports this
}

1. Due to using graphql-subscription dependency that rely on an AsyncIterator, you may also have to provide the esnext.asynciterable to the lib option:

{
  "lib": ["es2016", "esnext.asynciterable"]
}

All in all, the minimal tsconfig.json file example looks like this:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "lib": ["es2016", "esnext.asynciterable"],
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

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 due to a ts-node bug, an additional parameter is needed when running with ts-node:

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

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

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 do 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 middlewares and 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.

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

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

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 wasting of your time if the PR be rejected.

Changelog

v0.13.1

Fixes

• fix missing loosely typed overload signature for createUnionType (remove the 10 types limit)