Автоматическая трансформация типов

Механизм автоматической трансформации типов в экосистеме class-validator опирается не на саму библиотеку, а на взаимодействие с class-transformer и, в типичных архитектурах, с инфраструктурой фреймворка (например, пайпами в NestJS). Декораторы валидации работают с уже созданными экземплярами классов, поэтому входные данные сначала должны быть преобразованы из «сырых» JSON-объектов в экземпляры с корректными типами полей.

Данные, поступающие извне (HTTP-запросы, очереди сообщений, файлы), почти всегда представлены в виде строк или простых JSON-структур. Это приводит к характерным несоответствиям:

  • числа приходят как строки: "42" вместо 42
  • булевы значения могут быть строками: "true" или "false"
  • даты представлены строками в ISO-формате
  • вложенные структуры остаются обычными объектами без прототипов классов

class-validator выполняет проверку уже на уровне типов и значений, поэтому без предварительной трансформации большинство валидаторов работают некорректно или требуют избыточных ручных преобразований.

Разделение ответственности: валидация и трансформация

Архитектурно разделяются две операции:

  • Трансформация — преобразование plain object → class instance
  • Валидация — проверка instance согласно декораторам

class-validator не выполняет трансформацию самостоятельно. Эта задача делегируется class-transformer, который интегрируется в пайп обработки входных данных.

Базовый механизм преобразования через class-transformer

Ключевая функция преобразования:

  • plainToInstance() — создание экземпляра класса из простого объекта

Пример логики:

const dto = plainToInstance(UserDto, rawBody);

После этого dto уже содержит корректный прототип класса, и class-validator способен применять декораторы:

  • @IsString()
  • @IsInt()
  • @IsBoolean()
  • @IsDate()

Однако сама по себе эта трансформация не приводит к изменению типов примитивов.

Автоматическое приведение типов в NestJS ValidationPipe

Наиболее распространённый сценарий автоматической трансформации реализуется через конфигурацию пайпа:

new ValidationPipe({
  transform: true,
})

Параметр transform: true включает автоматическое использование class-transformer перед валидацией.

Дополнительно используется:

new ValidationPipe({
  transform: true,
  transformOptions: {
    enableImplicitConversion: true,
  },
})

Роль enableImplicitConversion

Флаг enableImplicitConversion активирует неявное приведение типов на основе metadata, полученной через reflect-metadata.

Это позволяет преобразовывать:

  • "123" → 123
  • "true" → true
  • "2025-01-01" → Date

без явного указания логики преобразования в коде.

Поведение примитивных типов

Числа

import { Type } from 'class-transformer';
import { IsInt } from 'class-validator';

class CreateDto {
  @Type(() => Number)
  @IsInt()
  age: number;
}

При включённой трансформации строка "25" будет преобразована в число 25.

Особенность заключается в том, что без @Type(() => Number) преобразование может не произойти в зависимости от конфигурации и источника данных.

Булевы значения

Булевы поля из HTTP-запросов часто приходят как строки:

  • "true"
  • "false"

При активной трансформации:

@Type(() => Boolean)
isActive: boolean;

значения приводятся к true/false, однако поведение зависит от источника данных и реализации преобразования. В некоторых случаях требуется дополнительная нормализация входных данных.

Даты

@Type(() => Date)
createdAt: Date;

Строка ISO:

"2025-01-01T10:00:00.000Z"

преобразуется в объект Date, после чего становится доступной валидация через:

  • @IsDate()
  • @MinDate()
  • @MaxDate()

Вложенные объекты и их трансформация

Одна из ключевых проблем — отсутствие автоматического преобразования вложенных структур без явного указания типа.

Пример:

class Address {
  @IsString()
  city: string;
}

class UserDto {
  @ValidateNested()
  @Type(() => Address)
  address: Address;
}

Без @Type(() => Address) вложенный объект останется plain object, и валидаторы внутри Address не будут применены.

Механизм ValidateNested

Декоратор:

  • инициирует рекурсивную валидацию
  • требует предварительной трансформации вложенного объекта

Без трансформации цепочка валидаторов не активируется.

Работа с массивами

Массивы требуют отдельного описания типа элементов:

class UserDto {
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => Address)
  addresses: Address[];
}

Здесь критичны два аспекта:

  • each: true включает валидацию каждого элемента
  • @Type(() => Address) обеспечивает преобразование каждого элемента массива

Без этого элементы массива остаются plain objects.

Неявное приведение и metadata reflection

Автоматическая трансформация опирается на метаданные TypeScript:

  • emitDecoratorMetadata
  • reflect-metadata

При включённой конфигурации компилятора:

{
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true
}

становится доступной информация о типах полей в runtime, что позволяет class-transformer выполнять частичное автоматическое приведение.

Проблемные случаи автоматической трансформации

Отсутствие metadata

Если TypeScript не генерирует metadata, преобразование становится непредсказуемым:

  • поля остаются строками
  • вложенные объекты не инстанцируются
  • массивы теряют типизацию элементов

Конфликты с API-форматом

Некоторые API возвращают неоднозначные типы:

  • "0" может означать число или булево false
  • "1" аналогично
  • пустые строки интерпретируются неоднозначно

Автоматическая трансформация в таких случаях не гарантирует корректного результата.

Частичное преобразование

Даже при включённом transform: true:

  • преобразуются только поля с явно описанными типами
  • неизвестные поля остаются без изменений
  • вложенные структуры требуют явных декораторов

Влияние whitelist и forbidNonWhitelisted

При использовании:

new ValidationPipe({
  whitelist: true,
  forbidNonWhitelisted: true,
  transform: true,
})

происходит дополнительная очистка объекта после трансформации:

  • удаляются неописанные поля
  • запрещённые поля вызывают исключения

Это влияет на итоговую структуру объекта, который проходит в бизнес-логику.

Преобразование в связке с кастомными декораторами

При необходимости сложной логики трансформации используется:

@Transform(({ value }) => parseInt(value, 10))
age: number;

@Transform выполняется на этапе class-transformer до валидации, что позволяет:

  • нормализовать входные данные
  • приводить нестандартные форматы
  • реализовывать условные преобразования

Порядок выполнения трансформации и валидации

В типичном pipeline:

  1. Получение plain object

  2. class-transformer:

    • создание instance
    • применение @Type
    • применение @Transform
    • implicit conversion (если включено)

  3. class-validator:

    • выполнение всех декораторов
    • проверка вложенных структур
    • применение условий each, groups, conditional validation

Ограничения автоматической трансформации

  • отсутствие строгой гарантии преобразования boolean из строковых значений
  • зависимость от metadata TypeScript
  • невозможность корректной обработки нестандартных форматов без кастомных трансформеров
  • необходимость явного описания вложенных типов
  • различие поведения между HTTP, WebSocket и CLI источниками данных

Поведение при частично типизированных DTO

Если часть полей не аннотирована:

class ExampleDto {
  name: string;

  age: number;
}

и отсутствует @Type, то:

  • name и age могут остаться строками
  • class-validator будет применять проверки к исходным значениям
  • ошибки типов могут возникать уже на этапе бизнес-логики

Связь с безопасностью данных

Автоматическая трансформация влияет на безопасность:

  • предотвращает injection через неожиданные типы
  • снижает риск обработки некорректных структур
  • в сочетании с whitelist ограничивает поверхность входных данных

Однако при неправильной настройке может возникнуть обратный эффект:

  • ложное ощущение типовой безопасности
  • пропуск некорректных значений при слабой конфигурации transform

Итоговое поведение системы трансформации

Система автоматического преобразования типов в контексте class-validator представляет собой слой над class-transformer, который:

  • приводит входные данные к классам
  • выполняет частичное неявное преобразование типов
  • требует явного описания сложных структур
  • зависит от metadata TypeScript и конфигурации пайпа
  • обеспечивает подготовку данных для корректной валидации
Оглавление