@IsDataURI

Декоратор @IsDataURI() выполняет проверку строки на соответствие формату Data URI, описанному в RFC 2397. Валидация основана на механизмах библиотеки validator.js, интегрированной в class-validator, и применяется к строковым значениям свойств классов.

Data URI представляет собой способ встраивания небольших данных непосредственно в строку, обычно внутри HTML, CSS или JSON. Общая структура формата:

data:[<mediatype>][;base64],<data>

где:

  • data: — обязательный префикс схемы;
  • <mediatype> — MIME-тип содержимого (например, image/png, text/plain);
  • ;base64 — признак кодирования в base64 (опционально);
  • <data> — непосредственно закодированное или URL-encoded содержимое.

Декоратор применяется к свойствам классов DTO:

import { IsDataURI } from 'class-validator';

class FileDto {
  @IsDataURI()
  file: string;
}

Валидация допускает только строки, полностью соответствующие формату Data URI. Любое отклонение от синтаксиса приводит к ошибке валидации.

Принцип работы валидатора

Внутри class-validator используется функция isDataURI из validator.js. Проверка включает несколько этапов:

  1. Проверка префикса data:

  2. Разбор MIME-типа (если указан)

  3. Определение наличия ;base64

  4. Валидация части данных:

    • base64-декодируемая строка при наличии base64
    • URL-encoded данные при отсутствии base64

  5. Проверка корректности разделителя ,

Строка считается валидной только при успешном прохождении всех этапов.

Поддерживаемые варианты Data URI

1. Без MIME-типа

data:,Hello%20World

Используется минимальная форма, где тип данных не задан явно.

2. С MIME-типом

data:text/plain,Hello%20World

В этом случае явно указан тип содержимого.

3. Base64-кодирование

data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...

Чаще всего используется для изображений и бинарных данных.

Опции декоратора

@IsDataURI() поддерживает передачу параметров, расширяющих поведение проверки. Основной опцией является настройка проверки MIME-типа:

@IsDataURI({ message: 'Некорректный Data URI' })
file: string;

Сообщение об ошибке

Опция message позволяет задать кастомный текст ошибки:

@IsDataURI({ message: 'Значение должно быть Data URI' })
file: string;

Особенности проверки MIME-типа

В некоторых конфигурациях валидатор может ограничивать допустимые медиа-типы. Это важно при работе с файлами, где требуется строгий контроль формата (например, только изображения).

Пример логической модели:

  • разрешены: image/png, image/jpeg
  • запрещены: text/html, application/javascript

Фактическая реализация зависит от переданных параметров и поведения validator.js.

Использование в DTO и трансформациях

Часто @IsDataURI() применяется в связке с другими декораторами:

import { IsString, IsNotEmpty, IsDataURI } from 'class-validator';

class AvatarDto {
  @IsString()
  @IsNotEmpty()
  @IsDataURI()
  avatar: string;
}

Такой подход обеспечивает одновременно проверку типа, наличия значения и формата Data URI.

Типовые сценарии применения

Встраивание изображений в JSON

Data URI позволяет передавать изображения без отдельной загрузки файлов:

{
  "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

Передача файлов в API

В REST API Data URI используется как альтернатива multipart/form-data при небольших объемах данных.

Внутренние конфигурации

Некоторые системы используют Data URI для хранения и передачи иконок, шаблонов или миниатюр.

Частые ошибки при валидации

Отсутствие префикса data:

image/png;base64,AAAA

Такое значение не считается Data URI.

Пропущенный разделитель запятая

data:image/png;base64AAAA

Отсутствие , нарушает структуру формата.

Некорректный base64

data:image/png;base64,%%%INVALID%%%

Содержимое не декодируется как base64, что приводит к ошибке.

Лишние пробелы

data:image/png;base64, AAAA

Пробелы внутри данных могут приводить к отклонению строки валидатором.

Поведение с Unicode и URL-encoding

При отсутствии ;base64 данные должны быть корректно URL-encoded:

data:text/plain,Привет%20мир

Неправильная кодировка кириллических символов часто становится причиной ошибки валидации.

Комбинация с другими декораторами

@IsDataURI() редко используется изолированно. Типичная композиция:

class UploadDto {
  @IsOptional()
  @IsString()
  @IsDataURI()
  preview: string;
}

Также возможно применение вместе с @Matches() для дополнительной фильтрации MIME-типа.

Поведение при null и undefined

Валидация зависит от дополнительных декораторов:

  • undefined игнорируется без @IsNotEmpty()
  • null требует явной обработки через @IsOptional() или пользовательские правила

Производительность проверки

Проверка Data URI включает:

  • парсинг строки
  • валидацию base64 (при наличии)
  • проверку структуры

На практике нагрузка минимальна, но при массовой валидации больших payload-ов с изображениями base64 может становиться значительным фактором затрат памяти и CPU.

Интеграция с пайпами в NestJS

При использовании валидационного пайпа:

app.useGlobalPipes(new ValidationPipe());

@IsDataURI() автоматически участвует в проверке входящих DTO до попадания данных в бизнес-логику, блокируя некорректные значения на уровне транспортного слоя.

Отличия от похожих декораторов

  • @IsBase64() — проверяет только base64-строку без схемы data:
  • @IsUrl() — проверяет URL, не содержащий встроенные данные
  • @Matches() — позволяет задать собственное регулярное выражение, но без семантической проверки Data URI

@IsDataURI() выполняет именно структурную проверку стандарта, а не только синтаксическое совпадение.

Практическая устойчивость формата

Data URI удобен для небольших вложений, однако имеет ограничения:

  • увеличение размера данных примерно на 33% при base64
  • отсутствие кэшируемости как у отдельных файлов
  • нагрузка на JSON-передачу при больших payload-ах

Валидация через @IsDataURI() обеспечивает лишь корректность формата, но не ограничивает размер или тип содержимого без дополнительных декораторов.

Оглавление