Understanding Pipes and Validation in NestJS

Mar 24, 2025 7 min

Understanding Pipes and Validation in NestJS

When building robust applications with NestJS, understanding how your data flows through the system is critical. In this post, we’ll dive deep into one of the most powerful features of NestJS: Pipes and Validation, and how they work with Data Transfer Objects (DTOs).

What Are Pipes in NestJS?

Pipes are special classes annotated with the @Injectable() decorator that implement the PipeTransform interface. They serve two primary purposes in your NestJS application:

  1. Transformation: Converting input data to the desired format
  2. Validation: Evaluating input data and potentially throwing exceptions if it fails validation rules

The Request/Response Lifecycle

To understand where pipes fit in, let’s first examine the complete request/response lifecycle in NestJS:

  1. Request: Initial HTTP request reaches your application
  2. Middleware: Processes the request before it reaches the route handler
    • Executes functions sequentially
    • Can modify request/response objects
    • Can end request-response cycle
  3. Filters Start: Exception handling begins
    • Processes all exceptions
    • Can catch and handle errors
  4. Guards: Handle authorization
    • Determine if the request should proceed
    • Usually handle authentication/permissions
    • Return true/false or throw exception
  5. Interceptors (Pre-Controller):
    • Bind extra logic before/after method execution
    • Transform result from method
    • Transform exception from method
    • Extend basic method behavior
  6. Pipes: Handle data transformation/validation
    • Transform input data
    • Validate input data
    • Can throw exceptions
  7. Controller: Route handler execution
    • Processes request
    • Returns response data
  8. Interceptors (Post-Controller):
    • Handle response data
    • Can transform response
    • Add response headers/metadata
  9. Filters End: Final exception handling
    • Process any remaining exceptions
    • Format error responses
  10. Response: Final HTTP response sent to client

As you can see, pipes are executed right before the controller method is invoked, making them perfect for ensuring your controller only receives properly formatted and validated data.

Types of Pipes

NestJS provides two types of pipes:

1. Built-in Pipes

These are ready-to-use pipes provided by NestJS:

  • ValidationPipe: Validates the data against predefined schemas or DTOs
  • ParseIntPipe: Transforms string inputs into integers
  • ParseFloatPipe: Transforms string inputs into floating-point numbers
  • ParseBoolPipe: Transforms string inputs into boolean values
  • ParseArrayPipe: Transforms string inputs into arrays
  • ParseUUIDPipe: Validates that a string is a UUID
  • ParseEnumPipe: Ensures a parameter is a valid value from an enum
  • DefaultValuePipe: Provides a default value if none is supplied

2. Custom Pipes

You can create your own pipes to handle specific transformation or validation logic unique to your application.

Using Validation Pipes

The ValidationPipe is particularly powerful when combined with Data Transfer Objects (DTOs) and class-validator decorators:

import {
  Controller,
  Post,
  Body,
  UsePipes,
  ValidationPipe,
} from "@nestjs/common";
import { CreateUserDto } from "./dto/create-user.dto";

@Controller("users")
export class UsersController {
  @Post()
  @UsePipes(new ValidationPipe())
  create(@Body() createUserDto: CreateUserDto) {
    // With ValidationPipe, you can be confident that createUserDto
    // contains valid data that matches your DTO definition
    return this.usersService.create(createUserDto);
  }
}

Where to Apply Pipes

NestJS offers multiple levels where you can apply pipes:

  1. Parameter-level: Apply pipes to specific parameters

    @Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  return this.usersService.findOne(id);
}

  2. Handler-level: Apply pipes to all parameters of a route handler

    @Post()
@UsePipes(new ValidationPipe())
create(@Body() createUserDto: CreateUserDto) {
  // ...
}

  3. Controller-level: Apply pipes to all handlers in a controller

    @Controller("users")
@UsePipes(new ValidationPipe())
export class UsersController {
  // ...
}

  4. Global-level: Apply pipes to every route handler across the entire application

    // main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  await app.listen(3000);
}
bootstrap();

Building Custom Pipes

When the built-in pipes don’t meet your needs, you can create custom pipes. Here’s a simple example:

import {
  PipeTransform,
  Injectable,
  ArgumentMetadata,
  BadRequestException,
} from "@nestjs/common";

@Injectable()
export class PositiveIntPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    const val = parseInt(value, 10);
    if (isNaN(val) || val <= 0) {
      throw new BadRequestException(
        "Validation failed: value must be a positive integer"
      );
    }
    return val;
  }
}

You would then use this custom pipe just like the built-in ones:

@Get(':id')
findOne(@Param('id', PositiveIntPipe) id: number) {
  return this.usersService.findOne(id);
}

Best Practices for Using Pipes

  1. Apply validation at the appropriate level: Choose the right scope for your pipes based on your application’s needs.
  2. Create reusable custom pipes: Build custom pipes that can be reused across your application.
  3. Combine pipes with DTOs: Use class-validator decorators in your DTOs for robust validation.
  4. Transform early: Convert strings to their appropriate types as early as possible in the request lifecycle.
  5. Provide meaningful error messages: When validation fails, ensure your error messages clearly explain what went wrong.

Understanding DTOs in NestJS

What is a DTO?

DTO (Data Transfer Object) is a design pattern specifically used to transfer data between different layers of your application. In NestJS, DTOs are primarily used to define the structure of data that will be transferred between the controller and the service layer.

Why Use DTOs?

  1. Type Safety: DTOs provide clear type definitions for the data being passed around.
  2. Data Validation: When combined with validation pipes, DTOs ensure that incoming data meets specific criteria.
  3. Documentation: DTOs effectively document the expected input and output structures of your API.
  4. Separation of Concerns: They help separate the data transfer logic from business logic.

Implementing DTOs in NestJS

NestJS leverages two powerful libraries to make DTOs even more effective:

  1. class-validator: For validating the data against defined rules
  2. class-transformer: For transforming the data between plain objects and class instances

Here’s an example of a simple DTO:

import { IsString, IsEmail, IsNotEmpty, MinLength } from "class-validator";

export class CreateUserDto {
  @IsNotEmpty()
  @IsString()
  readonly name: string;

  @IsEmail()
  readonly email: string;

  @IsString()
  @MinLength(8)
  readonly password: string;
}

Combining DTOs with Pipes

The real power comes when you combine DTOs with NestJS’s ValidationPipe:

@Post()
async create(@Body(new ValidationPipe()) createUserDto: CreateUserDto) {
  return this.usersService.create(createUserDto);
}

With this setup, NestJS will:

  1. Receive the incoming request
  2. Transform the JSON payload into an instance of the CreateUserDto class (using class-transformer)
  3. Validate the data against the decorators defined in the DTO (using class-validator)
  4. If validation fails, throw an exception before the controller method is called
  5. If validation passes, provide the controller with a properly typed and validated DTO object

Global Validation

For a more streamlined approach, you can set up global validation in your main.ts file:

import { ValidationPipe } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true, // Remove non-whitelisted properties
      forbidNonWhitelisted: true, // Throw errors if non-whitelisted properties are present
      transform: true, // Automatically transform payloads to be objects typed according to their DTO classes
    })
  );

  await app.listen(3000);
}
bootstrap();

Conclusion

Pipes and DTOs work hand in hand in NestJS to ensure your application only processes valid, properly formatted data. By using DTOs to define the structure of your data and pipes to validate and transform it, you can build more robust, error-resistant applications while keeping your controllers focused on their primary responsibilities.

Whether you’re using the built-in pipes or creating custom ones, properly implemented pipes with well-defined DTOs will significantly improve the reliability, type safety, and maintainability of your NestJS applications.

~James Best