@IsHexadecimal

Декоратор @IsHexadecimal относится к группе валидаторов строковых значений и предназначен для проверки, что значение представляет собой корректное шестнадцатеричное число. Проверка выполняется на уровне строки и допускает только символы, входящие в диапазон 0-9, a-f, A-F. Любые другие символы приводят к ошибке валидации.

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

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

Ключевые характеристики:

  • допустимы символы: 0-9, a-f, A-F
  • строка должна быть непустой (в зависимости от настроек each)
  • не допускаются префиксы 0x или #
  • пробелы и разделители считаются недопустимыми символами

Примеры допустимых значений:

  • ff
  • A1B2C3
  • deadBEEF
  • 0123456789abcdef

Примеры недопустимых значений:

  • 0xFF (содержит префикс)
  • #FFAA00 (содержит символ #)
  • GGHHII (символы вне диапазона)
  • 12 34 (пробел)

Сигнатура и параметры

В библиотеке class-validator декоратор используется следующим образом:

IsHexadecimal(validationOptions?: ValidationOptions)

Параметр validationOptions позволяет управлять поведением валидации:

  • message — пользовательское сообщение об ошибке
  • groups — группы валидации
  • each — применение к каждому элементу массива
  • context — дополнительный контекст ошибки

Базовое использование

Типовой сценарий — проверка строкового свойства DTO:

import { IsHexadecimal } from "class-validator";

class ColorDto {
  @IsHexadecimal()
  value: string;
}

В данном случае поле value должно содержать корректную шестнадцатеричную строку без дополнительных символов.

Использование с пользовательским сообщением

Сообщение ошибки может быть переопределено для унификации ответов API:

import { IsHexadecimal } from "class-validator";

class HashDto {
  @IsHexadecimal({
    message: "Значение должно быть шестнадцатеричной строкой",
  })
  hash: string;
}

Такой подход используется в системах, где требуется стандартизированный формат ошибок без раскрытия внутренних деталей валидации.

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

При использовании опции each: true проверка применяется к каждому элементу массива:

import { IsHexadecimal } from "class-validator";

class BatchDto {
  @IsHexadecimal({ each: true })
  values: string[];
}

В этом случае массив считается валидным только при условии, что каждый его элемент соответствует шестнадцатеричному формату. Один некорректный элемент делает весь массив невалидным.

Взаимодействие с трансформацией типов

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

Типичная ошибка возникает при передаче чисел:

class ExampleDto {
  @IsHexadecimal()
  value: string;
}

Передача значения:

{
  "value": 255
}

приведёт к ошибке, поскольку число не рассматривается как допустимый формат, даже если его строковое представление могло бы быть валидным.

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

Отличие от смежных валидаторов

Сравнение с @IsAlphanumeric

@IsAlphanumeric допускает буквы и цифры без ограничения диапазона, тогда как @IsHexadecimal ограничивает буквенные символы строго диапазоном a-f.

Сравнение с @Matches

@Matches предоставляет универсальный механизм через регулярные выражения. @IsHexadecimal является специализированной и более семантически выразительной альтернативой для конкретного случая.

Пример эквивалентной проверки через @Matches:

@Matches(/^[0-9a-fA-F]+$/)

Использование специализированного декоратора повышает читаемость и снижает вероятность ошибок в регулярных выражениях.

Поведение с пустыми значениями

IsHexadecimal не предназначен для проверки наличия значения. Пустые строки считаются невалидными.

При необходимости допуска пустого значения используется комбинация с @IsOptional:

import { IsHexadecimal, IsOptional } from "class-validator";

class ExampleDto {
  @IsOptional()
  @IsHexadecimal()
  value?: string;
}

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

Валидация цветовых кодов

Распространённый сценарий — проверка HEX-цветов без символа #:

class ThemeDto {
  @IsHexadecimal()
  primaryColor: string;

  @IsHexadecimal()
  secondaryColor: string;
}

Важно учитывать, что популярный CSS-формат #RRGGBB требует предварительного удаления символа # перед валидацией.

Ограничения и особенности реализации

Валидация носит строго символьный характер и не учитывает:

  • длину строки (например, 1 символ считается допустимым)
  • соответствие числовым диапазонам
  • наличие префиксов или разделителей
  • семантический смысл значения

Это означает, что строка "0" является валидной, хотя может быть недостаточной в контексте некоторых бизнес-правил.

При необходимости ограничения длины комбинируется с @MinLength и @MaxLength:

import { IsHexadecimal, MinLength, MaxLength } from "class-validator";

class StrictHexDto {
  @IsHexadecimal()
  @MinLength(6)
  @MaxLength(6)
  color: string;
}

Использование в сложных DTO

В сложных структурах данных IsHexadecimal часто применяется в сочетании с другими валидаторами:

import { IsHexadecimal, IsString, Length } from "class-validator";

class TokenDto {
  @IsString()
  @IsHexadecimal()
  @Length(32, 32)
  accessToken: string;
}

Такой подход позволяет одновременно гарантировать формат и фиксированную длину значения.

Применение в доменных моделях

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

Типичный пример:

class TransactionDto {
  @IsHexadecimal()
  transactionId: string;
}

Подобная проверка снижает вероятность ошибок при поиске записей по идентификаторам фиксированного формата.

Поведение при наследовании DTO

При наследовании классов валидаторы сохраняют своё поведение, однако порядок выполнения может зависеть от структуры пайплайна валидации:

class BaseDto {
  @IsHexadecimal()
  id: string;
}

class ExtendedDto extends BaseDto {
  name: string;
}

Валидация поля id сохраняется в производных классах без дополнительных объявлений.

Производительность и внутренняя логика

Проверка реализована через регулярное выражение и выполняется за линейное время относительно длины строки. Это делает декоратор подходящим для массовой валидации входных данных в API без заметного влияния на производительность.

При обработке больших массивов узким местом становится не сама проверка, а инфраструктурные операции сериализации и трансформации данных.

Типовые ошибки при использовании

На практике встречаются следующие ошибки конфигурации:

  • использование вместе с числовыми типами без трансформации
  • ожидание поддержки 0x формата
  • отсутствие ограничения длины при работе с фиксированными идентификаторами
  • применение к необработанным пользовательским строкам с пробелами

Корректная схема обычно включает предварительную нормализацию входных данных и последующую валидацию только очищенных строковых значений

Оглавление