Skip to main content

Services

@nestjs-query provides a common interface to use different ORMs in order to query and mutate your data.

The following ORMs are supported out of the box.

@ptc-org/nestjs-query-core also provides a number of base QueryServices that can be used to create custom query services. See the Services docs

All examples assume the following entity.

todo-item.entity.ts
import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm';

@Entity()
export class TodoItemEntity {
  @PrimaryGeneratedColumn()
  id!: string;

  @Column()
  title!: string;

  @Column()
  completed!: boolean;

  @CreateDateColumn()
  created!: Date;

  @UpdateDateColumn()
  updated!: Date;
}

Creating a Service​

Module​

The nestjs-query typeorm, sequelize, mongoose, and typegoose packages provide a module that will add providers to inject auto-created QueryServices using the @InjectQueryService decorator.

In order to use the decorator you will need to use the module that comes with the nestjs-query orm module providing it your entities that you want the services created for.

todo-item.module.ts
import { NestjsQueryTypeOrmModule } from '@ptc-org/nestjs-query-typeorm';
import { Module } from '@nestjs/common';
import { TodoItemEntity } from './todo-item.entity';
import { TodoItemResolver } from './todo-item.resolver';

@Module({
  providers: [TodoItemResolver],
  imports: [NestjsQueryTypeOrmModule.forFeature([TodoItemEntity])],
})
export class TodoItemModule {}

Decorator​

Once you have imported the correct module, use @InjectQueryService decorator to inject a QueryService into your class or resolver.

todo-item.resolver.ts
import { QueryService, InjectQueryService } from '@ptc-org/nestjs-query-core';
import { CRUDResolver } from '@ptc-org/nestjs-query-graphql';
import { Resolver } from '@nestjs/graphql';
import { TodoItemDTO } from './todo-item.dto';
import { TodoItemEntity } from './todo-item.entity';

@Resolver(() => TodoItemDTO)
export class TodoItemResolver extends CRUDResolver(TodoItemDTO) {
  constructor(
    @InjectQueryService(TodoItemEntity) readonly service: QueryService<TodoItemEntity>
  ) {
    super(service);
  }
}
note

The above resolver is an example of manually defining the resolver, if you use the NestjsQueryGraphQLModule you do not need to define a resolver.

note

In the above example the DTO and entity are the same shape, if you have a case where they are different or have computed fields check out Assemblers to understand how to convert to and from the DTO/Entity.

Querying​

The nestjs-query QueryService uses a common Query interface that allows you use a common type regardless of the persistence library in use.

To query for records from your service you can use the query method which will return a Promise of an array of entities. To read more about querying take a look at the Queries Doc.

Example​

Get all records

const records = await this.service.query({});

Filtering​

The filter option is translated to a WHERE clause.

Example​

To find all completed TodoItems by use can use the is operator.

const records = await this.service.query({
   filter : {
     completed: { is: true },
   },
});

Sorting​

The sorting option is translated to a ORDER BY.

Example​

Sorting records by completed and title.

const records = await this.service.query({
  sorting: [
    {field: 'completed', direction: SortDirection.ASC},
    {field: 'title', direction: SortDirection.DESC},
  ],
});

Paging​

The paging option is translated to LIMIT and OFFSET.

Example​

Skip the first 20 records and return the next 10.

const records = await this.service.query({
  paging: {limit: 10, offset: 20},
});

Find By Id​

To find a single record you can use the findById method.

Example​

const records = await this.service.findById(1);

Get By Id​

The getById method is the same as the findById with one key difference, it will throw an exception if the record is not found.

Example​

try {
  const records = await this.service.getById(1);
} catch (e) {
  console.error('Unable to get record with id = 1');
}

Aggregating​

To perform an aggregate query you can use the aggregate method which accepts a Filter and AggregateQuery.

Supported aggregates are count, sum, avg, min and max.

In this example we'll aggregate on all records.

const aggregateResponse = await this.service.aggregate({}, {
    count: ['id'],
    min: ['title'],
    max: ['title']
});

The response will look like the following

[
  {
    count: {
      id: 10
    },
    min: {
      title: 'Aggregate Todo Items'
    },
    min: {
      title: 'Query Todo Items'
    },
  }
]

In this example we'll aggregate on all completed TodoItems

const aggregateResponse = await this.service.aggregate({ completed: { is: true } }, {
    count: ['id'],
    min: ['title'],
    max: ['title']
});

Creating​

Create One​

To create a single record use the createOne method.

Example​

const createdRecord = await this.service.createOne({
  title: 'Foo',
  completed: false,
});

Create Many​

To create multiple records use the createMany method.

Example​

const createdRecords = await this.service.createMany([
  { title: 'Foo', completed: false },
  { title: 'Bar', completed: true },
]);

Updating​

Update One​

To update a single record use the updateOne method.

Example​

Updates the record with an id equal to 1 to completed.

const updatedRecord = await this.service.updateOne(1, { completed: true });

Update Many​

To update multiple records use the updateMany method.

NOTE This method returns a UpdateManyResponse which contains the updated record count.

Example​

Updates all TodoItemEntities to completed if their title ends in Bar

const { updatedCount } = await this.service.updateMany(
  {completed: true}, // update
  {completed: {is: false}, title: {like: '%Bar'}} // filter
);

Deleting​

Delete One​

To delete a single record use the deleteOne method.

Example​

Delete the record with an id equal to 1.

const deletedRecord = await this.service.deleteOne(1);

Delete Many​

To delete multiple records use the deleteMany method.

NOTE This method returns a DeleteManyResponse which contains the deleted record count.

Example​

Delete all TodoItemEntities older than Jan 1, 2019.

const { deletedCount } = await this.service.deleteMany(
  { created: { lte: new Date('2019-1-1') } } // filter
);

Foreign Keys​

It is a common use case to include a foreign key from your entity in your DTO.

To do this you should add the foreign key to your entity as well as your DTO.

note

This section only applies when using typeorm and sequelize with relations

Example​

Assume TodoItems can have SubTasks we would set up our SubTaskEntity using the following

sub-task.entity.ts
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  ObjectType,
  ManyToOne,
  JoinColumn,
} from 'typeorm';
import { TodoItemEntity } from '../todo-item/todo-item.entity';

@Entity({ name: 'sub_task' })
export class SubTaskEntity {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column()
  title!: string;

  @Column({ nullable: true })
  description?: string;

  @Column()
  completed!: boolean;

  // add the todoItemId to the model
  @Column({ nullable: false, name: 'todo_item_id' })
  todoItemId!: string;

  @ManyToOne((): ObjectType<TodoItemEntity> => TodoItemEntity, (td) => td.subTasks, {
    onDelete: 'CASCADE',
    nullable: false,
  })
  // specify the join column we want to use.
  @JoinColumn({ name: 'todo_item_id' })
  todoItem!: TodoItemEntity;

  @CreateDateColumn()
  created!: Date;

  @UpdateDateColumn()
  updated!: Date;
}

Then we could add the todoItemId to the SubTaskDTO.

sub-task.dto.ts
import { FilterableField, IDField } from '@ptc-org/nestjs-query-graphql';
import { ObjectType, ID, GraphQLISODateTime } from '@nestjs/graphql';

@ObjectType('SubTask')
export class SubTaskDTO {
  @IDField(() => ID)
  id!: number;

  @FilterableField()
  title!: string;

  @FilterableField({ nullable: true })
  description?: string;

  @FilterableField()
  completed!: boolean;

  @FilterableField(() => GraphQLISODateTime)
  created!: Date;

  @FilterableField(() => GraphQLISODateTime)
  updated!: Date;

  // expose the todoItemId as a filterable field.
  @FilterableField()
  todoItemId!: string;
}

Relations​

note

This section only applies when you combine your DTO and entity and are using Typeorm or Sequelize

When your DTO and entity are the same class and you have relations defined, you should not decorate your the relations in the DTO with @Field or @FilterableField.

Instead decorate the class with @CursorConnection, @OffsetConnection, @UnPagedRelation or @Relation.

Example​

Assume you have the following subtask definition.

sub-task.ts
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  ManyToOne,
  JoinColumn,
} from 'typeorm';
import { ObjectType, ID } from '@nestjs/graphql';
import { FilterableField, IDField, Relation } from '@ptc-org/nestjs-query-graphql';
import { TodoItem } from '../todo-item/todo-item';

@ObjectType()
@Relation('todoItem', () => TodoItem, { update: { enabled: true } })
@Entity({ name: 'sub_task' })
export class SubTask {
  @IDField(() => ID)
  @PrimaryGeneratedColumn()
  id!: number;

  @FilterableField()
  @Column()
  title!: string;

  @FilterableField()
  @Column({ nullable: true })
  description?: string;

  @FilterableField()
  @Column()
  completed!: boolean;

  @FilterableField()
  @Column({ nullable: false, name: 'todo_item_id' })
  todoItemId!: string;

  // do not decorate with @Field
  @ManyToOne(() => TodoItem, (td) => td.subTasks, {
    onDelete: 'CASCADE',
    nullable: false,
  })
  @JoinColumn({ name: 'todo_item_id' })
  todoItem!: TodoItem;

  @FilterableField()
  @CreateDateColumn()
  created!: Date;

  @FilterableField()
  @UpdateDateColumn()
  updated!: Date;
}

Notice how the todoItem is not decorated with a field decorator, instead it is exposed through the @Relation decorator.