Complete Guide to Validating Arrays of Objects with Class-validator in NestJS

Introduction

In modern web application development, data validation is crucial for ensuring application robustness and security. Particularly when building enterprise applications with TypeScript and NestJS, the class-validator package provides a powerful decorator-driven validation mechanism. However, when dealing with complex data structures like arrays of objects, developers often encounter validation failures. This article, based on real development scenarios, provides a detailed analysis of how to correctly validate arrays containing specific numbers of objects.

Problem Context

Consider a common authentication scenario: users need to provide two authentication parameters during login, each containing id, type, and value fields. When defining validation rules with class-validator, the initial implementation might look like this:

import { IsString, IsNumber } from 'class-validator';

export class AuthParam {
  @IsNumber()
  id: number;

  @IsString()
  type: string;

  @IsString()
  value: string;
}

The corresponding array validation class might initially be defined as:

import { IsArray, ValidateNested } from 'class-validator';
import { AuthParam } from './authParam.model';

export class SignIn {
  @IsArray()
  @ValidateNested({ each: true })
  authParameters: AuthParam[];
}

While this implementation can validate whether each element in the array is of type AuthParam, it has two critical flaws: first, it cannot ensure the array contains exactly two elements; second, in some cases, validation might pass even if array elements are not AuthParam instances.

Solution

To address these issues, multiple decorators need to be combined. First, control array length using @ArrayMinSize and @ArrayMaxSize decorators:

import { IsArray, ValidateNested, ArrayMinSize, ArrayMaxSize } from 'class-validator';
import { AuthParam } from './authParam.model';

export class SignInModel {
  @IsArray()
  @ValidateNested({ each: true })
  @ArrayMinSize(2)
  @ArrayMaxSize(2)
  authParameters: AuthParam[];
}

However, this still isn't sufficient to ensure array elements are correctly validated as AuthParam types. The crucial step is introducing the @Type decorator:

import { IsArray, ValidateNested, ArrayMinSize, ArrayMaxSize } from 'class-validator';
import { AuthParam } from './authParam.model';
import { Type } from 'class-transformer';

export class SignInModel {
  @IsArray()
  @ValidateNested({ each: true })
  @ArrayMinSize(2)
  @ArrayMaxSize(2)
  @Type(() => AuthParam)
  authParameters: AuthParam[];
}

Technical Principles

The @Type decorator comes from the class-transformer package, and its role is to specify type transformation rules for nested objects. When class-validator validates nested objects, it needs to know how to transform plain JavaScript objects into specific class instances. Without the @Type decorator, the validator might not correctly recognize the AuthParam type, leading to validation failures or false passes.

The execution order of decorators is important: @IsArray first validates whether the property is an array, @ValidateNested({ each: true }) instructs the validator to perform nested validation on each element in the array, @ArrayMinSize(2) and @ArrayMaxSize(2) ensure the array length is exactly 2, and finally @Type(() => AuthParam) provides type transformation information.

Complete Example

Below is a complete NestJS controller example demonstrating how to use the above validation in a practical application:

import { Controller, Post, Body } from '@nestjs/common';
import { Validate } from 'class-validator';

@Controller('auth')
export class AuthController {
  @Post('signin')
  async signIn(@Body() signInData: SignInModel) {
    // Validation is automatically handled by NestJS pipes
    // If validation fails, a 400 error is automatically returned
    // After validation passes, signInData.authParameters will be an array of AuthParam instances
    const [param1, param2] = signInData.authParameters;
    console.log(param1.id, param1.type, param1.value);
    console.log(param2.id, param2.type, param2.value);
    
    // Process authentication logic
    return { success: true };
  }
}

Common Issues and Considerations

1. Ensure correct dependency installation: Besides class-validator, the class-transformer package also needs to be installed.

2. Error handling: When validation fails, class-validator throws exceptions containing detailed error information. In NestJS, these errors are typically handled through exception filters, returning structured error responses.

3. Performance considerations: For large arrays, nested validation might impact performance. In practical applications, validation strategies should be considered based on specific circumstances.

4. Compatibility with other validation decorators: Other decorators like @IsOptional, @IsDefined, etc., can be combined to implement more complex validation logic.

Conclusion

By reasonably combining decorators from class-validator and class-transformer, arrays containing specific numbers of objects can be effectively validated. The key is understanding the role of the @Type decorator in nested validation and the collaborative relationships between decorators. This pattern is not only applicable to authentication scenarios but can also be extended to any use case requiring validation of object arrays, providing a solid foundation for building robust TypeScript applications.