@Crud

Class decorator that generates RESTful CRUD endpoints for a controller

Overview

The @Crud decorator is a class decorator that automatically generates RESTful CRUD endpoints for your NestJS controller. It provides a complete set of routes for Create, Read, Update, and Delete operations with extensive customization options.

Signature

export const Crud = (options: CrudOptions) => (target: unknown): void

Parameters

options · CrudOptions · required

Configuration object for CRUD operations

model · ModelOptions · required

Model configuration

type · any · required

The entity class/type to use for CRUD operations

dto · DtoOptions

Data Transfer Object configuration for create and update operations

serialize · SerializeOptions

Serialization options for responses

query · QueryOptions

Query configuration options

allow · QueryFields

Fields allowed in queries

exclude · QueryFields

Fields excluded from queries

persist · QueryFields

Fields to persist in all queries

filter · QueryFilterOption

Default filter conditions

join · JoinOptions

Relation join options

sort · QuerySort[]

Default sort configuration

limit · number

Default limit for pagination

maxLimit · number

Maximum allowed limit

cache · number | false

Cache duration in milliseconds, or false to disable

alwaysPaginate · boolean

Always return paginated responses

softDelete · boolean

Enable soft delete functionality

routes · RoutesOptions

Route-specific configuration

exclude · BaseRouteName[]

Routes to exclude from generation. Available routes: getManyBase, getOneBase, createOneBase, createManyBase, updateOneBase, replaceOneBase, deleteOneBase, recoverOneBase

only · BaseRouteName[]

Only generate these routes

getManyBase · GetManyRouteOptions

Options for the get many route

getOneBase · GetOneRouteOptions

Options for the get one route

createOneBase · CreateOneRouteOptions

Options for the create one route

createManyBase · CreateManyRouteOptions

Options for the create many route

updateOneBase · UpdateOneRouteOptions

Options for the update one route

replaceOneBase · ReplaceOneRouteOptions

Options for the replace one route

deleteOneBase · DeleteOneRouteOptions

Options for the delete one route

recoverOneBase · RecoverOneRouteOptions

Options for the recover one route (soft delete)

params · ParamsOptions

URL parameter configuration

Each key is the parameter name, and the value is a ParamOption object with:

field · string

Entity field name to map to

type · ParamOptionType

Parameter type (e.g., ‘number’, ‘string’, ‘uuid’)

enum · SwaggerEnumType

Enum type for parameter validation

primary · boolean

Whether this is a primary key parameter

disabled · boolean

Disable this parameter

routesFactory · typeof CrudRoutesFactory

Custom routes factory class for advanced customization

validation · ValidationPipeOptions | false

Validation pipe options, or false to disable validation

Usage

Basic Example

import { Controller } from '@nestjs/common';
import { Crud } from '@nestjsx/crud';
import { User } from './user.entity';
import { UserService } from './user.service';

@Crud({
  model: { type: User },
})
@Controller('users')
export class UserController {
  constructor(public service: UserService) {}
}

This generates the following endpoints:

• GET /users - Get many users
• GET /users/:id - Get one user
• POST /users - Create one user
• POST /users/bulk - Create many users
• PATCH /users/:id - Update one user
• PUT /users/:id - Replace one user
• DELETE /users/:id - Delete one user

Advanced Configuration

@Crud({
  model: { type: User },
  query: {
    limit: 10,
    maxLimit: 100,
    alwaysPaginate: true,
    sort: [{ field: 'createdAt', order: 'DESC' }],
    join: {
      profile: {
        eager: true,
        allow: ['firstName', 'lastName'],
      },
      posts: {
        alias: 'userPosts',
      },
    },
  },
  routes: {
    exclude: ['createManyBase', 'replaceOneBase'],
    deleteOneBase: {
      returnDeleted: true,
    },
  },
  params: {
    id: {
      field: 'id',
      type: 'uuid',
      primary: true,
    },
  },
})
@Controller('users')
export class UserController {
  constructor(public service: UserService) {}
}

With Custom Parameters

@Crud({
  model: { type: Post },
  params: {
    userId: {
      field: 'userId',
      type: 'number',
    },
    status: {
      field: 'status',
      type: 'string',
      enum: PostStatus,
    },
  },
})
@Controller('users/:userId/posts/:status')
export class PostController {
  constructor(public service: PostService) {}
}

Generated Routes

The decorator automatically generates the following base routes:

Route Name	HTTP Method	Path	Description
getManyBase	GET	/	Retrieve multiple entities
getOneBase	GET	/:id	Retrieve single entity
createOneBase	POST	/	Create single entity
createManyBase	POST	/bulk	Create multiple entities
updateOneBase	PATCH	/:id	Update single entity
replaceOneBase	PUT	/:id	Replace single entity
deleteOneBase	DELETE	/:id	Delete single entity
recoverOneBase	PATCH	/:id/recover	Recover soft-deleted entity

The recoverOneBase route is only generated when query.softDelete is enabled.

Implementation Details

The decorator uses a routes factory pattern to generate the endpoints. The source code shows:

packages/crud/src/decorators/crud.decorator.ts:4-9

export const Crud =
  (options: CrudOptions) =>
  (target: unknown): void => {
    const factoryMethod = options.routesFactory || CrudRoutesFactory;
    const factory = new factoryMethod(target, options);
  };

The controller must have a service property that implements the CRUD service interface. This service is used by the generated routes to perform database operations.

See Also

• @CrudAuth - Add authentication and authorization
• @Override - Override generated routes
• @ParsedRequest - Access parsed request data