This is a Typescript library that provides a NestJS decorator which automatically generates CRUD routes of a controller for given TypeORM entity. The decorator generates endpoints for not only create, retrieve one, retrieve many, update, delete but also upsert, recover and search operations for the entity.
- Automatically generates CRUD routes for a given TypeORM entity
- Automatically generates swagger for generated routes
- Supports pagination, sorting, filtering, relation, searching, upserting, recovering and soft deleting
- Supports complex search criteria(
LIKE,ILIKE,BETWEEN,IN,NULL,?,@>,JSON_CONTAINS) - Supports strong validation by using class-validator
- Supports saving author information for mutating operations(Create, Update, Upsert, Delete and Recover)
- Supports adding decorators, interceptors to each routes in Controller for customizing
- Supports customizing swagger response
# npm
npm install @nestjs-library/crud
# yarn
yarn add @nestjs-library/crud
# pnpm
pnpm add @nestjs-library/crudIn order to use the Crud decorator, you need to define a TypeORM entity first. The following example defines a User entity with the following properties.
import { BaseEntity, Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
@Entity()
export class User extends BaseEntity {
@PrimaryGeneratedColumn()
id: number;
@Column()
username: string;
@Column()
email: string;
}Create a NestJS service and controller with a TypeORM entity. The service needs to extend the CrudService class and the controller needs to implement the CrudController interface.
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { CrudService } from '@nestjs-library/crud';
import { Repository } from 'typeorm';
import { User } from './user.entity';
@Injectable()
export class UserService extends CrudService<User> {
constructor(@InjectRepository(User) repository: Repository<User>) {
super(repository);
}
}import { Controller } from '@nestjs/common';
import { Crud, CrudController } from '@nestjs-library/crud';
import { User } from './user.entity';
import { UserService } from './user.service';
@Crud({ entity: User })
@Controller('users')
export class UserController implements CrudController<User> {
constructor(public readonly crudService: UserService) {}
}In your NestJS module, add Service, Controller and TypeORM module to providers, controllers, imports array respectively.
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './user.entity';
import { UserController } from './user.controller';
import { UserService } from './user.service';
@Module({
imports: [TypeOrmModule.forFeature([User])],
controllers: [UserController],
providers: [UserService],
})
export class UserModule {}After the module initializes, it will generate the following CRUD endpoints:
GET /users- retrieves a list of users with paginationGET /users/:id- retrieves a single user by IDPOST /users- creates single or multiple usersPATCH /users/:id- updates an existing user by IDDELETE /users/:id- deletes an existing user by IDPUT /users/:id- upserts (update or create) an existing user by IDPOST /users/search- retrieves a list of users based on complex search criteriaPOST /users/:id/recover- recovers a soft deleted user by ID
The Crud decorator supports the following configuration options:
(required) The TypeORM entity that the controller operates on.
(optional) You can configure each route by specifying the routes option.
For example, if you want to set the default pagination size for a search route, you can specify option as below.
@Crud({
entity: User,
routes: {
search: { numberOfTake: 5 },
},
})Every route has the following base options.
import { NestInterceptor, Type } from '@nestjs/common';
interface RouteBaseOption {
decorators?: Array<PropertyDecorator | MethodDecorator>;
interceptors?: Array<Type<NestInterceptor>>;
swagger?: {
hide?: boolean;
response?: Type<unknown>;
};
exclude?: string[];
}CREATE, UPDATE, DELETE, UPSERT, and RECOVER routes can have the following options.
interface SaveOptions {
listeners?: boolean;
}And each route has its own options as below.
interface ReadOneOptions {
params?: string[];
softDelete?: boolean;
relations?: false | string[];
}import { Sort, PaginationType } from 'src/lib/interface';
interface ReadManyOptions {
sort?: Sort | `${Sort}`;
paginationType?: PaginationType | `${PaginationType}`;
numberOfTake?: number;
relations?: false | string[];
softDelete?: boolean;
paginationKeys?: string[];
}import { PaginationType } from 'src/lib/interface';
interface SearchOptions {
paginationType?: PaginationType | `${PaginationType}`;
numberOfTake?: number;
limitOfTake?: number;
relations?: false | string[];
softDelete?: boolean;
paginationKeys?: string[];
}import { Type } from '@nestjs/common';
import { Author } from 'src/lib/interface';
interface CreateOptions {
swagger?: {
body?: Type<unknown>;
};
author?: Author;
}import { Type } from '@nestjs/common';
import { Author } from 'src/lib/interface';
interface UpdateOptions {
params?: string[];
swagger?: {
body?: Type<unknown>;
};
author?: Author;
}import { Author } from 'src/lib/interface';
interface DeleteOptions {
params?: string[];
softDelete?: boolean;
author?: Author;
}interface UpsertOptions {
params?: string[];
swagger?: {
body?: Type<unknown>;
};
author?: Author;
}interface RecoverOptions {
params?: string[];
author?: Author;
}(optional) An array of methods to generate routes for. If not specified, all routes will be generated.
For example, if you want to generate only create and retrieve one, you can specify the following configuration.
import { Crud, Method } from '@nestjs-library/crud';
@Crud({ entity: User, only: [Method.CREATE, Method.READ_ONE] })This library is licensed under the MIT License. See the LICENSE file for details.