API референс

Библиотека Validator.js представляет собой набор функций для проверки и валидации строковых данных. В основе API лежит набор независимых методов, каждый из которых решает одну задачу: проверка формата, диапазона, структуры или соответствия стандарту. Все функции работают с типом string, приводя входные данные к строке перед проверкой.

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

import validator from 'validator';

или в CommonJS:

const validator = require('validator');

API построено как плоский объект, где каждый метод доступен напрямую:

validator.isEmail('test@mail.com');
validator.isURL('https://example.com');

Базовые правила работы API

Большинство функций Validator.js придерживаются единых принципов:

  • входные данные приводятся к строке (value + '')
  • пустые строки часто считаются невалидными (если не указано обратное)
  • строгая проверка формата без побочных эффектов
  • отсутствие мутаций входных данных

Некоторые методы принимают дополнительные параметры в виде объекта с настройками, позволяющими изменять поведение проверки.

Методы проверки строковых значений

Проверка email

validator.isEmail(str [, options])

Проверяет соответствие строки стандарту email-адреса.

Основные опции:

  • allow_display_name — разрешает отображаемое имя
  • require_display_name — требует отображаемое имя
  • allow_utf8_local_part — разрешает UTF-8 в локальной части
  • ignore_max_length — игнорирует ограничение длины

Пример поведения:

  • user@example.com — валидно
  • user.name+tag@domain.co — валидно
  • invalid@ — невалидно

Проверка URL

validator.isURL(str [, options])

Проверяет корректность URL-адреса.

Ключевые опции:

  • protocols — допустимые протоколы (http, https, ftp)
  • require_protocol — обязательность протокола
  • require_host — наличие хоста
  • allow_underscores — разрешение символа _ в домене
  • host_whitelist / host_blacklist — фильтрация доменов

Пример:

  • https://example.com — валидно
  • ftp://files.server.net — валидно при включённом ftp
  • example.com — зависит от require_protocol

Проверка чисел

isNumeric

validator.isNumeric(str [, options])

Проверяет, состоит ли строка только из цифр.

Опции:

  • no_symbols — запрещает знаки +/-
  • locale — локализация чисел

Примеры:

  • "12345" — валидно
  • "-123" — валидно при разрешённых символах
  • "12.3" — невалидно без дополнительных настроек

isInt

validator.isInt(str [, options])

Проверяет целое число.

Опции:

  • min
  • max
  • allow_leading_zeroes

Примеры:

  • "10" — валидно
  • "10.5" — невалидно
  • "001" — зависит от настроек

isFloat

validator.isFloat(str [, options])

Проверяет число с плавающей точкой.

Опции:

  • min
  • max
  • locale

Проверка булевых значений

validator.isBoolean(str [, options])

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

  • "true", "false"
  • "1", "0"
  • "yes", "no"

Опции позволяют расширять список допустимых строк.

Методы проверки строковых форматов

isAlpha

validator.isAlpha(str [, locale])

Проверяет, содержит ли строка только буквы.

Поддерживаются локали:

  • en-US
  • ru-RU (ограниченно)
  • другие языки через расширения

isAlphanumeric

validator.isAlphanumeric(str [, locale])

Разрешает буквы и цифры без спецсимволов.

isLowercase / isUppercase

validator.isLowercase(str)
validator.isUppercase(str)

Проверка регистра символов без учёта локали.

isLength

validator.isLength(str, options)

Проверяет длину строки:

  • min
  • max

Пример:

validator.isLength('hello', { min: 3, max: 10 });

isUUID

validator.isUUID(str [, version])

Поддерживаемые версии UUID:

  • 3
  • 4
  • 5
  • all

isDate

validator.isDate(str [, options])

Проверка даты в строковом формате.

Опции:

  • format — ожидаемый формат
  • strictMode — строгий режим

isJSON

validator.isJSON(str)

Проверяет валидность JSON-строки.

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

  • требует строгого соответствия синтаксису JSON
  • не допускает комментарии или trailing commas

Методы проверки идентификаторов и системных значений

isMongoId

validator.isMongoId(str)

Проверяет ObjectId MongoDB (24 hex символа).

isJWT

validator.isJWT(str)

Проверяет структуру JSON Web Token.

isHash

validator.isHash(str, algorithm)

Поддерживаемые алгоритмы:

  • md5
  • sha1
  • sha256
  • sha512
  • ripemd160

Методы проверки IP и сетевых данных

isIP

validator.isIP(str [, version])

Поддержка:

  • 4 (IPv4)
  • 6 (IPv6)
  • 0 (оба варианта)

isMACAddress

validator.isMACAddress(str [, options])

Форматы:

  • 00:1B:44:11:3A:B7
  • 00-1B-44-11-3A-B7

Методы проверки файлов и путей

isMimeType

validator.isMimeType(str)

Примеры:

  • image/png
  • application/json

isSlug

validator.isSlug(str)

Проверяет SEO-friendly строки:

  • my-url-title
  • article-2024

Методы нормализации и преобразования

trim

validator.trim(str [, chars])

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

escape

validator.escape(str)

Экранирует HTML-символы:

  • < → &lt;
  • > → &gt;
  • & → &amp;

unescape

validator.unescape(str)

Обратное преобразование HTML-сущностей в символы.

Методы очистки данных

blacklist

validator.blacklist(str, chars)

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

whitelist

validator.whitelist(str, chars)

Оставляет только разрешённые символы.

Методы сравнения и диапазонов

equals

validator.equals(str, comparison)

Строгое сравнение строк.

contains

validator.contains(str, seed [, options])

Проверка наличия подстроки.

Опции:

  • ignoreCase
  • minOccurrences

matches

validator.matches(str, pattern)

Сравнение с регулярным выражением.

Проверка локальных форматов

isMobilePhone

validator.isMobilePhone(str [, locale])

Поддержка множества стран:

  • ru-RU
  • en-US
  • en-GB
  • zh-CN

Форматы зависят от региональных правил.

isPostalCode

validator.isPostalCode(str, locale)

Проверка почтовых индексов по странам.

Расширенные возможности API

Опциональные строгие режимы

Многие функции поддерживают строгие режимы проверки, которые отключают “гибкое” поведение и требуют полного соответствия стандарту.

Локализация

Некоторые методы принимают параметр locale, изменяющий:

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

Композиция проверок

Validator.js не навязывает цепочки вызовов, но функции часто комбинируются вручную:

validator.isLength(str, { min: 5 }) &&
validator.isAlphanumeric(str)

Иммутабельность поведения

Все функции:

  • не изменяют входные данные
  • возвращают boolean или преобразованную строку
  • не зависят от глобального состояния

Категоризация API

Валидация форматов

  • email
  • URL
  • IP
  • MAC
  • UUID

Числовая проверка

  • isInt
  • isFloat
  • isNumeric

Строковые правила

  • isLength
  • isAlpha
  • isAlphanumeric
  • isLowercase
  • isUppercase

Системные идентификаторы

  • isMongoId
  • isJWT
  • isHash

Очистка и трансформация

  • trim
  • escape
  • unescape
  • blacklist
  • whitelist

Сетевые форматы

  • isIP
  • isURL
  • isMobilePhone
  • isPostalCode
Оглавление