Skip to main content
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