Метод validate и его параметры

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

Общая сигнатура

schema.validate(value, options?)

Метод вызывается на экземпляре схемы и принимает два параметра:

  • value — проверяемое значение
  • options — объект конфигурации (необязательный)

Возвращаемое значение:

  • Promise<validValue> при успешной валидации
  • Promise.reject(ValidationError) при ошибке

Таким образом, метод всегда работает в асинхронном стиле, даже если в схеме нет асинхронных правил.

Параметр value

value представляет собой входные данные, которые необходимо проверить. Это может быть любой тип:

  • строка
  • число
  • объект
  • массив
  • null или undefined

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

Пример:

const schema = yup.string().min(3);

schema.validate("abc");

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

Параметр options

Объект options управляет поведением валидации. Он позволяет тонко настраивать процесс проверки, трансформации и обработки ошибок.

abortEarly

abortEarly: boolean

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

  • true (по умолчанию): возвращается только первая ошибка
  • false: собираются все ошибки

Пример:

schema.validate("a", { abortEarly: false });

При сложной схеме с несколькими ограничениями это позволяет получить полный список нарушений.

context

context: any

Позволяет передавать дополнительный контекст в схему. Используется в функциях when, test и других динамических проверках.

Пример:

const schema = yup.string().when('$role', {
  is: 'admin',
  then: (s) => s.required()
});

schema.validate("value", { context: { role: 'admin' } });

Контекст доступен внутри схемы через $-ссылки.

strict

strict: boolean

Отключает трансформации данных.

  • false (по умолчанию): Yup применяет cast и преобразования
  • true: проверка происходит без преобразования

Пример:

const schema = yup.number();

schema.validate("123", { strict: true });

В строгом режиме строка "123" не будет преобразована в число.

stripUnknown

stripUnknown: boolean

Применяется только для объектов. Удаляет поля, не описанные в схеме.

Пример:

const schema = yup.object({
  name: yup.string()
});

schema.validate(
  { name: "Alex", age: 25 },
  { stripUnknown: true }
);

Результат:

{ name: "Alex" }

recursive

recursive: boolean

Определяет, будет ли выполняться рекурсивная валидация вложенных схем.

  • true (по умолчанию): проверяются вложенные объекты и массивы
  • false: вложенные схемы игнорируются

external options (дополнительные внутренние параметры)

Некоторые версии Yup поддерживают расширенные опции:

  • path — указывает путь в объекте для точечной валидации
  • originalValue — исходное значение до трансформации
  • parent — родительский объект (в сложных схемах)

Поведение метода validate

Метод выполняет несколько этапов:

1. Кастинг (cast)

Если strict: false, значение преобразуется к ожидаемому типу схемы.

2. Трансформации

Применяются функции .transform(), заданные в схеме.

3. Проверка правил

Выполняются:

  • встроенные ограничения (required, min, max)
  • пользовательские test()
  • асинхронные проверки

4. Обработка ошибок

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

  • message — текст ошибки
  • path — путь к полю
  • errors — массив сообщений (если abortEarly: false)

Асинхронность validate

Метод всегда возвращает Promise, даже если внутри нет асинхронных операций.

await schema.validate(value);

Это важно для унифицированного API, позволяющего использовать одинаковый подход для всех схем.

Обработка ошибок ValidationError

При ошибке метод отклоняет Promise с объектом:

{
  name: "ValidationError",
  message: "...",
  errors: ["..."],
  path: "fieldName"
}

Пример обработки:

schema.validate(data)
  .catch(err => {
    console.log(err.errors);
  });

validate vs isValid

Метод validate отличается от isValid:

  • validate возвращает либо данные, либо ошибку
  • isValid возвращает true или false
await schema.isValid(value); // boolean
await schema.validate(value); // value | throws

validateSync и ограничения

Хотя существует синхронная версия validateSync, она не поддерживает асинхронные проверки (например, запросы к серверу или базе данных). Поэтому validate является универсальным решением.

Поведение с массивами и объектами

Объекты

При валидации объектов:

  • проверяются все поля схемы
  • учитывается stripUnknown
  • выполняется глубокая проверка вложенных схем

Массивы

При массивах:

  • каждый элемент проходит отдельную валидацию
  • ошибки могут агрегироваться при abortEarly: false

Особенности работы с test()

Пользовательские проверки через test() интегрируются в pipeline validate.

yup.string().test('check', 'Ошибка', (value) => {
  return value === 'ok';
});

Такие проверки участвуют в общей цепочке и могут быть асинхронными.

Контекст выполнения и this

Внутри пользовательских функций доступен контекст схемы:

  • this.parent — родительский объект
  • this.path — путь текущего поля
  • this.options — опции validate

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

Влияние abortEarly на структуру ошибок

При abortEarly: true возвращается только первая ошибка, что ускоряет выполнение.

При abortEarly: false структура ошибки расширяется:

{
  errors: ["Ошибка 1", "Ошибка 2", "Ошибка 3"]
}

Это особенно важно для форм с множеством полей.

Производственные особенности

Метод validate оптимизирован для:

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

Типичные сценарии использования

Валидация формы

await schema.validate(formData, { abortEarly: false });

API-проверка входных данных

await schema.validate(req.body);

Условная логика через context

await schema.validate(data, {
  context: { mode: "edit" }
});
Оглавление