Benutzerdefinierte Validatoren und asynchrone Constraints

Why Custom Validators?

Anatomy of a ValidatorConstraint

import {
  ValidatorConstraint,
  ValidatorConstraintInterface,
  ValidationArguments,
} from 'class-validator';

@ValidatorConstraint({ name: 'isStrongPassword', async: false })
export class IsStrongPasswordConstraint
  implements ValidatorConstraintInterface
{
  validate(value: string, _args: ValidationArguments): boolean {
    if (typeof value !== 'string') return false;
    const hasUpper = /[A-Z]/.test(value);
    const hasDigit = /[0-9]/.test(value);
    return value.length >= 8 && hasUpper && hasDigit;
  }

  defaultMessage(args: ValidationArguments): string {
    return `${args.property} must be 8+ chars with an uppercase letter and a digit`;
  }
}

Wrapping It in a Decorator

import { registerDecorator, ValidationOptions } from 'class-validator';
import { IsStrongPasswordConstraint } from './is-strong-password.constraint';

export function IsStrongPassword(options?: ValidationOptions) {
  return function (object: object, propertyName: string) {
    registerDecorator({
      target: object.constructor,
      propertyName,
      options,
      constraints: [],
      validator: IsStrongPasswordConstraint,
    });
  };
}

// Usage in a DTO:
// class CreateUserDto {
//   @IsStrongPassword()
//   password: string;
// }

The Pure Logic Is Testable

function isStrongPassword(value: string): boolean {
  if (typeof value !== 'string') return false;
  const hasUpper = /[A-Z]/.test(value);
  const hasDigit = /[0-9]/.test(value);
  return value.length >= 8 && hasUpper && hasDigit;
}

const cases = ['abc', 'alllowercase1', 'Short1', 'GoodPass99'];
for (const c of cases) {
  console.log(`${c.padEnd(15)} -> ${isStrongPassword(c)}`);
}

Passing Arguments to a Constraint

import {
  registerDecorator,
  ValidationOptions,
  ValidatorConstraint,
  ValidatorConstraintInterface,
  ValidationArguments,
} from 'class-validator';

@ValidatorConstraint({ name: 'match', async: false })
export class MatchConstraint implements ValidatorConstraintInterface {
  validate(value: unknown, args: ValidationArguments): boolean {
    const [relatedProperty] = args.constraints as [string];
    const related = (args.object as Record<string, unknown>)[relatedProperty];
    return value === related;
  }

  defaultMessage(args: ValidationArguments): string {
    const [relatedProperty] = args.constraints as [string];
    return `${args.property} must match ${relatedProperty}`;
  }
}

export function Match(property: string, options?: ValidationOptions) {
  return (object: object, propertyName: string) =>
    registerDecorator({
      target: object.constructor,
      propertyName,
      options,
      constraints: [property],
      validator: MatchConstraint,
    });
}

Going Async: Database Constraints

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import {
  ValidatorConstraint,
  ValidatorConstraintInterface,
  ValidationArguments,
} from 'class-validator';
import { User } from './user.entity';

@ValidatorConstraint({ name: 'isEmailUnique', async: true })
@Injectable()
export class IsEmailUniqueConstraint
  implements ValidatorConstraintInterface
{
  constructor(
    @InjectRepository(User) private readonly users: Repository<User>,
  ) {}

  async validate(email: string): Promise<boolean> {
    const existing = await this.users.findOne({ where: { email } });
    return existing === null;
  }

  defaultMessage(args: ValidationArguments): string {
    return `email '${args.value}' is already registered`;
  }
}

Wiring DI With useContainer

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { useContainer } from 'class-validator';
import { AppModule } from './app.module';

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

  // Resolve custom validators via Nest's DI container
  useContainer(app.select(AppModule), { fallbackOnErrors: true });

  app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
  await app.listen(3000);
}
bootstrap();

Registering the Constraint as a Provider

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './user.entity';
import { UsersService } from './users.service';
import { IsEmailUniqueConstraint } from './is-email-unique.constraint';

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  providers: [UsersService, IsEmailUniqueConstraint],
  exports: [IsEmailUniqueConstraint],
})
export class UsersModule {}

Using the Async Decorator on a DTO

import { IsEmail, IsNotEmpty } from 'class-validator';
import { IsEmailUnique } from './is-email-unique.decorator';
import { IsStrongPassword } from './is-strong-password.decorator';

export class RegisterUserDto {
  @IsEmail()
  @IsEmailUnique({ message: 'This email is taken' })
  email: string;

  @IsNotEmpty()
  @IsStrongPassword()
  password: string;
}

Performance and TOCTOU Caveats

Returning Friendly, Targeted Errors

const existingEmails = new Set(['ada@corp.io', 'grace@corp.io']);

function validateUnique(email: string): { ok: boolean; message?: string } {
  const ok = !existingEmails.has(email);
  return ok ? { ok } : { ok, message: `email '${email}' is already registered` };
}

for (const email of ['ada@corp.io', 'linus@corp.io']) {
  const result = validateUnique(email);
  console.log(`${email.padEnd(16)} -> ${JSON.stringify(result)}`);
}

Quick Check

Recap