TypeOrmCrudService

A comprehensive service implementation for TypeORM that provides full CRUD operations with advanced querying capabilities

Overview

The TypeOrmCrudService is a powerful service class that extends the abstract CrudService and provides complete CRUD functionality for TypeORM entities. It handles complex querying, filtering, sorting, pagination, and relation management out of the box.

Basic Usage

The simplest way to use TypeOrmCrudService is to extend it in your service class:

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { TypeOrmCrudService } from '@nestjsx/crud-typeorm';
import { User } from './user.entity';

@Injectable()
export class UsersService extends TypeOrmCrudService<User> {
  constructor(@InjectRepository(User) repo) {
    super(repo);
  }
}

The TypeOrmCrudService automatically inherits all CRUD methods and doesn’t require any additional configuration for basic operations.

Constructor

repo · Repository<T> · required

The TypeORM repository instance for your entity. This is typically injected using @InjectRepository(Entity).

Properties

Protected Properties

dbName · DataSourceOptions['type']

The database type (e.g., ‘postgres’, ‘mysql’, ‘mariadb’). Automatically detected from the repository connection.

entityColumns · string[]

An array of all column names in the entity. Populated during initialization.

entityPrimaryColumns · string[]

An array of primary key column names. Used for entity identification.

entityHasDeleteColumn · boolean

Indicates whether the entity has a soft delete column. Enables soft delete functionality.

entityColumnsHash · ObjectLiteral

A hash map of entity columns for quick lookup and SQL injection prevention.

entityRelationsHash · Map<string, IAllowedRelation>

A cache of entity relations metadata for efficient join operations.

Public Methods

getMany

Retrieves multiple entities based on the request parameters.

public async getMany(req: CrudRequest): Promise<GetManyDefaultResponse<T> | T[]>

req · CrudRequest · required

The CRUD request object containing parsed query parameters and options.

return · GetManyDefaultResponse<T> | T[]

Returns either a paginated response with metadata or a plain array of entities.

Example:

const result = await usersService.getMany(req);
// With pagination:
// { data: [...], count: 10, total: 100, page: 1, pageCount: 10 }
// Without pagination:
// [...]

getOne

Retrieves a single entity based on the request parameters.

public async getOne(req: CrudRequest): Promise<T>

req · CrudRequest · required

The CRUD request object with search criteria.

return · T

Returns the found entity or throws a NotFoundException.

Example:

const user = await usersService.getOne(req);

createOne

Creates a single entity.

public async createOne(req: CrudRequest, dto: T | Partial<T>): Promise<T>

req · CrudRequest · required

The CRUD request object with options.

dto · T | Partial<T> · required

The data transfer object containing the entity data to create.

return · T

Returns the created entity, either as a shallow object or fully populated based on the returnShallow option.

Example:

const newUser = await usersService.createOne(req, {
  email: '[e-mail]',
  name: 'John Doe'
});

createMany

Creates multiple entities in bulk.

public async createMany(req: CrudRequest, dto: CreateManyDto<T | Partial<T>>): Promise<T[]>

req · CrudRequest · required

The CRUD request object.

dto · CreateManyDto<T | Partial<T>> · required

An object with a bulk property containing an array of entities to create.

return · T[]

Returns an array of created entities.

Example:

const users = await usersService.createMany(req, {
  bulk: [
    { email: '[e-mail]', name: 'User 1' },
    { email: '[e-mail]', name: 'User 2' }
  ]
});

Bulk creates are processed in chunks of 50 entities for optimal performance.

updateOne

Updates a single entity.

public async updateOne(req: CrudRequest, dto: T | Partial<T>): Promise<T>

req · CrudRequest · required

The CRUD request object with entity identification.

dto · T | Partial<T> · required

Partial entity data to update.

return · T

Returns the updated entity.

Example:

const updatedUser = await usersService.updateOne(req, {
  name: 'Jane Doe'
});

By default, path parameters cannot be overridden. Set allowParamsOverride: true in route options to change this behavior.

replaceOne

Replaces an entire entity (PUT operation).

public async replaceOne(req: CrudRequest, dto: T | Partial<T>): Promise<T>

req · CrudRequest · required

The CRUD request object.

dto · T | Partial<T> · required

Complete entity data to replace.

return · T

Returns the replaced entity.

Example:

const replacedUser = await usersService.replaceOne(req, {
  email: '[e-mail]',
  name: 'John Smith',
  age: 30
});

deleteOne

Deletes a single entity.

public async deleteOne(req: CrudRequest): Promise<void | T>

req · CrudRequest · required

The CRUD request object with entity identification.

return · void | T

Returns the deleted entity if returnDeleted is true, otherwise returns void.

Example:

await usersService.deleteOne(req);

Supports both hard delete and soft delete. When soft delete is enabled, the entity is marked as deleted but not removed from the database.

recoverOne

Recovers a soft-deleted entity.

public async recoverOne(req: CrudRequest): Promise<T>

req · CrudRequest · required

The CRUD request object identifying the soft-deleted entity.

return · T

Returns the recovered entity.

Example:

const recoveredUser = await usersService.recoverOne(req);

createBuilder

Creates a TypeORM QueryBuilder with all request parameters applied.

public async createBuilder(
  parsed: ParsedRequestParams,
  options: CrudRequestOptions,
  many = true,
  withDeleted = false
): Promise<SelectQueryBuilder<T>>

parsed · ParsedRequestParams · required

Parsed request parameters including filters, joins, sort, and pagination.

options · CrudRequestOptions · required

CRUD request options from the controller configuration.

many · boolean · default: "true"

Whether to apply pagination and sorting (for getMany) or not (for getOne).

withDeleted · boolean · default: "false"

Whether to include soft-deleted entities in the query.

return · SelectQueryBuilder<T>

A fully configured TypeORM SelectQueryBuilder instance.

Example:

const builder = await this.createBuilder(req.parsed, req.options);
const users = await builder.getMany();

Advanced Features

SQL Injection Protection

The service includes built-in SQL injection protection using regular expressions:

protected sqlInjectionRegEx: RegExp[] = [
  /(%27)|(\')|(--)|(%)|(#)/gi,
  /((%3D)|(=))[^\n]*((%27)|(\')|(--)|(%)|(;))/gi,
  /w*((%27)|(\')|(\')|(%4F))((%72)|r|(%52))/gi,
  /((%27)|(\')|(\')|(\'))union/gi,
];

Field names and values are automatically checked for SQL injection patterns. Invalid queries throw BadRequestException.

Query Operators

The service supports a comprehensive set of query operators:

Basic Operators:

• $eq - Equal to
• $ne - Not equal to
• $gt - Greater than
• $lt - Less than
• $gte - Greater than or equal to
• $lte - Less than or equal to

String Operators:

• $cont - Contains
• $excl - Excludes
• $starts - Starts with
• $ends - Ends with

Case-Insensitive Operators:

• $eqL - Equal (case-insensitive)
• $neL - Not equal (case-insensitive)
• $contL - Contains (case-insensitive)
• $startsL - Starts with (case-insensitive)
• $endsL - Ends with (case-insensitive)
• $exclL - Excludes (case-insensitive)

Array Operators:

• $in - In array
• $notin - Not in array
• $inL - In array (case-insensitive)
• $notinL - Not in array (case-insensitive)

Null Operators:

• $isnull - Is null
• $notnull - Is not null

Range Operators:

• $between - Between two values

Database-Specific Optimizations

The service automatically detects the database type and applies appropriate optimizations:

const likeOperator = this.dbName === 'postgres' ? 'ILIKE' : 'LIKE';

For MySQL and MariaDB, backticks are used for identifiers, while PostgreSQL uses double quotes.

Repository Access

Direct access to TypeORM repository methods:

public get findOne(): Repository<T>['findOne']
public get find(): Repository<T>['find']
public get count(): Repository<T>['count']

Example:

// Access the underlying repository
const count = await usersService.count({ where: { isActive: true } });
const user = await usersService.findOne({ where: { email: '[e-mail]' } });

Error Handling

The service provides consistent error handling:

• NotFoundException: Thrown when an entity is not found
• BadRequestException: Thrown for invalid data or SQL injection attempts

Example:

try {
  const user = await usersService.getOne(req);
} catch (error) {
  if (error instanceof NotFoundException) {
    // Handle not found
  }
}

See Also

• CrudService - Abstract base class
• Custom Service - Creating custom implementations