Параметры функции валидации

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

Базовая сигнатура функции проверки

При использовании метода test у любого типа схемы Yup передаётся функция следующего вида:

(value, context) => boolean | ValidationError | undefined

Где:

  • value — текущее значение поля, которое проходит проверку
  • context — объект контекста, содержащий служебные данные и вспомогательные функции

Структура параметра value

Параметр value всегда содержит «сырое» значение поля после применения трансформаций (transform), но до финального результата валидации.

Особенности:

  • может быть undefined, если поле отсутствует
  • может быть null, если это допустимое состояние схемы
  • может быть уже преобразованным типом (например, строка → число)

Контекст выполнения (context)

Второй параметр функции проверки предоставляет расширенную информацию о текущем состоянии схемы:

(value, context) => {}

Контекст включает следующие ключевые поля:

path

Строка, указывающая путь к проверяемому полю.

Пример:

"user.email"

Используется для формирования ошибок и диагностики.

parent

Объект родительского уровня, содержащий все поля текущего объекта.

Пример:

{
  email: "test@mail.com",
  password: "123456"
}

Позволяет реализовывать межполевую валидацию.

originalValue

Исходное значение до применения transform.

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

schema

Ссылка на текущую схему Yup.

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

options

Объект настроек, переданных в validate.

Наиболее часто используемые параметры:

  • abortEarly — прекращение валидации при первой ошибке
  • stripUnknown — удаление неизвестных полей
  • strict — отключение трансформаций
  • context — пользовательский контекст

createError

Функция для явного формирования ошибки валидации.

Сигнатура:

createError({ message, path })

Используется вместо возврата false, когда требуется детализированная ошибка.

this-контекст внутри test-функции

Помимо явного context, Yup также привязывает служебные данные к this:

this.path
this.parent
this.schema
this.options
this.createError
this.originalValue

Это важно учитывать, поскольку многие старые и новые примеры используют именно this.

Пример:

Yup.string().test('check-name', function (value) {
  if (!value) {
    return this.createError({ message: 'Значение обязательно' });
  }
  return true;
});

Возвращаемые значения функции валидации

Функция может возвращать:

true

Проверка успешно пройдена.

false

Стандартная ошибка с использованием сообщения по умолчанию.

createError(…)

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

undefined

Рассматривается как успешная проверка (используется редко).

Параметры валидации через schema.validate

Отдельный набор параметров передаётся при вызове:

schema.validate(value, options)

abortEarly

Тип: boolean

  • true — остановка при первой ошибке
  • false — сбор всех ошибок

strict

Тип: boolean

  • отключает автоматические преобразования типов
  • полезно при строгой типизации данных

stripUnknown

Тип: boolean

  • удаляет поля, не описанные в схеме
  • применяется к объектам

context

Тип: object

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

schema.validate(data, { context: { role: 'admin' } })

Доступ внутри test:

this.options.context

Использование параметров внутри кастомных проверок

Комбинация параметров позволяет реализовывать сложные сценарии:

Yup.number().test('min-role-based', function (value) {
  const role = this.options.context?.role;

  if (role === 'admin' && value < 10) {
    return this.createError({
      message: 'Для администратора минимум 10'
    });
  }

  return true;
});

Особенности передачи аргументов в test

Сигнатура метода test может выглядеть так:

test(name, message, testFunction)

где testFunction получает:

  • значение поля
  • контекст выполнения

Пример:

Yup.string().test(
  'len-check',
  'Слишком короткое значение',
  function (value, context) {
    if (value && value.length < 3) {
      return context.createError();
    }
    return true;
  }
);

Приоритет параметров и контекста

При конфликте значений:

  • this имеет приоритет над вторым аргументом
  • options.context переопределяет глобальные значения
  • originalValue не изменяется трансформациями

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

Функция может возвращать Promise:

test('async-check', async function (value) {
  const isValid = await apiCheck(value);

  if (!isValid) {
    return this.createError({ message: 'Ошибка сервера' });
  }

  return true;
});

Контекст сохраняется и в асинхронном режиме, включая path, parent и options.

Типичные комбинации параметров

Межполевые проверки

Используется parent:

Yup.object({
  password: Yup.string(),
  confirm: Yup.string().test(function (value) {
    return value === this.parent.password;
  })
});

Проверка с внешним контекстом

Используется options.context:

test(function (value) {
  const mode = this.options.context?.mode;
  return mode === 'strict' ? value !== '' : true;
});

Формирование сложных ошибок

Используется createError:

test(function (value) {
  if (!value) {
    return this.createError({
      path: this.path,
      message: 'Поле не заполнено'
    });
  }
  return true;
});

Итоговая структура параметров функции валидации

Функция проверки в Yup фактически опирается на три источника данных:

  1. value — текущее значение
  2. context (второй аргумент) — структурированная информация о схеме
  3. this-контекст — дублирующий API для доступа к метаданным и утилитам

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

Оглавление