Строки: string()

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

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

Базовое поведение string()

Базовая схема без дополнительных правил:

Joi.string()

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

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

  • "hello"
  • "123"
  • ""

Пример недопустимых значений (при строгой проверке):

  • null
  • undefined
  • {}

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

Для контроля размеров строки используются ограничения:

min() и max()

Joi.string().min(3).max(10)
  • min(n) — минимальная длина строки
  • max(n) — максимальная длина строки

Ограничения применяются после приведения значения к строке.

Пример:

  • "abc" — допустимо
  • "ab" — ошибка (меньше минимального значения)
  • "abcdefghijk" — ошибка (превышение максимума)

length()

Фиксированная длина строки:

Joi.string().length(5)

Эквивалент строгого диапазона, где min === max.

Ограничение содержимого строки

pattern()

Позволяет задавать регулярное выражение:

Joi.string().pattern(/^[a-z]+$/)

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

Примеры:

  • "abc" — допустимо
  • "abc123" — ошибка

Также возможно использование именованных паттернов:

Joi.string().pattern(new RegExp('^[0-9]{3}$'))

alphanum()

Ограничение на латинские буквы и цифры:

Joi.string().alphanum()

Допустимые значения:

  • "abc123"
  • "A1B2C3"

Недопустимые:

  • "abc-123"
  • "hello world"

email()

Проверка формата электронной почты:

Joi.string().email()

Включает базовую валидацию структуры:

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

Возможны дополнительные настройки строгой проверки:

Joi.string().email({ tlds: { allow: false } })

uri()

Проверка URI:

Joi.string().uri()

Допустимые примеры:

  • "https://example.com"
  • "ftp://server.com/file"

Можно ограничивать схемы:

Joi.string().uri({ scheme: ['http', 'https'] })

uuid()

Проверка UUID:

Joi.string().uuid()

Поддерживаются версии UUID (v1–v5 в зависимости от конфигурации):

Joi.string().uuid({ version: 'uuidv4' })

Преобразование строки

trim()

Удаляет пробелы в начале и конце строки:

Joi.string().trim()

Пример:

  • " hello " → "hello"

lowerCase()

Преобразует строку в нижний регистр:

Joi.string().lowercase()

upperCase()

Преобразует строку в верхний регистр:

Joi.string().uppercase()

normalize()

Нормализация Unicode:

Joi.string().normalize()

Используется для приведения строк к единому виду (например, при сравнении данных с разными формами Unicode).

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

valid()

Определяет список разрешённых значений:

Joi.string().valid('admin', 'user', 'guest')

Любое значение вне списка считается ошибкой.

invalid()

Исключает значения:

Joi.string().invalid('root', 'superuser')

allow()

Добавляет исключения из правил валидации:

Joi.string().min(5).allow('')

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

Работа с пустыми значениями

По умолчанию пустая строка считается валидной. Поведение можно изменить:

Joi.string().empty('')

Пустые значения могут преобразовываться в undefined или другое значение по правилам схемы.

Обязательность и опциональность

required()

Joi.string().required()

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

optional()

Joi.string().optional()

Явное указание необязательности (обычно используется по умолчанию).

Значение по умолчанию

Joi.string().default('unknown')

Если значение отсутствует, подставляется указанное значение.

Кастомизация сообщений об ошибках

Joi.string().min(5).messages({
  'string.min': 'Строка слишком короткая'
})

Поддерживаются коды ошибок:

  • string.base
  • string.min
  • string.max
  • string.length
  • string.pattern.base
  • string.email
  • string.uri

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

Joi применяет правила в определённом порядке:

  1. Приведение типов
  2. Трансформации (trim, lowercase, uppercase)
  3. Проверки формата (email, uri, pattern)
  4. Ограничения длины
  5. Проверка допустимых значений (valid, invalid)

Это важно при комбинировании нескольких методов.

Комбинированные схемы

Пример комплексной строки:

Joi.string()
  .trim()
  .lowercase()
  .min(3)
  .max(30)
  .pattern(/^[a-z0-9_]+$/)
  .required()

Такая схема описывает:

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

Особенности строгого режима

При включённом strict:

  • отсутствует автоматическое приведение типов
  • число 123 не считается строкой "123"
  • повышается предсказуемость валидации
Joi.string().strict()

Поведение при ошибках

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

  • тип ошибки
  • описание нарушения
  • контекст (ожидаемая длина, шаблон и т.д.)

Это позволяет строить детализированную обработку ошибок на уровне приложения.

Оглавление