npm package: @scope3/type-graphql
Description: Create GraphQL schema and resolvers with TypeScript, using classes and decorators!
Author: Michał Lytek
Latest version: 2.0.0

<!-- prettier-ignore-start -->
<!-- markdownlint-disable-next-line MD041 -->
![logo](./images/logo.png)
<!-- prettier-ignore-end -->

---

## Performance-Optimized Fork by [Scope3](https://scope3.com/home)

> **Context**: This is a high-performance fork maintained by [Scope3](https://github.com/scope3data) with significant optimization improvements. Our changes have been submitted as [PR #1779](https://github.com/MichalLytek/type-graphql/pull/1779) to the original repository but remain unmerged after 6+ months.

### Performance Improvements

#### What’s Different in the Scope3 Fork?

This fork introduces a major refactor of the TypeGraphQL metadata build process, focused on dramatically improving performance for large schemas. It works very well! Scope3 has been running this fork in production for over 6 months, dropping our schema generation time from 4-5 minutes to under 10 seconds in our K8s deployments.

**Problem:**  
Schema generation in the upstream project was exponentially slow for large schemas, taking 30+ seconds with 3k-15k metadata objects due to repeated O(n) array `.filter()` lookups.

**Scope3 Solution:**  
We replaced all repeated array lookups with O(1) HashMap-based caching.

- Added cache initialization for all major metadata types (object types, fields, params, middlewares, directives, resolver classes, etc.).
- All metadata lookups now use these caches instead of array `.filter()` calls.
- Refactored resolver and field metadata construction to leverage these caches.

**Technical Details:**

- Introduced `Map` caches for object types, fields, params, middlewares, directives, and resolver classes.
- Added an `initCache()` method to populate these caches before schema building.
- All metadata construction logic now uses these caches for instant lookup.

**Performance Impact:**

- Schema generation time reduced from tens of seconds to milliseconds for large schemas.
- Example:
  - `buildClassMetadata`: 31.3s → 268ms (116x faster)
  - `buildFieldResolverMetadata`: 314ms → 39ms (8x faster)
  - `buildResolversMetadata`: 1.4s → 126ms (11x faster)

**Compatibility:**

- The fork remains 100% backward compatible with the original TypeGraphQL API.
- All original TypeGraphQL tests pass with these changes.
- Scope3 has been running this fork in production for over 6 months.
- All recent upstream changes are documentation-only (sponsor updates).

---

If you want more technical details or code samples, see the source or reach out to Scope3!

### Installation

```bash
# Install with npm
npm install @scope3/type-graphql

# Install with Yarn
yarn add @scope3/type-graphql

# Install with PNPM
pnpm add @scope3/type-graphql
```

### What's Coming

- Prisma 6 support – Upgrading to the latest Prisma version
- GraphQL 16.11 – Latest GraphQL version with improved performance and features

### Compatibility

100% backward compatible – drop-in replacement for the original `type-graphql` package.

#### Setting up Import Aliases for Drop-in Compatibility

To seamlessly migrate existing code without changing import statements throughout your codebase, you can set up a path alias in your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "paths": {
      "type-graphql": ["@scope3/type-graphql"]
    }
  }
}
```

This allows you to continue using:

```typescript
import { Resolver, Query, Field, ObjectType } from "type-graphql";
```

Instead of having to update all imports to:

```typescript
import { Resolver, Query, Field, ObjectType } from "@scope3/type-graphql";
```

**Note:** Make sure the `baseUrl` is set in your `tsconfig.json` for path mapping to work properly:

```json
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "type-graphql": ["@scope3/type-graphql"]
    }
  }
}
```

---

# TypeGraphQL

[![release](https://github.com/MichalLytek/type-graphql/actions/workflows/release.yml/badge.svg)](https://github.com/MichalLytek/type-graphql/actions/workflows/release.yml)
[![website](https://github.com/MichalLytek/type-graphql/actions/workflows/website.yml/badge.svg)](https://github.com/MichalLytek/type-graphql/actions/workflows/website.yml)
[![codeql](https://github.com/MichalLytek/type-graphql/actions/workflows/codeql.yml/badge.svg)](https://github.com/MichalLytek/type-graphql/actions/workflows/codeql.yml)
[![discord](https://img.shields.io/discord/1195751245386875040?logo=discord&color=%237289da)](https://discord.gg/cWnBAQcbg2)
[![codecov](https://codecov.io/gh/MichalLytek/type-graphql/branch/master/graph/badge.svg)](https://codecov.io/gh/MichalLytek/type-graphql)
[![npm](https://img.shields.io/npm/v/type-graphql?logo=npm&color=%23CC3534)](https://www.npmjs.com/package/type-graphql)
[![open collective](https://opencollective.com/typegraphql/tiers/badge.svg)](https://opencollective.com/typegraphql)

Create [GraphQL](https://graphql.org) schema and resolvers with [TypeScript](https://www.typescriptlang.org), using classes and decorators!

**<https://typegraphql.com>**

[![donate](https://opencollective.com/typegraphql/donate/button.png?color=black)](https://opencollective.com/typegraphql)

## Introduction

**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 class.
For example, to declare `Recipe` type we simply create a class and annotate it with decorators:

```ts
@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:

```graphql
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:

```ts
@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:

```graphql
type Query {
  recipes: [Recipe!]!
}

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

## Motivation

We all know that GraphQL is great and solves many problems we have with REST APIs, like Over-Fetching and Under-Fetching. 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.graphql` using SDL. Then we create our data models using [ORM classes](https://github.com/typeorm/typeorm), 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 implement the resolvers using weird generic signatures and manually performing common tasks, like validation, authorization and loading dependencies:

```ts
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 the field name? The rename feature (F2) won't work correctly.

Tools like [GraphQL Code Generator](https://github.com/dotansimha/graphql-code-generator) or [graphqlgen](https://github.com/prisma/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 the 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.

## Documentation

The documentation, installation guide, and detailed description of the API and all of its features are [available on the website](https://typegraphql.com).

### Getting started

A full getting started guide with a simple walkthrough (tutorial) can be found at [getting started docs](https://typegraphql.com/docs/getting-started.html).

### Video tutorial

If you prefer video tutorials, you can watch [Ben Awad](https://github.com/benawad)'s [TypeGraphQL video series](https://www.youtube.com/playlist?list=PLN3n1USn4xlma1bBu3Tloe4NyYn9Ko8Gs) on YouTube.

### Examples

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

The [Tests folder](./tests) might also give you some tips on how to get various things done.

## Security contact information

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## The future

The currently released version is a stable 1.0.0 release. It is well-tested (97% coverage, ~500 test cases) and has most of the planned features already implemented. Plenty of companies and independent developers are using it in production with success.

However, there are also plans for a lot more features like better TypeORM, Prisma and DataLoader integration, custom decorators and metadata annotations support - [the full list of ideas](https://github.com/MichalLytek/type-graphql/issues?q=is%3Aissue+is%3Aopen+label%3A"Enhancement+%3Anew%3A") is available on the GitHub repo. You can also keep track of [development's progress on the project board](https://github.com/MichalLytek/type-graphql/projects/1).

If you have any interesting feature requests, feel free to open an issue on GitHub so we can discuss that!

## 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 it - its ongoing development is possible only thanks to the support of the community.

[![donate](https://opencollective.com/typegraphql/donate/button.png?color=blue)](https://opencollective.com/typegraphql)

### Gold Sponsors 🏆

> Please ask your company to support this open source project by [becoming a gold sponsor](https://opencollective.com/typegraphql/contribute/gold-sponsors-8340) and getting a premium technical support from our core contributors.

### Silver Sponsors 🥈

<!-- markdownlint-disable MD033 -->

| [<img src="./images/leofame.png" width="250" alt="Leofame" />](https://leofame.com/buy-instagram-followers) |
| :---------------------------------------------------------------------------------------------------------: |
|                         [**Leofame**](https://leofame.com/buy-instagram-followers)                          |

### Bronze Sponsors 🥉

| [<img src="./images/live-graphics-system.png" width="55" alt="live graphic systems" />](https://www.ligrsystems.com) | [<img src="./images/lifex.png" width="60" alt="lifeX aps" />](https://www.joinlifex.com) | [<img src="./images/instinctools.svg" width="100" alt="instinctools" />](https://instinctools.com/manufacturing) | [<img src="./images/wordhint.jpg" width="90" alt="WordHint" />](https://www.wordhint.net/) | [<img src="./images/strands-hint-logo.svg" width="80" alt="Strands Hint" />](https://strands-hint.net) |
| :------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------: |
|                               [**Live Graphic Systems**](https://www.ligrsystems.com)                                |                       [**LifeX Aps**](https://www.joinlifex.com/)                        |                            [**instinctools**](https://instinctools.com/manufacturing)                            |                         [**WordHint**](https://www.wordhint.net/)                          |                              [**Strands Hint**](https://strands-hint.net)                              |

| [<img src="./images/nongamstopbets.png" width="40" alt="NonGamstopBets" />](https://www.nongamstopbets.com/casinos-not-on-gamstop/) | [<img src="./images/casinodeps.svg" width="60" alt="CasinoDeps.co.nz" />](https://casinodeps.co.nz/1-dollar-casinos/) | [<img src="./images/non-stop-casino.png" width="40" alt="Non Stop Casino" />](https://uk.nonstopcasino.org/non-gamstop-casinos/) | [<img src="./images/graming.svg" width="90" alt="Graming" />](https://graming.com/buy-tiktok-views/) | [<img src="./images/betwinner.svg" width="100" alt="BetWinner" />](https://guidebook.betwinner.com/) | [<img src="./images/famety.png" width="40" alt="Famety" />](https://www.famety.com/buy-instagram-likes) | [<img src="./images/logo-buzzv.png" width="70" alt="BuzzVoice" />](https://buzzvoice.com/) | [<img src="./images/socialwick-logo.png" width="60" alt="SocialWick" />](https://www.socialwick.com/) | [<img src="./images/c19.png" width="50" alt="C19" />](https://www.c19.cl/) |
| :---------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------: |
|                            [**NonGamstopBets**](https://www.nongamstopbets.com/casinos-not-on-gamstop/)                             |                             [**CasinoDeps**](https://casinodeps.co.nz/1-dollar-casinos/)                              |                             [**Non Stop Casino**](https://uk.nonstopcasino.org/non-gamstop-casinos/)                             |                         [**Graming**](https://graming.com/buy-tiktok-views/)                         |                          [**BetWinner**](https://guidebook.betwinner.com/)                           |                        [**Famety**](https://www.famety.com/buy-instagram-likes)                         |                          [**BuzzVoice**](https://buzzvoice.com/)                           |                             [**SocialWick**](https://www.socialwick.com/)                             |                       [**C19**](https://www.c19.cl/)                       |

| [<img src="./images/sidesmedia.png" width="40" alt="SidesMedia" />](https://sidesmedia.com/) | [<img src="./images/social_followers.png" width="60" alt="Social Followers" />](https://www.socialfollowers.uk/buy-tiktok-followers/) | [<img src="./images/ig-comment.png" width="80" alt="IG Comment" />](https://igcomment.com/buy-instagram-comments/) | [<img src="./images/twicsy.svg" width="100" alt="Twicsy" />](https://twicsy.com/buy-instagram-followers) | [<img src="./images/buzzoid.svg" width="90" alt="Buzzoid" />](https://buzzoid.com/buy-instagram-followers/) | [<img src="./images/socialmention.webp" width="100" alt="Social Mention" />](https://www.socialmention.com/buy-youtube-likes/) | [<img src="./images/tiktok-expert.jpg" width="60" alt="TikTok Expert" />](https://www.reddit.com/r/TikTokExpert/comments/1f812o7/best_and_cheapest_site_to_buy_tiktok_followers/) | [<img src="./images/tokmax.svg" width="70" alt="Tokmax" />](https://tokmax.com/) | [<img src="./images/use-viral-logo.webp" width="90" alt="UseViral" />](https://useviral.com/) |
| :------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------: |
|                          [**SidesMedia**](https://sidesmedia.com/)                           |                             [**Social Followers**](https://www.socialfollowers.uk/buy-tiktok-followers/)                              |                          [**IG Comment**](https://igcomment.com/buy-instagram-comments/)                           |                         [**Twicsy**](https://twicsy.com/buy-instagram-followers)                         |                         [**Buzzoid**](https://buzzoid.com/buy-instagram-followers/)                         |                             [**Social Mention**](https://www.socialmention.com/buy-youtube-likes/)                             |                            [**TikTok Expert**](https://www.reddit.com/r/TikTokExpert/comments/1f812o7/best_and_cheapest_site_to_buy_tiktok_followers/)                            |                        [**Tokmax**](https://tokmax.com/)                         |                             [**UseViral**](https://useviral.com/)                             |

<!-- markdownlint-enable MD033 -->

[![become a sponsor](https://opencollective.com/static/images/become_sponsor.svg)](https://opencollective.com/typegraphql)

### Members 💪

[![Members](https://opencollective.com/typegraphql/tiers/members.svg?avatarHeight=45&width=320&button=false)](https://opencollective.com/typegraphql#contributors)

### GitHub Sponsors

[![GitHub Sponsors](./images/github-sponsors.svg)](https://github.com/sponsors/TypeGraphQL)

## Community

- Visit the [Official Website](https://typegraphql.com)
- Chat on [Discord](https://discord.gg/cWnBAQcbg2)

## Want to help?

Want to file a bug, contribute some code, or improve the documentation? Great! Please read our
guidelines for [CONTRIBUTING](./CONTRIBUTING.md) and then check out one of our [help-wanted issues](https://github.com/MichalLytek/type-graphql/labels/Help%20Wanted%20%3Asos%3A).