NestJS Graphql automation library for building performant API
\n
\n \n \n \n \n
\n\n\n## Description\n\nThe library allows to build efficient graphql API helping overcome n+1 problem and building hasura-like search interface with the minimum dependencies.\n\n## Introduction\nWith the library you will be able to build queries like that easily, using decorators and having full controll over everything.\n```graphql\n{\n users(\n where: {\n id: { in: [1,2,3,4] }\n task_title: { like: \"%Task%\" }\n }\n order_by: {email: ASC, created_at: DESC}\n paginate: {page: 1, per_page: 10}\n ) {\n id\n fname\n lname\n email\n tasks(order_by: {id: ASC_NULLS_LAST}) {\n id\n title\n }\n }\n}\n\n```\n\n## Overview\n- [Description](#description)\n- [Introduction](#introduction)\n- [Overview](#overview)\n- [Installation](#installation)\n- [Data Loader n+1 problem solver](#data-loader-n1-problem-solver)\n - [Loader usage guide](#loader-usage-guide)\n - [One to many example](#one-to-many-example)\n - [Many to one relation](#many-to-one-relation)\n- [Polymorphic relations](#polymorphic-relations)\n - [Usage](#usage)\n - [Example](#example)\n- [Filters](#filters)\n - [Basic example 1](#basic-example-1)\n - [Basic example 2](#basic-example-2)\n - [Filter usage guide](#filter-usage-guide)\n - [@Query with filters](#query-with-filters)\n - [@ResolveField with filter](#resolvefield-with-filter)\n - [Custom filters](#custom-filters)\n - [Raw filters](#raw-filters)\n- [Sorting](#sorting)\n - [Basic example](#basic-example)\n - [Custom sorting fields](#custom-sorting-fields)\n - [Raw sorting](#raw-sorting)\n- [Exclusions](#exclusions)\n - [Exclude field from filters and sortings](#exclude-field-from-filters-and-sortings)\n- [Pagination](#pagination)\n - [@Query with pagination](#query-with-pagination)\n- [Field extraction](#field-extraction)\n - [Basic example](#basic-example-1)\n- [Base models and inheritance](#base-models-and-inheritance)\n - [How to inherit DTO from base class](#how-to-inherit-dto-from-base-class)\n- [Federation](#federation)\n - [Example](#example-1)\n- [Additional options](#additional-options)\n- [More examples](#more-examples)\n- [FAQ](#faq)\n- [Contribution](#contribution)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm i nestjs-graphql-tools\nor\nyarn add nestjs-graphql-tools\n```\n\n## Data Loader n+1 problem solver\n#### Loader usage guide\n 1. Decorate your resolver with `@GraphqlLoader()`\n 2. Add `@Loader()` parameter as a first parameter\n 3. @Loader will return you LoaderData interface which includes ids of entities and helpers for constructing sutable object for graphql\n\n##### One to many example\n\n```typescript\n@Resolver(() => UserObjectType) \nexport class UserResolver {\n\n @ResolveField(() => TaskObjectType)\n @GraphqlLoader()\n async tasks(\n @Loader() loader: LoaderData,\n @Args('story_points') story_points: number, // custom search arg\n ) {\n const tasks = await getRepository(Task).find({\n where: {\n assignee_id: In(loader.ids) // assignee_id is foreign key from Task to User table\n story_points\n }\n });\n\n return loader.helpers.mapOneToManyRelation(tasks, loader.ids, 'assignee_id'); // this helper will construct an object like { : Task }. Graphql expects this shape.\n }\n}\n```\n\n##### Many to one relation\n```typescript\n@Resolver(() => TaskObjectType)\nexport class TaskResolver {\n\n constructor(\n @InjectRepository(User) public readonly userRepository: Repository\n ) {}\n\n @ResolveField(() => UserObjectType)\n @GraphqlLoader({\n foreignKey: 'assignee_id' // Here we're providing foreigh key. Decorator gather all the keys from parent and provide it in loader.ids\n })\n async assignee(\n @Loader() loader: LoaderData,\n @Filter(() => UserObjectType) filter: Brackets,\n ) {\n const qb = this.userRepository.createQueryBuilder('u')\n .where(filter)\n .andWhere({\n id: In(loader.ids) // Here will be assigne_ids\n })\n const users = await qb.getMany();\n return loader.helpers.mapManyToOneRelation(users, loader.ids); // This helper provide the shape {assignee_id: User}\n }\n}\n```\n## Polymorphic relations\n`@GraphqlLoader` decorator provides ability to preload polymorphic relations\n#### Usage\nTo be able to use it you need to decorate your resolver with `@GraphqlLoader` decorator. Decorator has parameter which allows to specify fields which needs to be gathered for polymorphic relation.\n\n```typescript\n@GraphqlLoader({\n polymorphic: {\n idField: 'description_id', // Name of polymorphic id attribute of the parent model\n typeField: 'description_type' // Name of polymorphic type attribute of the parent model\n }\n})\n```\nThis decorator will aggregate all types and provide ids for each type. All aggregated types will be aveilable in `@Loader` decorator. It has attribute which called `polymorphicTypes. \n\nPolmorphicTypes attribute shape \n```typescript\n[\n {\n type: string | number\n ids: string[] | number[]\n }\n]\n\n```\n\n##### Example\n\n```typescript\n// Parent class\n// task.resolver.ts\n@Resolver(() => TaskObjectType)\nexport class TaskResolver {\n constructor(\n @InjectRepository(Task) public readonly taskRepository: Repository,\n @InjectRepository(Description) public readonly descriptionRepository: Repository\n ) {}\n\n @ResolveField(() => [DescriptionObjectType])\n @GraphqlLoader()\n async descriptions(\n @Loader() loader: LoaderData,\n @SelectedUnionTypes({ \n nestedPolymorphicResolverName: 'descriptionable',\n }) selectedUnions: SelectedUnionTypesResult // <-- This decorator will gather and provide selected union types. NestedPolymorphicResolverName argument allows to specify where specifically it should gather the fields\n ) {\n // Mapping graphql types to the database types\n const selectedTypes = Array.from(selectedUnions.types.keys()).map(type => { \n switch (type) {\n case DescriptionTextObjectType.name:\n return DescriptionType.Text;\n case DescriptionChecklistObjectType.name:\n return DescriptionType.Checklist;\n }\n });\n\n const qb = this.descriptionRepository.createQueryBuilder('d')\n .andWhere({\n task_id: In(loader.ids),\n description_type: In(selectedTypes) // finding only selected types\n })\n \n const descriptions = await qb.getMany();\n return loader.helpers.mapOneToManyRelation(descriptions, loader.ids, 'task_id');\n }\n}\n\n\n// Polymorphic resolver\n// description.resolver.ts\n@Resolver(() => DescriptionObjectType)\nexport class DescriptionResolver {\n constructor(\n @InjectRepository(DescriptionText) public readonly descriptionTextRepository: Repository,\n @InjectRepository(DescriptionChecklist) public readonly descriptionChecklistRepository: Repository,\n ) {}\n \n @ResolveField(() => [DescriptionableUnion], { nullable: true })\n @GraphqlLoader({ // <-- We will load description_id field of parent model to the ids and description_type field to the type\n polymorphic: {\n idField: 'description_id',\n typeField: 'description_type'\n }\n })\n async descriptionable(\n @Loader() loader: PolymorphicLoaderData<[DescriptionText | DescriptionChecklist], number, DescriptionType>, // <-- It will return aggregated polymorphicTypes\n @SelectedUnionTypes() types: SelectedUnionTypesResult // <-- It will extract from the query and return selected union types\n ) {\n const results = []; // <-- We need to gather all entities to the single array\n\n for (const item of loader.polimorphicTypes) {\n switch(item.descriminator) {\n case DescriptionType.Text:\n const textDescriptions = await this.descriptionTextRepository.createQueryBuilder()\n .select(types.getFields(DescriptionTextObjectType))\n .where({\n id: In(item.ids)\n })\n .getRawMany();\n\n results.push({ descriminator: DescriptionType.Text, entities: textDescriptions })\n\n break;\n case DescriptionType.Checklist:\n const checklistDescriptions = await this.descriptionChecklistRepository.createQueryBuilder()\n .select(types.getFields(DescriptionChecklistObjectType))\n .where({\n id: In(item.ids)\n })\n .getRawMany();\n\n results.push({ descriminator: DescriptionType.Checklist, entities: checklistDescriptions })\n \n break;\n default: break;\n }\n }\n return loader.helpers.mapOneToManyPolymorphicRelation(results, loader.ids); // <-- This helper will change shape of responce to the shape which is sutable for graphql\n }\n}\n```\nYou can find complete example in src/descriptions folder\n\n\n## Filters\nFilter is giving ability to filter out entities by the condition. Condition looks similar to hasura interface using operators `eq, neq, gt, gte, lt, lte, in, like, notlike, between, notbetween, null`.\nBy default it generates filter based on provided model. It supports only first level of the tables hierachy. If you need to search in depth you can declare custom filters (example 3).\n\n#### Basic example 1\n\n```graphql\n{\n users(where: {id: {eq: 1}}) {\n id\n }\n}\n```\n#### Basic example 2\n```graphql\n{\n users(\n where: {\n and: [\n {\n email: {like: \"yahoo.com\"}\n }\n {\n email: {like: \"google.com\"}\n }\n ],\n or: {\n id: {\n between: [1,2,3]\n }\n }\n }\n ) {\n id\n }\n}\n```\n\n#### Filter usage guide\n1. Add `@Filter()` parameter with type of `FilterArgs`\n2. `@Filter()` will return typeorm compatible condition which you can use in your query builder.\n\n##### @Query with filters\n\n```typescript\n@Resolver(() => UserObjectType)\nexport class UserResolver {\n constructor(\n @InjectRepository(Task) public readonly taskRepository: Repository,\n @InjectRepository(User) public readonly userRepository: Repository\n ) {}\n\n @Query(() => [UserObjectType])\n users(\n @Filter(() => UserObjectType) filter: FilterArgs, // It will return typeorm condition\n @Args('task_title', {nullable: true}) taskTitle: string, // You can add custom additional filter if needed\n ) {\n const qb = this.userRepository.createQueryBuilder('u')\n .leftJoin('task', 't', 't.assignee_id = u.id')\n .where(filter)\n .distinct();\n\n if (taskTitle) { // mixed filters\n qb.andWhere(`t.title ilike :title`, { title: `%${taskTitle}%` })\n }\n\n return qb.getMany()\n }\n}\n```\n\n##### @ResolveField with filter\n\n```typescript\n@Resolver(() => UserObjectType)\nexport class UserResolver {\n constructor(@InjectRepository(Task) public readonly taskRepository: Repository) {}\n\n @ResolveField(() => TaskObjectType)\n @GraphqlLoader()\n async tasks(\n @Loader() loader: LoaderData,\n @Filter(() => TaskObjectType) filter: FilterArgs,\n ) {\n const qb = this.taskRepository.createQueryBuilder()\n .where(filter)\n .andWhere({\n assignee_id: In(loader.ids)\n });\n\n const tasks = await qb.getMany();\n \n return loader.helpers.mapOneToManyRelation(tasks, loader.ids, 'assignee_id');\n }\n}\n```\n##### Custom filters\n\n```typescript\n@InputType()\nexport class UserFilterInputType {\n @FilterField(() => String, { sqlExp: 't.title'})\n task_title: string;\n\n @FilterField(() => String, { sqlExp: 't.story_points'})\n task_story_points: number;\n \n @FilterField(() => String, { sqlExp: 'concat(u.fname, \\' \\', u.lname)'})\n full_name: string;\n}\n\n// Resolver\n@Resolver(() => UserObjectType)\nexport class UserResolver {\n constructor(\n @InjectRepository(Task) public readonly taskRepository: Repository,\n @InjectRepository(StoryModel) public readonly storyRepository: Repository,\n @InjectRepository(User) public readonly userRepository: Repository\n ) {}\n\n @Query(() => [UserObjectType])\n users(\n @Filter(() => [UserObjectType, UserFilterInputType]) filter: FilterArgs, // <-- Object model and Filter model. It is possible to provide only one model or more that 2.\n @Sorting(() => UserObjectType, { sqlAlias: 'u' }) sorting: SortArgs\n ) {\n const qb = this.userRepository.createQueryBuilder('u')\n .leftJoin('task', 't', 't.assignee_id = u.id')\n .where(filter)\n .orderBy(sorting);\n\n return qb.getMany()\n }\n}\n```\n\nYou can also exclude some fields from the DTO filter. Read [Exclusions](#exclusions).\n\n#### Raw filters\nRaw filters allow to get access to the user provided raw value right from the code. This feature allows to build your own filters interpreters.\n\nHow to use raw filters:\n1. Add `@Filter({ raw: true })` parameter with type of `RawFilterArgs` where `T` is your filter type\n2. `@Filter()` will return raw filter data.\n\n```typesript\nexport class UserResolver {\n @Query(() => [UserObjectType])\n async usersRaw(\n @Filter(() => [UserObjectType, UserFilterInputType], {sqlAlias: 'u', raw: true}) filter: RawFilterArgs,\n @Paginator() paginator: PaginatorArgs\n ) {\n // Your customer filter logic..\n return [];\n }\n}\n```\n\n## Sorting\nThe library provides ability to make sorting. It supports all types of sorting.\n`[ASC/DESC] [NULLS FIRST/LAST]`\n\n#### Basic example\n\n```graphql\n{\n users(\n order_by: {\n id: ASC_NULLS_LAST\n }\n ) {\n id\n }\n}\n```\n```typescript\n@Resolver(() => TaskObjectType)\nexport class TaskResolver {\n constructor(@InjectRepository(Task) public readonly taskRepository: Repository) {}\n\n @Query(() => [TaskObjectType])\n async tasks(\n /* SqlAlias is an ptional argument. Allows to provide alias in case if you have many tables joined. In current case it doesn't required */\n @Sorting(() => TaskObjectType, { sqlAlias: 't' }) sorting: SortArgs\n ) {\n const qb = this.taskRepository.createQueryBuilder('t')\n .orderBy(sorting);\n return qb.getMany();\n }\n}\n```\n\n#### Custom sorting fields\n```typescript\n// sorting.dto.ts\n@InputType()\nexport class UserSortingInputType {\n @SortingField({sqlExp: 't.story_points'})\n task_story_points: number;\n}\n\n// user.resolver.ts\n@Resolver(() => UserObjectType)\nexport class UserResolver {\n constructor(\n @InjectRepository(Task) public readonly taskRepository: Repository,\n @InjectRepository(StoryModel) public readonly storyRepository: Repository,\n @InjectRepository(User) public readonly userRepository: Repository\n ) {}\n\n @Query(() => [UserObjectType])\n users(\n /* SqlAlias is an optional argument. You can provide alias in case if you have many tables joined.\n Object model and Sorting model. Ability to provide 1+ model. It accepts both Object and Sorting models. Next model in array extends previous model overriding fields with the same names.\n */\n @Sorting(() => [UserObjectType, UserSortingInputType], { sqlAlias: 'u' }) sorting: SortArgs\n ) {\n const qb = this.userRepository.createQueryBuilder('u')\n .leftJoin('task', 't', 't.assignee_id = u.id')\n .orderBy(sorting)\n .distinct();\n\n return qb.getMany()\n }\n}\n```\nYou can also exclude some fields from the sorting DTO. Read [Exclusions](#exclusions).\n\n#### Raw sorting\nRaw sorting allows to get access to the user provided raw value right from the code. This feature allows to build your own sorting interpreters.\n\nHow to use raw sorting:\n1. Add `@Sorting({ raw: true })` parameter with type of `RawSortingArgs` where `T` is your sorting type\n2. `@Sorting()` will return raw sorting data.\n\n```typesript\nexport class UserResolver {\n @Query(() => [UserObjectType])\n async usersRaw(\n @Sorting(() => [UserObjectType], { sqlAlias: 'u', raw: true}) sorting: RawSortingArgs,\n @Paginator() paginator: PaginatorArgs\n ) {\n // Your customer filter logic..\n return [];\n }\n}\n```\n\n## Exclusions\nSometimes you don't want to provide filters/sorting by all the fields in the dto. There's a couple decorators that can help with it `@FilterField({exclude: true}) ` and `@SortingField({exclude: true})`\n\n#### Exclude field from filters and sortings\n```typescript\n\n@ObjectType()\nexport class User {\n @Field(() => String)\n fname: string;\n\n @Field(() => String)\n @FilterField({exclude: true})\n @SortingField({exclude: true})\n mname: string;\n\n @Field(() => String)\n lname: string;\n}\n\nexport class UserResolver {\n @Query(() => [UserObjectType])\n users(\n @Filter(() => [UserObjectType], {sqlAlias: 'u'}) filter: FilterArgs,\n @Sorting(() => [UserObjectType], { sqlAlias: 'u' }) sorting: SortArgs\n ) {\n const qb = this.userRepository.createQueryBuilder('u')\n .where(filter)\n .orderBy(sorting);\n\n return qb.getMany()\n }\n}\n\n```\n\nNow, if you try to build a query with the sorting an filtering by mname you'll get an error, because there's not such field in the graphql schema definition for sorting and filtering.\n\n## Pagination\nThe library provides parameter decorator `@Paginator()` for the pagination. This decorator returns object like that\n\n```typescript\n{\n page: number,\n per_page: number\n}\n\n```\n\n#### @Query with pagination\n\n```typescript\n@Resolver(() => TaskObjectType)\nexport class TaskResolver {\n constructor(@InjectRepository(Task) public readonly taskRepository: Repository) {}\n\n @Query(() => [TaskObjectType])\n async tasks(\n @Paginator() paginator: PaginatorArgs,\n ) {\n const qb = this.taskRepository.createQueryBuilder('t');\n \n if (paginator) {\n qb.offset(paginator.page * paginator.per_page).limit(paginator.per_page)\n }\n\n return qb.getMany();\n }\n}\n```\n\n## Field extraction\nThe library allows to gather only requested field from the query and provides it as an array to the parameter variable.\n\n#### Basic example\n\nSimple graphql query\n```graphql\n{\n tasks {\n id\n title\n }\n}\n\n```\nResolver\n\n```typescript\n@Resolver(() => TaskObjectType)\nexport class TaskResolver {\n constructor(@InjectRepository(Task) public readonly taskRepository: Repository) {}\n\n @Query(() => [TaskObjectType])\n async tasks(\n @Filter(() => TaskObjectType) filter: FilterArgs,\n @SelectedFields({sqlAlias: 't'}) selectedFields: SelectedFieldsResult // Requested fields will be here. sqlAlias is optional thing. It useful in case if you're using alias in query builder\n ) {\n const res = await this.taskRepository.createQueryBuilder('t')\n .select(selectedFields.fieldsData.fieldsString) // fieldsString return array of strings\n .where(filter)\n .getMany();\n return res;\n }\n}\n```\n\nThe query will generate typeorm request with only requested fields\n```sql\nSELECT \"t\".\"id\" AS \"t_id\", \"t\".\"title\" AS \"t_title\" FROM \"task\" \"t\"\n```\n\n## Base models and inheritance\nIn order to make base model with common attributes it is required to decorate base model with the `@InheritedModel()` decorator. You can find usage of it in base.dto.ts file inside src folder.\n\n#### How to inherit DTO from base class\n```typescript\n@ObjectType()\n@InheritedModel() // <-- Make inheritance possible. If you not decorate object with this decorator, you will not see these properties in \"where\" and sorting statements\nexport class BaseDTO {\n @Field(() => Int)\n id: number;\n\n // Timestamps\n @Field(() => Date)\n created_at: Date;\n\n @Field(() => Date)\n updated_at: Date;\n}\n```\n\n## Federation\nBasic support of federation already in place. Just add to your method with `@ResolveReference()` one more decorator `@GraphqlLoader()`\n\n#### Example\nThis examples is the reference to official example https://github.com/nestjs/nest/tree/master/sample/31-graphql-federation-code-first. Clone https://github.com/nestjs/nest/tree/master/sample/31-graphql-federation-code-first (download specific directory with https://download-directory.github.io/ or with chrome extention https://chrome.google.com/webstore/detail/gitzip-for-github/ffabmkklhbepgcgfonabamgnfafbdlkn)\n1. Annotate method resolveReference of `users-application/src/users/users.resolver.ts`\n```typescript\n// users-application/src/users/users.resolver.ts\n@ResolveReference()\n@GraphqlLoader()\nasync resolveReference(\n @Loader() loader: LoaderData,\n) {\n const ids = loader.ids;\n const users = this.usersService.findByIds(ids);\n return loader.helpers.mapManyToOneRelation(users, loader.ids, 'id')\n}\n```\n1. Add method findByIds to `users-application/src/users/users.service.ts`\n```typescript\n// users-application/src/users/users.service.ts\n@Injectable()\nexport class UsersService {\n private users: User[] = [\n { id: 1, name: 'John Doe' },\n { id: 2, name: 'Richard Roe' },\n ];\n\n findByIds(idsList: number[]): User[] {\n return this.users.filter((user) => idsList.some(id => Number(id) === user.id));\n }\n}\n```\n3. Install dependencies of 3 projects : npm ci in gateway, posts-application, users-application.\n4. Run all projects in order :\n - `cd users-application && npm run start`\n - `cd posts-application && npm run start`\n - `cd gateway && npm run start`\n\n5. Go to localhost:3001/graphql and send graphql request to gateway\n```graphql\n{\n posts {\n id\n title\n authorId\n user {\n id\n name\n }\n }\n}\n```\n## Additional options\nOptions are ENV variables that you can provide to configurate the lib\n- `FILTER_OPERATION_PREFIX` - Operation prefix. You can make hasura-like prefix for where operators like _eq, _neq, etc. Example `FILTER_OPERATION_PREFIX=\\_`\n\n\n## More examples\nYou can find more examples in the src folder\n\n## FAQ\n1. **Q**: Let's say you have many joins and some tables has duplicated fields like name or title. **A**: In order not to break filters you need to provide sqlAlias that matches alias of the main model of the query. There plenty examples in the code in in readme.\n2. **Q**:The same example where you have a model with many joins and you want to provide ability to sort or filter by joined field. **A**: you can create custom filter with ability to provide sql alias that they will use. Check out filtering section, there a couple examples with custom fields.\n3. **Q**: The error: `QueryFailedError: for SELECT DISTINCT, ORDER BY expressions must appear in select list`. **A** To avoid this error add sorted field to selected fields. In most of the time it might happen in case you're using custom fields for sorting.\n4. **Q**: How can I make resolver for Many to Many relation. **A** Many to Many relation is the same as One to Many. Basically, it requres one additional resolver that resolves the intermediary table between two main entitites. Let's say we have Roles and Users with M to M relation. The implementation from the database perspective would be Users <> UsersRoles <> Roles. UserRole is the intermediary table. You would need to implement a resolver for UsersRoles. In this resolver you need to resolve users and roles fields like it described [here](#many-to-one-relation).\n\n## Contribution\nIf you want to contribute please create new PR with good description.\n\nHow to run the project:\n1. Create a database\n```bash\ncreatedb -h localhost -U postgres nestjs_graphql_tools_development_public;\n```\n2. Fill out database config in `config/default.json`\n3. Run dev server\n```bash\nyarn install\nyarn start:dev\n```\nOn the first run, server will seed up the database with testing dataset.\n\n4. Reach out `http://localhost:3000/graphql`\n\n## License\n\nNestJS Graphql tools is [GNU GPLv3 licensed](LICENSE).\n","readmeFilename":"README.md"}
![\"Nest](\"https://nestjs.com/img/logo-small.svg\"){kind=logo}
![\"NestJS](\"https://raw.githubusercontent.com/Adrinalin4ik/Nestjs-Graphql-Tools/master/images/svg.svg\")
\n![\"NPM](\"https://img.shields.io/npm/v/nestjs-graphql-tools.svg\")
\n ![\"Package](\"https://img.shields.io/npm/l/nestjs-graphql-tools.svg\")
\n ![\"NPM](\"https://img.shields.io/npm/dm/nestjs-graphql-tools.svg\")
\n ![\"mutable.ai\"](\"https://img.shields.io/badge/Auto_Wiki-Mutable.ai-blue\"){kind=icon}