@IsAlpha, @IsAlphanumeric

Декоратор @IsAlpha относится к группе строковых валидаторов библиотеки class-validator и используется для проверки того, что значение поля содержит исключительно буквенные символы.

Под буквенными символами понимаются символы алфавита конкретной локали (по умолчанию — латинский алфавит). Любые цифры, пробелы, знаки препинания и специальные символы приводят к ошибке валидации.

Базовое поведение

Основная задача валидатора — подтвердить, что строка состоит только из букв:

  • допустимые символы: a-z, A-Z (и дополнительные буквы выбранной локали)
  • недопустимые символы: 0-9, !@#$%^&*(), пробелы, подчёркивания

Пример использования

import { IsAlpha } from 'class-validator';

class CreateUserDto {
  @IsAlpha()
  firstName: string;
}

В данном случае поле firstName будет считаться валидным только при условии, что оно состоит исключительно из букв.

Поведение при некорректных значениях

Следующие значения будут отклонены:

  • "John123" — содержит цифры
  • "John Doe" — содержит пробел
  • "John_Doe" — содержит символ подчёркивания
  • "John!" — содержит знак препинания

Локализация

Одним из ключевых аспектов @IsAlpha является поддержка локалей. Валидатор может учитывать расширенные алфавиты различных языков.

import { IsAlpha } from 'class-validator';

class CreateUserDto {
  @IsAlpha('en-US')
  lastName: string;
}

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

  • немецкие умляуты
  • французские акценты
  • испанские специфические символы

Однако поведение зависит от реализации используемой версии class-validator и используемых регулярных выражений внутри библиотеки.

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

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

@IsAlphanumeric

Декоратор @IsAlphanumeric используется для проверки строки на соответствие алфавитно-цифровому набору символов. В отличие от @IsAlpha, он допускает наличие цифр, но запрещает любые специальные символы и пробелы.

Основная логика проверки

Разрешённые символы:

  • латинские буквы a-z, A-Z
  • цифры 0-9
  • символы расширенных алфавитов (при использовании локалей)

Запрещённые символы:

  • пробелы
  • знаки пунктуации
  • математические и служебные символы (+, -, =, @, # и т.д.)
  • подчёркивания и прочие спецсимволы

Базовый пример

import { IsAlphanumeric } from 'class-validator';

class RegisterDto {
  @IsAlphanumeric()
  username: string;
}

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

  • "user123"
  • "TestAccount9"
  • "abcXYZ456"

и отклоняет:

  • "user name" (пробел)
  • "user-name" (дефис)
  • "user.name" (точка)

Отличие от @IsAlpha

Ключевое различие между двумя валидаторами заключается в допустимом наборе символов:

Декоратор Разрешённые символы Запрещённые символы
@IsAlpha только буквы цифры, пробелы, спецсимволы
@IsAlphanumeric буквы и цифры пробелы, спецсимволы

@IsAlphanumeric часто используется для полей идентификаторов, логинов и кодов.

Использование с локалями

Как и другие строковые валидаторы class-validator, @IsAlphanumeric может учитывать локали:

import { IsAlphanumeric } from 'class-validator';

class ProductDto {
  @IsAlphanumeric('en-US')
  sku: string;
}

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

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

Логин пользователя
class LoginDto {
  @IsAlphanumeric()
  login: string;

  password: string;
}

Использование ограничивает логин простым набором символов, исключая пробелы и спецсимволы.

Артикулы товаров
class ProductDto {
  @IsAlphanumeric()
  articleCode: string;
}

Такой подход часто применяется для SKU или внутренних кодов товаров.

Системные идентификаторы
class SystemDto {
  @IsAlphanumeric()
  externalId: string;
}

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

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

  • не допускаются пробелы даже в составе строки
  • не допускаются дефисы, подчёркивания и разделители
  • поведение зависит от выбранной локали, что может приводить к различиям между средами
  • не выполняется проверка на длину строки — для этого используются дополнительные декораторы (@MinLength, @MaxLength)

Комбинирование с другими валидаторами

На практике @IsAlphanumeric часто используется вместе с другими проверками:

import { IsAlphanumeric, MinLength, MaxLength } from 'class-validator';

class UserDto {
  @IsAlphanumeric()
  @MinLength(5)
  @MaxLength(20)
  username: string;
}

Такой набор ограничивает:

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

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

  • ожидание поддержки дефисов в логинах (они не допускаются)
  • попытка использовать пробелы в кодах товаров
  • отсутствие учёта локали, приводящее к отклонению допустимых символов в международных приложениях
  • использование только одного валидатора без дополнительных ограничений на длину и формат
Оглавление