NestJS Pipes Pattern

NestJS Pipes Pattern

Validate and transform request data with PipeTransform, ValidationPipe, and custom pipes

When to Use

• You need to validate incoming request bodies against a DTO class
• You need to transform a string route parameter to a number, UUID, boolean, or enum
• You want validation to run automatically on all routes without per-handler boilerplate
• You are building a custom transformation (e.g., trim strings, normalize phone numbers)

Instructions

1. Enable ValidationPipe globally in main.ts (recommended for most applications):

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true, // strip properties not in DTO
    forbidNonWhitelisted: true, // throw on extra properties
    transform: true, // auto-transform payload to DTO class instance
    transformOptions: { enableImplicitConversion: true },
  })
);

2. Use built-in transformation pipes as inline pipe arguments:

@Get(':id')
findOne(@Param('id', ParseUUIDPipe) id: string) { ... }

@Get(':page')
list(@Query('page', ParseIntPipe) page: number) { ... }

@Param('status', new ParseEnumPipe(UserStatus)) status: UserStatus

3. Define DTO classes with class-validator decorators:

import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

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

  @IsOptional()
  @IsString()
  displayName?: string;
}

4. Custom pipe — implement PipeTransform<T, R>:

@Injectable()
export class TrimPipe implements PipeTransform<string, string> {
  transform(value: string): string {
    if (typeof value !== 'string') return value;
    return value.trim();
  }
}

5. Apply custom pipes at the parameter level: @Body('name', TrimPipe) name: string.

6. For pipes that may fail (e.g., parsing), throw BadRequestException rather than returning null.

Details

Pipes serve two roles: validation (throw if invalid) and transformation (convert to the expected type). Both happen before the handler executes.

whitelist: true behavior: ValidationPipe strips any property on the incoming JSON that has no corresponding decorator in the DTO. This prevents mass-assignment attacks where clients send unexpected fields (e.g., isAdmin: true). forbidNonWhitelisted: true goes further and throws a 400 if any extra property is present.

transform: true: Without this, @Body() dto: CreateUserDto gives you a plain object, not a CreateUserDto instance. With it, NestJS runs class-transformer's plainToInstance automatically so you get a proper class instance and @Type() decorators work correctly.

Class-validator integration: All class-validator decorators (@IsEmail(), @IsUUID(), @IsEnum(), @Min(), @Max(), etc.) work with ValidationPipe. Nested DTOs require @ValidateNested() combined with @Type(() => NestedDto).

Scope: Pipes can be applied at four levels (most specific wins):

1. Global — app.useGlobalPipes()
2. Controller — @UsePipes()
3. Method — @UsePipes()
4. Parameter — inline in @Param('id', ParseUUIDPipe)

Async pipes: transform() can return Promise<R>. This enables async validation (e.g., checking a database for uniqueness), though this is better done at the service layer.

Source

https://docs.nestjs.com/pipes

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.