Whitelist and transform options in NestJS

Introduction

Whitelist and transform options help clean and shape data coming into your NestJS app. They make sure only allowed data is kept and convert data to the right types automatically.

When you want to accept only specific fields from user input to keep your app safe.

When you want to automatically convert strings to numbers or dates in incoming requests.

When you want to avoid unexpected or extra data that your app does not need.

When you want to simplify your code by letting NestJS handle data conversion.

When you want to protect your app from malicious or wrong data formats.

Syntax

NestJS

import { ValidationPipe } from '@nestjs/common';

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,
  transform: true,
}));

whitelist: Removes any properties that are not in your DTO (Data Transfer Object).

transform: Automatically converts input data to the types defined in your DTO classes.

Examples

This removes any extra fields not defined in your DTO but does not convert types.

NestJS

new ValidationPipe({ whitelist: true })

This converts input data types but keeps all fields, even extra ones.

NestJS

new ValidationPipe({ transform: true })

This removes extra fields and converts data types automatically.

NestJS

new ValidationPipe({ whitelist: true, transform: true })

This disables both features, so input is accepted as-is.

NestJS

new ValidationPipe({ whitelist: false, transform: false })

Sample Program

This NestJS app has a POST /users endpoint. It uses ValidationPipe with whitelist and transform options on the body. It only accepts 'name' and 'age' fields. It converts 'age' to a number automatically.

If extra fields are sent, they are removed. If 'age' is sent as a string like '25', it becomes the number 25.

NestJS

import { Controller, Post, Body, ValidationPipe } from '@nestjs/common';
import { IsInt, IsString } from 'class-validator';
import { NestFactory } from '@nestjs/core';
import { Module } from '@nestjs/common';

class CreateUserDto {
  @IsString()
  name: string;

  @IsInt()
  age: number;
}

@Controller('users')
class UserController {
  @Post()
  createUser(@Body(new ValidationPipe({ whitelist: true, transform: true })) createUserDto: CreateUserDto) {
    return createUserDto;
  }
}

@Module({
  controllers: [UserController],
})
class AppModule {}

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

bootstrap();

Important Notes

Time complexity: Validation and transformation run in linear time relative to input size.

Space complexity: Uses extra memory proportional to input size for creating new objects.

Common mistake: Forgetting to enable whitelist allows unwanted fields to pass through.

Use whitelist to keep data clean and transform to avoid manual type conversions.

Summary

Whitelist removes unwanted fields from input data.

Transform converts input data to the types defined in your DTO.

Using both together keeps your app safe and your data clean.