@IsAscii

Декоратор @IsAscii() применяется для проверки строкового значения на соответствие набору ASCII-символов. Поддерживаются только символы с кодами от 0 до 127 включительно, что делает его полезным в задачах, где требуется строгая совместимость с ограниченными текстовыми форматами, протоколами или внешними системами, не поддерживающими Unicode.

ASCII-строка считается валидной, если каждый символ входит в стандартную таблицу ASCII. Это означает отсутствие кириллицы, акцентов, эмодзи и любых расширенных Unicode-символов.

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

HelloWorld
user123
email@example.com

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

Привет
café
hello?

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

Синтаксис и применение

@IsAscii() используется в DTO-классах и моделях валидации, чаще всего в связке с class-validator.

import { IsAscii } from 'class-validator';

export class CreateUserDto {
  @IsAscii()
  username: string;
}

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

Поведение при валидации

При передаче строки валидатор проходит по каждому символу и проверяет его код. Если хотя бы один символ выходит за пределы ASCII-таблицы, валидация завершается ошибкой.

Пример ошибки:

{
  "username": "Иван"
}

Результат валидации:

  • ошибка: значение содержит не-ASCII символы

Использование в NestJS DTO

В экосистеме NestJS @IsAscii() часто применяется в Data Transfer Objects для контроля входящих данных.

import { IsAscii, IsString } from 'class-validator';

export class LoginDto {
  @IsString()
  @IsAscii()
  login: string;

  @IsString()
  @IsAscii()
  password: string;
}

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

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

@IsAscii() редко используется изолированно. Обычно он комбинируется с другими валидаторами для усиления контроля над входными данными.

Ограничение длины

import { IsAscii, Length } from 'class-validator';

export class TokenDto {
  @IsAscii()
  @Length(10, 64)
  token: string;
}

Здесь одновременно проверяется:

  • допустимость ASCII-символов
  • длина строки в заданном диапазоне

Проверка обязательности и формата

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

export class ApiKeyDto {
  @IsString()
  @IsNotEmpty()
  @IsAscii()
  apiKey: string;
}

Комбинация обеспечивает:

  • тип string
  • отсутствие пустого значения
  • ASCII-ограничение

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

1. Технические идентификаторы

ASCII-ограничение полезно для полей, которые используются как ключи:

export class FileDto {
  @IsAscii()
  fileId: string;
}

Такие значения часто передаются в URL, файловых системах или внешних сервисах.

2. API-ключи и токены

Многие системы требуют строго ASCII-совместимые строки:

export class AuthDto {
  @IsAscii()
  accessToken: string;
}

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

3. Имя пользователя в интеграционных системах

Некоторые внешние сервисы поддерживают только латиницу и базовые символы:

export class ExternalUserDto {
  @IsAscii()
  username: string;
}

Поведение с пробелами и спецсимволами

ASCII включает пробел и базовые знаки пунктуации, поэтому следующие значения считаются допустимыми:

"hello world"
"user.name"
"user_name"
"user-name"

Однако символы вроде:

  • é
  • ü
  • ж
  • ?

автоматически приводят к ошибке валидации.

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

class-validator работает после преобразования входных данных в объекты классов (обычно через class-transformer). Если данные приходят в виде Buffer или уже нормализованной строки, проверка ASCII выполняется на итоговом значении.

Важно учитывать, что предварительная трансформация может изменить строку, например при декодировании URL-encoded данных.

Особенности внутренней проверки

Логика проверки основана на простом проходе по строке:

  • каждый символ проверяется на принадлежность диапазону 0–127
  • при обнаружении первого нарушения валидация помечается как неуспешная
  • дальнейшие символы не влияют на результат

Это делает декоратор достаточно быстрым даже на длинных строках.

Ограничения использования

@IsAscii() не различает смысловые типы данных и не проверяет контекст. Он не гарантирует:

  • корректность URL
  • безопасность строки
  • отсутствие SQL-инъекций
  • семантическую валидность

Он проверяет исключительно кодировку символов.

Сочетание с кастомными валидаторами

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

import { Validate, IsAscii } from 'class-validator';

export class CustomDto {
  @IsAscii()
  @Validate(CustomBusinessRule)
  code: string;
}

Такой подход разделяет:

  • техническую валидность (ASCII)
  • бизнес-логику (кастомный валидатор)

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

Как и большинство декораторов class-validator, @IsAscii() по умолчанию игнорирует undefined и null, если не добавлены ограничения вроде @IsNotEmpty() или @IsDefined().

export class ExampleDto {
  @IsAscii()
  value?: string;
}

Здесь отсутствие значения не вызовет ошибку, но наличие не-ASCII строки приведёт к отказу.

Практические нюансы интеграции

При работе с внешними источниками данных важно учитывать:

  • кодировка HTTP-запросов (UTF-8 → возможная потеря соответствия ASCII)
  • базы данных с Unicode-поддержкой
  • промежуточные слои сериализации (JSON, GraphQL)

@IsAscii() становится критическим ограничением в системах, где требуется строгая совместимость с legacy-протоколами или бинарными форматами, рассчитанными только на ASCII.

Производительность и масштабирование

Проверка ASCII является одной из самых дешёвых операций в class-validator, поскольку:

  • отсутствуют регулярные выражения сложного уровня
  • используется простая проверка диапазона кодов символов
  • сложность линейная O(n)

Это позволяет использовать декоратор массово без заметной нагрузки даже при обработке больших DTO-наборов.

Оглавление