Понимание контекста валидации

Валидация данных в Superstruct строится не только на проверке значения как такового, но и на окружении, в котором это значение существует. Контекст валидации представляет собой набор служебной информации, которая передаётся в каждый пользовательский валидатор и позволяет учитывать структуру объекта, путь до текущего узла, режим преобразования и состояние проверки.

Роль контекста в процессе проверки

При обработке значения Superstruct формирует объект контекста, который сопровождает каждую проверку, включая вложенные поля сложных структур. Это позволяет реализовывать:

  • точное определение источника ошибки;
  • зависимые проверки (например, сравнение полей внутри объекта);
  • управление поведением валидации в зависимости от режима выполнения;
  • расширенные сценарии преобразования данных.

Контекст становится связующим звеном между текущим значением и всей структурой данных, в которой оно находится.

Путь значения и навигация по структуре

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

Пример логики пути:

["user", "profile", "email"]

Такой путь указывает, что валидация происходит на уровне email, вложенного в profile, который, в свою очередь, находится в user.

Значение path используется для:

  • формирования точных сообщений об ошибках;
  • трассировки вложенных структур;
  • интеграции с UI-формами и отображением ошибок по полям.

Исходное значение (branch)

Контекст содержит также branch — исходное значение, от которого происходит текущая проверка. В отличие от value, которое может быть преобразовано или уточнено в процессе валидации, branch остаётся неизменным и представляет первоначальные данные на данном уровне дерева.

Использование branch позволяет:

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

Режим преобразования данных (coercion)

Контекст может содержать флаг coerce, определяющий, разрешено ли автоматическое приведение типов.

В режиме coercion возможны преобразования:

  • строк в числа;
  • строк в даты;
  • приведение структурированных данных к нужному формату.

Проверяющие функции могут учитывать этот флаг для изменения поведения:

  • либо строго валидировать тип;
  • либо пытаться привести значение к допустимому виду.

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

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

Типичная сигнатура:

(value, context) => boolean | string | void

Контекст предоставляет инструменты для управления результатом проверки:

  • context.path — путь к значению;
  • context.branch — исходное значение на текущем уровне;
  • context.coerce — режим преобразования;
  • context.fail() — явное формирование ошибки.

Использование context.fail позволяет завершить проверку с детализированным сообщением:

context.fail("Недопустимый формат значения")

или с более точной структурой ошибки, включая путь и тип нарушения.

Ошибки и механизм fail

Superstruct не ограничивается возвратом булевого результата. Контекст позволяет формировать структурированные ошибки через механизм fail.

При вызове fail выполнение текущей проверки прерывается, а ошибка регистрируется в общей структуре результата.

Это обеспечивает:

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

Контекст в refine и композиции структур

При использовании refine контекст сохраняется и передаётся в пользовательскую функцию уточнения.

Это позволяет реализовывать зависимые ограничения, например:

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

Пример логики:

  • если role = "admin", поле permissions должно быть заполнено;
  • если дата окончания меньше даты начала, возникает ошибка на уровне объекта.

Вложенные структуры и наследование контекста

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

Это означает:

  • path дополняется новым ключом;
  • branch сужается до текущего поддерева;
  • режим coerce сохраняется;
  • ошибки остаются привязанными к общей иерархии.

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

Динамическое поведение через контекст

Контекст позволяет реализовывать динамические схемы, в которых структура проверки зависит от текущих данных.

Это достигается через:

  • анализ branch;
  • использование path для определения положения;
  • переключение логики внутри пользовательских структур.

Подобные механизмы используются для:

  • форм с условными полями;
  • API с вариативными схемами;
  • адаптивных структур данных.

Управление точностью ошибок

Контекст валидации напрямую влияет на детализацию ошибок. Комбинация path, branch и fail позволяет формировать сообщения, которые:

  • указывают точное расположение проблемы;
  • содержат контекст значения;
  • различают типы нарушений внутри одной структуры.

Это особенно важно при работе с большими объектами, где простое сообщение о несоответствии типа недостаточно информативно.

Связь контекста с композицией структур

При использовании композиции (object, array, union) контекст передаётся через всю цепочку проверок без потери информации.

Это обеспечивает:

  • согласованность вложенных валидаторов;
  • единый механизм обработки ошибок;
  • возможность локальной логики в глобальной структуре.

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

Оглавление