Mastering Validation in TypeScript with class-validator – A Complete Beginner's Guide

Learn how to validate user input in TypeScript and NestJS using class-validator. This in-depth tutorial covers everything from basic usage to advanced decorators, real-world use cases, and integration with NestJS — all optimized for clean code, security, and SEO.

📌 Table of Contents

1. What is class-validator?
2. Why Input Validation Matters
3. Installation
4. Basic Example: Email and Password Validation
5. Popular Validation Decorators
6. Advanced Validation: Arrays, Enums, Dates
7. Nested Object Validation
8. Conditional Validation with @ValidateIf
9. Custom Validators
10. Full Integration with NestJS
11. Common Pitfalls and Mistakes
12. Final Takeaways
13. Connect with Me

🧠 What is class-validator?

class-validator is a powerful library that allows you to use decorators to validate TypeScript class properties. It's most commonly used with frameworks like NestJS or in pure Node.js apps to enforce runtime validation.

❗ Why Input Validation Matters

• 🔐 Prevents invalid or malicious data
• 🧼 Ensures clean, predictable input
• 📉 Reduces bugs in business logic
• 🔧 Improves API documentation and usability

⚙️ Installation

Install it along with class-transformer:

npm install class-validator class-transformer 

🧪 Basic Example: Email and Password Validation

import { IsEmail, MinLength } from 'class-validator'; export class CreateUserDto { @IsEmail() email: string; @MinLength(6) password: string; } 

import { validate } from 'class-validator'; const user = new CreateUserDto(); user.email = 'wrong-format'; user.password = '123'; const errors = await validate(user); console.log(errors); // -> array of error messages 

📋 Popular Validation Decorators

💡 Advanced Validation: Arrays, Enums, Dates

Validate Arrays

@IsArray() @IsInt({ each: true }) scores: number[]; 

Validate Enums

enum Role { USER = 'user', ADMIN = 'admin' } @IsEnum(Role) role: Role; 

Validate Dates

@IsDate() @MinDate(new Date()) joinDate: Date; 

🧱 Nested Object Validation

class Profile { @IsString() bio: string; } class User { @ValidateNested() @Type(() => Profile) profile: Profile; } 

Always include @Type() from class-transformer, or validation will silently fail.

⚖️ Conditional Validation with @ValidateIf

@ValidateIf(o => o.age > 18) @IsString() licenseNumber: string; 

This only validates licenseNumber if age > 18.

🔧 Custom Validators

@ValidatorConstraint({ name: 'IsStrongPassword', async: false }) class IsStrongPassword implements ValidatorConstraintInterface { validate(value: string) { return value.length >= 8 && /[A-Z]/.test(value); } defaultMessage() { return 'Password must have at least 8 characters and one uppercase letter.'; } } 

Use it like this:

@Validate(IsStrongPassword) password: string; 

🚀 Full Integration with NestJS

main.ts Setup

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

Sample DTO and Controller

// create-user.dto.ts export class CreateUserDto { @IsEmail() email: string; @MinLength(6) password: string; @IsOptional() @IsInt() @Min(18) age?: number; } 

// users.controller.ts @Post() create(@Body() dto: CreateUserDto) { return this.userService.create(dto); } 

NestJS will automatically:

• Validate the body
• Convert string to numbers if needed
• Throw 400 Bad Request on validation failure

❌ Common Pitfalls and Mistakes

1. Forgetting @Type() in Nested DTOs

@ValidateNested() profile: Profile; // ❌ Will not validate // ✅ Fix: @ValidateNested() @Type(() => Profile) profile: Profile; 

2. Wrong Order of Decorators

@IsEmail() @IsNotEmpty() email: string; // Runs bottom-up: IsNotEmpty first, then IsEmail 

Always order carefully if decorators depend on each other.

3. Not Using plainToInstance()

const user = plainToInstance(CreateUserDto, req.body); await validate(user); 

Without this, validation may silently fail if using plain JS objects.

✅ Final Takeaways

• Use @IsOptional() when fields aren't required
• Always use @Type() in nested objects
• Use ValidationPipe in NestJS for automatic validation
• Validate arrays with { each: true }
• Use custom validators for complex business rules

🔄 What About Zod?

While this guide focuses on class-validator, many developers also consider zod for validating data in TypeScript. If you're wondering how it compares, here’s a quick breakdown to help you choose the best tool for your needs:

🥊 class-validator vs Zod: Which Should You Use?

✅ When to Use class-validator

• You're using NestJS
• You prefer OOP and decorators
• You need class-transformer for serialization
• Your architecture uses DTO classes

⚡ When to Use Zod

• You're building with functional programming style
• You're using tRPC, Express, or Fastify
• You want fast runtime validation and type inference
• You prefer schema-based design

🧠 Final Word

Both libraries are excellent. Your choice depends on:

• Your framework (NestJS vs Express/tRPC)
• Your programming style (OOP vs functional)
• Your team’s preference for decorators vs schemas

If you prefer decorators and structured classes, go with class-validator.

If you prefer schema inference and functional composition, go with zod.

🙌 Connect with Me

If this helped you, please:

• 📚 Official Repo: github.com/typestack/class-validator

• 📬 Share your thoughts in comments

• 🔗 Connect with me on LinkedIn

Want a quick reference? I’m posting a class-validator cheatsheet next! Follow me to stay updated.