nestjs-url-dto

Universal parameter validation for NestJS using DTOs with class-validator.

Installation

npm install nestjs-url-dto

Quick Start

1. Create your parameter DTO

import { IsNotEmpty, IsNumber, IsPositive, Transform } from 'class-validator';

export class UserIdDto {
  @IsNotEmpty({ message: 'User ID is required' })
  @Transform(({ value }) => parseInt(value))
  @IsNumber({}, { message: 'User ID must be a number' })
  @IsPositive({ message: 'User ID must be positive' })
  value: number; //only value

  constructor(data: any) {
    this.value = data;
  }
}

2. Use in your controller

import { Controller, Get } from '@nestjs/common';
import { ParamDto } from 'nestjs-url-dto';
import { UserIdDto } from './dto/user-id.dto';

@Controller('users')
export class UsersController {
  @Get(':id')
  findOne(@ParamDto(UserIdDto, 'id') id: number) {
    // id is automatically validated and transformed to number
    return this.usersService.findOne(id);
  }
}

Features

• ✅ Type Safety - Full TypeScript support
• ✅ Reusable DTOs - Create once, use everywhere
• ✅ Automatic Validation - Built-in class-validator integration
• ✅ Custom Error Messages - Define your own validation messages
• ✅ Transformation - Automatic string to number/boolean conversion

API Reference

ParamDto<T>(dtoClass, paramName)

Custom parameter decorator that validates route parameters using DTO classes.

Parameters:

• dtoClass - DTO class constructor
• paramName - Name of the parameter to extract from the route

Returns: Parameter decorator that validates and transforms the parameter

Examples

Numeric Parameters

export class ClanIdDto {
  @IsNotEmpty()
  @Transform(({ value }) => parseInt(value))
  @IsNumber()
  @IsPositive()
  @Max(999999)
  value: number;

  constructor(data: any) {
    this.value = data;
  }
}

@Get(':clanId')
findClan(@ParamDto(ClanIdDto, 'clanId') clanId: number) {
  return this.clanService.findOne(clanId);
}

String Parameters

export class UsernameDto {
  @IsNotEmpty()
  @IsString()
  @Length(3, 20)
  @Matches(/^[a-zA-Z0-9_]+$/)
  value: string;

  constructor(data: any) {
    this.value = data;
  }
}

@Get('profile/:username')
findProfile(@ParamDto(UsernameDto, 'username') username: string) {
  return this.profileService.findByUsername(username);
}

Boolean Parameters

export class ActiveDto {
  @IsNotEmpty()
  @IsBooleanString()
  @Transform(({ value }) => value === 'true')
  value: boolean;

  constructor(data: any) {
    this.value = data;
  }
}

@Get('users/:active')
getUsers(@ParamDto(ActiveDto, 'active') active: boolean) {
  return this.usersService.findByActive(active);
}

Error Handling

When validation fails, the pipe throws a BadRequestException with detailed error messages:

{
  "statusCode": 400,
  "message": "Validation failed: User ID must be a positive number",
  "error": "Bad Request"
}

Migration from Standard @Param

Before (Standard NestJS)

@Get(':id')
findOne(@Param('id') id: string) {
  const numericId = parseInt(id);
  if (isNaN(numericId) || numericId <= 0) {
    throw new BadRequestException('Invalid ID');
  }
  return this.service.findOne(numericId);
}

After (With this library)

@Get(':id')
findOne(@ParamDto(UserIdDto, 'id') id: number) {
  // id is already validated and transformed
  return this.service.findOne(id);
}

License

MIT License