TypeORM GraphQL Relation Loader

A dataloader for TypeORM that makes it easy to load TypeORM relations for GraphQL query resolvers.

UPGRADE NOTICE

The 1.0.0 release of this package includes almost a complete rewrite of the source code. The public interface of the loader has changed significantly. As such, upgrading from the older versions will require significant work.

For those upgrading, I highly recommend reading through the new documentation to get an idea of the changes required.

Contents

• Description
• Installation
• Usage
• Gotchas
• Roadmap
• Contributing
• Problem
• Solution
• Acknowledgments

Description

This package provides a GraphQLDatabaseLoader class, which is a caching loader that will parse a GraphQL query info object and load the TypeORM fields and relations needed to resolve the query. For a more in-depth explanation, see the Problem and Solution sections below.

Installation

yarn add @mando75/typeorm-graphql-loader

# OR

npm install @mando75/typeorm-graphql-loader

This package requires that you have TypeORM installed as a peer dependency

Usage

You should create a new GraphQLDatabaseLoader instance in each user session, generally via the GraphQLContext object. This is to help with caching and prevent user data from leaking between requests. The constructor takes a TypeORM connection as the first argument, and a LoaderOptions type as an optional second parameter.

Apollo Server Example

import { GraphQLDatabaseLoader } from '@mando75/typeorm-graphql-loader';
const connection = createConnection({...}); // Create your TypeORM connection

const apolloServer = new ApolloServer({
  schema,
  context: {
    loader: new GraphQLDatabaseLoader(connection, {/** additional options if needed**/})
  },
});

The loader will now appear in your resolver's context object:

{ 
  Query: {
    getBookById(object: any, args: {id: string }, context: MyGraphQLContext, info: GraphQLResolveInfo) {
        return context.loader
            .loadEntity(Book, "book")
            .where("book.id = :id", { id })
            .info(info)
            .loadOne();
    }
  }
}

Please note that the loader will only return the fields and relations that the client requested in the query. You can configure certain entity fields to be required or ignored via the ConfigureLoader decorator.

The loader provides a thin wrapper around the TypeORM SelectQueryBuilder with utility functions to help with things like adding where conditions, searching and pagination. For more advanced query building, see the documentation for the ejectQueryBuilder method.

Please refer to the full documentation for more details on what options and utilities the loader provides.

Gotchas

Because this package reads which relations and fields to load from the GraphQL query info object, the loader only works if your schema field names match your TypeORM entity field names. If it cannot find a requested GraphQL query field, it will not return it. In this case, you will need to provide a custom resolver for that field in your GraphQL resolvers file. In this case, the loader will provide the resolver function with an object parameter which is an entity loaded with whichever other fields your query requested. The loader will always return an object with at least the primary key loaded, so basic method calls should be possible. The loader will automatically scan your entity and include whatever column marked as primary key in the query.

This is not a complete replacement for the dataloader package, its purpose is different. While it does provide some batching, its primary purpose is to load the relations and fields needed to resolve the query. In most cases, you will most likely not need to use dataloader when using this package. However, I have noticed in my own use that there are occasions where this may need to be combined with dataloader to remove N + 1 queries. One such case was a custom resolver for a many-to-many relation that existed in the GraphQL Schema but not on a database level. In order to completely remove the N+1 queries from that resolver, I had to wrap the TypeORM GraphQL loader in a Facebook DataLoader. If you find that you are in a situation where the TypeORM GraphQL loader is not solving the N+1 problem, please open an issue, and I'll do my best to help you out with it.

This package has currently only been tested with Postgresql and SQLite. In theory, everything should work with the other SQL variants that TypeORM supports, as it uses the TypeORM Query Builder API to construct the database queries. If you run into any issues with other SQL dialects, please open an issue.

For help with pagination, first read Pagination Advice

Roadmap

Relay Support

Currently, the loader only supports offset pagination. I would like to add the ability to support Relay-style pagination out of the box.

Track Progress

Contributing

This project is developed on GitLab.com. However, I realize that many developers use GitHub as their primary development platform. If you do not use and do not wish to create a GitLab account, you can open an issue in the mirrored GitHub Repository. Please note that all merge requests must be done via GitLab as the GitHub repo is a read-only mirror.

When opening an issue, please include the following information:

• Package Version
• Database and version used
• TypeORM version
• GraphQL library used
• Description of the problem
• Example code

Please open an issue before opening any Merge Requests.

Problem

TypeORM is a pretty powerful tool, and it gives you quite a bit of flexibility in how you manage entity relations. TypeORM provides 3 ways to load your relations, eagerly, manually, or lazily. For more info on how this works, see the TypeORM Documentation.

While this API is great for having fine-grained control of you data layer, it can get frustrating to use in a GraphQL schema. For example, lets say we have three entities, User, Author, and Book. Each Book has an Author, and each Author has a User. We want to expose these relations via a GraphQL API. Our issue now becomes how to resolve these relations. Let's look at how an example resolver function might try to resolve this query:

Query

query bookById($id: ID!) {
  book(id: $id) {
    id
    name
    author {
      id
      user {
        id
        name
      }
    }
  }
}

We could do something simple like this:

function findBookById(object, args, context, info) {
  return Book.findOne(args.id);
}

but then the author and user relations won't be loaded. We can remedy that by specifying them in our find options like so:

function findBookById(object, args, context, info) {
  return Book.findOne(args.id, { relations: ["author", "author.user"] });
}

however, this could get really nasty if we have many relations we may need. Well, we could just set all of our relations to eagerly load so we don't need to specify them, but then we may start loading a bunch of data we may never use which isn't very performant at scale.

How about just defining a resolver for every relation and loading them as needed? That could work, but it seems like a lot of work and duplication of effort when we've already specified our relations on the entity level. This will also lead us to a path where we will need to start creating custom loaders via dataloader to deal with impending N + 1 problems.

Another possible, and probably intuitive solution is to use lazy relations. Because lazy relations return Promises, as long as we give the resolver an instance of our Book entity, it will call each relation and wait for the Promise to resolve, fixing our problem. It lets us use our original resolver function:

function findBookById(object, args, context, info) {
  return Book.findOne(args.id);
}

and GraphQL will just automatically resolve the relation promises for us and return the data. Seems great right? It's not. This introduces a massive N+1 problem. Now every time you query a sub-relation, GraphQL will inadvertently perform another database query to load the lazy relation. At small scale this isn't a problem, but the more complex your schema becomes, the harder it will hit your performance.

Solution

This package offers a solution to take away all the worry of how you manage your entity relations in the resolvers. GraphQL provides a parameter in each resolver function called info. This info parameter contains the entire query graph, which means we can traverse it and figure out exactly which fields need to be selected, and which relations need to be loaded. This is used to create one SQL query that can get all the information at once.

Because the loader uses the queryBuilder API, it does not matter if you have all "normal", "lazy", "eager" relations, or a mix of all of them. You give it your starting entity, and the GraphQL query info, and it will figure out what data you need and give it back to you in a structured TypeORM entity. Additionally, it provides some caching functionality as well, which will dedupe identical query signatures executed in the same tick.

Acknowledgments

This project inspired by the work of Weboptimizer's typeorm-loader package. I work quite a bit with Apollo Server + TypeORM and I was looking to find a way to more efficiently pull data via TypeORM for GraphQL via intelligently loading the needed relations for a given query. I stumbled across his package, which seemed to promise all the functionality, but it seemed to be in a broken/unmaintained state. After several months of no response from the author, and with significant bug fixes/features added in my fork, I decided to just make my own package. So thanks to Weboptimizer for doing a lot of the groundwork. Since then, I have almost completely rewritten the library to be a bit more maintainable and feature rich, but I would still like to acknowledge the inspiration his project gave me.