Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nestjsx/crud/llms.txt

Use this file to discover all available pages before exploring further.

The ParamsOptions interface allows you to configure URL path parameters used in CRUD operations, including their types, validation, and mapping to entity fields.

​
Interface Definition

export interface ParamsOptions {
  [key: string]: ParamOption;
}

export interface ParamOption {
  field?: string;
  type?: ParamOptionType;
  enum?: SwaggerEnumType;
  primary?: boolean;
  disabled?: boolean;
}

​
Structure

ParamsOptions is a key-value object where:
  • Key: The parameter name as it appears in the URL (e.g., id, userId, companyId)
  • Value: A ParamOption object that configures how that parameter behaves

​
ParamOption Properties

​
field
string
The entity field name that this parameter maps to.
params: {
  id: {
    field: 'id', // Maps to the 'id' field in the entity
    type: 'uuid',
    primary: true,
  }
}
If not specified, defaults to the parameter name.
​
type
ParamOptionType
The data type of the parameter for validation and parsing.Common values:
  • 'number': Numeric ID
  • 'uuid': UUID string
  • 'string': Generic string
params: {
  id: { type: 'uuid', primary: true },
  companyId: { type: 'number' },
}
​
enum
SwaggerEnumType
Enum type for Swagger documentation and validation.
enum Status {
  Active = 'active',
  Inactive = 'inactive',
}

params: {
  status: {
    field: 'status',
    enum: Status,
  }
}
This will generate proper enum documentation in Swagger and validate that the parameter matches one of the enum values.
​
primary
boolean
Indicates whether this parameter represents the primary key.
params: {
  id: {
    field: 'id',
    type: 'uuid',
    primary: true, // This is the primary key
  }
}
The primary parameter is used for single-record operations (getOne, updateOne, deleteOne, etc.).
​
disabled
boolean
If true, this parameter is disabled and won’t be used in queries.
params: {
  userId: {
    disabled: true, // Don't use this parameter
  }
}

​
Usage Examples

​
Basic UUID Primary Key

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

@Crud({
  model: { type: User },
  params: {
    id: {
      field: 'id',
      type: 'uuid',
      primary: true,
    },
  },
})
@Controller('users')
export class UsersController {}
Generates routes like:
  • GET /users/:id
  • PATCH /users/:id
  • DELETE /users/:id

​
Numeric Primary Key

@Crud({
  model: { type: Product },
  params: {
    id: {
      field: 'id',
      type: 'number',
      primary: true,
    },
  },
})
@Controller('products')
export class ProductsController {}

​
Composite Parameters (Nested Resources)

@Crud({
  model: { type: Post },
  params: {
    userId: {
      field: 'userId',
      type: 'number',
    },
    id: {
      field: 'id',
      type: 'number',
      primary: true,
    },
  },
})
@Controller('users/:userId/posts')
export class PostsController {}
Generates routes like:
  • GET /users/:userId/posts
  • GET /users/:userId/posts/:id
  • POST /users/:userId/posts
  • PATCH /users/:userId/posts/:id

​
Custom Field Mapping

@Crud({
  model: { type: Article },
  params: {
    slug: {
      field: 'urlSlug', // URL parameter 'slug' maps to entity field 'urlSlug'
      type: 'string',
      primary: true,
    },
  },
})
@Controller('articles')
export class ArticlesController {}
Generates routes like:
  • GET /articles/:slug (uses urlSlug field for lookup)

​
Enum Parameters

enum UserRole {
  Admin = 'admin',
  User = 'user',
  Guest = 'guest',
}

@Crud({
  model: { type: User },
  params: {
    role: {
      field: 'role',
      type: 'string',
      enum: UserRole,
    },
    id: {
      field: 'id',
      type: 'uuid',
      primary: true,
    },
  },
})
@Controller('users/:role')
export class UsersController {}

​
Disabled Parameters

@Crud({
  model: { type: Order },
  params: {
    userId: {
      field: 'userId',
      type: 'number',
      disabled: true, // Present in URL but not used in queries
    },
    id: {
      field: 'id',
      type: 'uuid',
      primary: true,
    },
  },
})
@Controller('users/:userId/orders')
export class OrdersController {}

​
ParamOptionType

The ParamOptionType from @nestjsx/crud-request typically includes: 
type ParamOptionType = 'number' | 'string' | 'uuid';
  • 'number': Validates and parses as a number
  • 'string': Treats as a string (no parsing)
  • 'uuid': Validates UUID format

​
Notes

If you don’t specify a field property, the parameter name will be used as the field name. For example, params: { id: { type: 'uuid', primary: true } } assumes the entity has an id field.
Make sure your route path matches your parameter configuration. If you define a parameter userId in params, your controller route should include :userId in the path.
// Correct
@Controller('users/:userId/posts')

// Incorrect - missing :userId in path
@Controller('users/posts')

CrudOptions

Main CRUD configuration

ModelOptions

Configure entity model

Build docs developers (and LLMs) love

Get started for freeTalk to us