Custom and async validators (and their traps)

Two ways to write a custom constraint

class-validator gives you two shapes for a custom rule. The first is a constraint class: a class decorated with @ValidatorConstraint that implements ValidatorConstraintInterface. You write validate() (return boolean or Promise<boolean>) and defaultMessage(), then attach it to a property with @Validate(MyConstraint).

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

// A synchronous rule — no I/O, just logic over the value
@ValidatorConstraint({ name: 'isStrongPassword', async: false })
export class IsStrongPasswordConstraint implements ValidatorConstraintInterface {
  validate(value: string): boolean {
    return typeof value === 'string'
      && value.length >= 12
      && /[a-z]/.test(value)
      && /[A-Z]/.test(value)
      && /[0-9]/.test(value);
  }
  defaultMessage(args: ValidationArguments): string {
    return `${args.property} must be ≥12 chars with upper, lower, and a digit`;
  }
}

export class SignupDto {
  @Validate(IsStrongPasswordConstraint)
  password: string;
}

The second shape is a decorator factory built on registerDecorator. This is what you reach for when you want a reusable @IsEmailUnique() you can drop onto any property — it wraps the same constraint interface in a function that registers it against the target and property:

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

// Reusable decorator: @IsEmailUnique() — wraps a constraint via registerDecorator
export function IsEmailUnique(options?: ValidationOptions) {
  return function (target: object, propertyName: string) {
    registerDecorator({
      name: 'isEmailUnique',
      target: target.constructor,
      propertyName,
      options,
      validator: IsEmailUniqueConstraint, // the @Injectable() class below
    });
  };
}

Either way the rule lives in a constraint class. The decorator factory is just ergonomic packaging so the call site reads @IsEmailUnique() instead of @Validate(IsEmailUniqueConstraint).

Async validators and the DI trap

A uniqueness check has to talk to the database, so its validate() returns a Promise<boolean> and the constraint is marked async: true. To query, it needs the users repository — so you inject it, like any other Nest service:

@ValidatorConstraint({ name: 'isEmailUnique', async: true })
@Injectable()
export class IsEmailUniqueConstraint implements ValidatorConstraintInterface {
  constructor(private readonly users: UsersRepository) {} // injected dep

  async validate(email: string): Promise<boolean> {
    // true = valid = email is NOT taken
    return !(await this.users.exists({ email }));
  }
  defaultMessage(): string {
    return 'email already taken';
  }
}

This compiles, and then crashes at runtime: Cannot read properties of undefined (reading 'exists'). The reason is the trap. class-validator instantiates constraint classes itself, outside Nest’s DI container — it just does new IsEmailUniqueConstraint(), with no idea your constructor wanted a repository. So this.users is undefined. Depending on how you wrote the guard, that’s either a crash or — worse — a validator that silently always passes because the await on undefined throws and gets swallowed.

The one-line fix lives in main.ts. useContainer (exported by class-validator) tells it to resolve constraints through Nest’s container instead of new-ing them itself:

import { useContainer } from 'class-validator';
import { AppModule } from './app.module';

const app = await NestFactory.create(AppModule);
// Route constraint instantiation through Nest's DI so @Injectable() deps resolve
useContainer(app.select(AppModule), { fallbackOnErrors: true });

Now IsEmailUniqueConstraint is built by Nest, gets its UsersRepository, and this.users is real. The fallbackOnErrors: true matters: class-validator’s built-in constraints (@IsEmail, @IsString, …) aren’t Nest providers, so Nest can’t resolve them — fallbackOnErrors lets class-validator fall back to its own new for those instead of throwing. Without it, every built-in validator becomes a “provider not found” error.

Three traps, and why the index is the real fix

Putting a DB read in the validation layer buys you three problems, in increasing order of severity. When you see all three together you understand why the validator and the index are not alternatives — each closes a gap the other cannot.

(1) DI — the one above: forget useContainer and the injected repository is undefined. A deploy-day crash, easy to find once you know it exists.

(2) Perf and enumeration — validation now runs a query on every request to that endpoint, before the handler, including malformed and malicious ones. That’s a DB round trip per request, and worse, the distinct "email already taken" message turns the endpoint into a user-enumeration oracle: an attacker scripts it to learn which emails have accounts. Mitigate with rate limiting and a message that doesn’t confirm existence.

(3) The TOCTOU race — the real lesson. This is the production incident. The uniqueness check is read-then-write, so under concurrency two signups both pass the validator and both insert. The outcome is either two rows with the same email (no constraint) or a raw Postgres unique-violation surfacing as a 500 (constraint present, unhandled). The fix is to stop pretending validation is a constraint:

// 1) The DATABASE is the source of truth — a UNIQUE index serializes inserts
//    e.g. CREATE UNIQUE INDEX users_email_key ON users (lower(email));

// 2) Catch the unique-violation and map it to a clean 409 — Postgres code 23505
try {
  return await this.users.insert(dto);
} catch (e) {
  if (e.code === '23505') {           // unique_violation
    throw new ConflictException('email already taken'); // 409, not 500
  }
  throw e;
}

Validation is not a constraint. Keep the async @IsEmailUnique() — it gives the common case a friendly 400 without a stack trace. But the UNIQUE index is the source of truth: it is the only thing that serializes the two concurrent inserts, and catching 23505 turns the loser of that race into a clean 409 instead of a leaked 500. The validator is the UX; the index is the guarantee.