@IsVariableWidth

Назначение валидатора

Декоратор @IsVariableWidth применяется для проверки строк на соответствие критерию переменной ширины символов. Под переменной шириной в контексте Unicode понимаются символы, которые могут иметь различное визуальное представление по ширине: часть из них относится к полноширинным (full-width), часть — к полуширинным (half-width), а также существуют символы нейтральной ширины.

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

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

Логика проверки

Внутренняя проверка ориентируется на свойства Unicode-символов. Каждый символ строки анализируется на предмет его ширины в контексте терминологии Unicode East Asian Width:

  • Halfwidth (H) — полуширинные символы (стандартный ASCII)
  • Fullwidth (F) — полноширинные символы (часто используются в CJK-типографике)
  • Ambiguous (A) — неоднозначные по ширине символы
  • Neutral (N) — нейтральные символы

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

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

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

Строка считается валидной, если она удовлетворяет условиям, связанным с допустимой комбинацией символов разной ширины.

Невалидными считаются случаи:

  • строка полностью состоит из символов одной фиксированной ширины при ожидании смешанного текста;
  • строка содержит символы, не соответствующие допустимым Unicode-классам;
  • строка нарушает требования системы нормализации ширины символов.

Результат проверки интегрируется в систему class-validator как стандартная ошибка валидации с возможностью передачи сообщения.

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

Использование декоратора осуществляется внутри классов-DTO, где требуется контроль качества входных данных:

import { IsVariableWidth } from 'class-validator';

class TextPayload {
  @IsVariableWidth()
  content: string;
}

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

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

Как и большинство валидаторов class-validator, @IsVariableWidth не обрабатывает отсутствие значения как ошибку по умолчанию. Пустое значение игнорируется, если поле не помечено как обязательное.

Для обязательности используется комбинация:

  • @IsDefined
  • @IsNotEmpty

В связке с ними @IsVariableWidth применяется уже к гарантированно существующему значению.

Влияние нормализации Unicode

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

Unicode допускает несколько форм представления одного и того же визуального символа:

  • NFC (Canonical Composition)
  • NFD (Canonical Decomposition)
  • NFKC (Compatibility Composition)
  • NFKD (Compatibility Decomposition)

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

Использование в интернационализации

Основные сценарии применения связаны с обработкой текста в многоязычных системах:

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

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

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

Поведение @IsVariableWidth имеет ряд ограничений, обусловленных природой Unicode:

  • ширина символа определяется контекстом отображения, а не только кодовой точкой;
  • разные шрифты могут по-разному интерпретировать ширину одного и того же символа;
  • браузеры и терминалы используют различные таблицы East Asian Width;
  • валидатор не учитывает визуальный рендеринг, только кодовую классификацию.

Из-за этого результат проверки может не полностью совпадать с визуальным восприятием строки.

Ошибки валидации и сообщения

При нарушении условий формируется стандартная ошибка ValidationError, содержащая:

  • имя свойства
  • значение
  • constraint, связанный с isVariableWidth

Сообщение может быть переопределено:

@IsVariableWidth({ message: 'Строка должна содержать корректные символы переменной ширины' })
content: string;

Совместное использование с другими декораторами

@IsVariableWidth редко используется изолированно. Чаще всего он комбинируется с другими проверками:

  • @IsString — гарантия строкового типа
  • @Length — контроль длины
  • @Matches — регулярные выражения для фильтрации допустимых символов
  • @IsOptional — разрешение отсутствия значения

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

Поведение в пайплайне class-validator

В процессе валидации объект проходит последовательную обработку:

  1. преобразование входных данных (если используется class-transformer);
  2. проверка типов;
  3. выполнение декораторов в порядке регистрации;
  4. накопление ошибок.

@IsVariableWidth участвует в шаге проверки содержимого строки и не влияет на трансформацию данных.

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

Оценка строки на соответствие правилам ширины символов требует посимвольного анализа. Сложность алгоритма линейная:

O(n), где n — длина строки.

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

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

На практике часто встречаются некорректные предположения о поведении валидатора:

  • ожидание проверки «визуальной ширины» вместо Unicode-классификации;
  • применение к числовым или бинарным данным;
  • попытка использовать как фильтр языка или алфавита;
  • игнорирование нормализации строк перед проверкой.

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

Контекст использования в архитектуре приложений

В архитектуре серверных приложений на Node.js с использованием DTO-слоя @IsVariableWidth обычно размещается на границе входных данных:

  • контроллеры REST API;
  • GraphQL input-типы;
  • WebSocket события;
  • сервисы импорта данных.

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

Оглавление