Программная валидация

Общая модель валидации

В Inputmask программная валидация строится вокруг идеи синхронизации введённого значения с маской в реальном времени и возможности принудительной проверки строки независимо от DOM-событий. Маска выступает не только как средство форматирования, но и как детерминированный валидатор, основанный на конфигурации mask, definitions, regex и дополнительных параметрах поведения ввода.

Валидация может происходить в нескольких режимах:

  • интерактивная (по мере ввода)
  • постобработка значения (blur/submit)
  • программная проверка строки без привязки к input
  • полная переоценка состояния через API экземпляра маски

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

Проверка строки через isValid

Основной программный механизм валидации — метод isValid, доступный через экземпляр Inputmask.

const im = new Inputmask("9999-9999");
im.isValid("1234-5678");

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

Внутренне проверка выполняет:

  • разбор строки по позициям маски
  • сопоставление символов с definitions
  • проверку обязательных и необязательных сегментов
  • учет greedy, repeat, optional правил

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

Валидация через Inputmask.prototype

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

Inputmask("AA-9999").isValid("AB-1234");

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

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

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

Механизм включает:

  • проверку допустимости символа по definition
  • блокировку недопустимых вводов
  • автозамены (например, ~ в числовых масках)
  • обработку вставки (paste) как последовательности символов

Таким образом, поле всегда находится в состоянии «валидного частичного префикса».

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

Для пересчёта состояния маски используется метод setValue, который инициирует повторную валидацию:

const im = new Inputmask("999-999");
const input = document.querySelector("input");

im.mask(input);
im.setValue("1234567");

При установке значения:

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

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

Метод getValue возвращает текущее значение с учётом маски, но не всегда отражает валидность в строгом смысле.

const value = im.getValue();
const valid = im.isValid(value);

Разделение логики:

  • getValue — текущее отображаемое значение
  • isValid — строгая проверка соответствия шаблону

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

Частичная валидация и состояние incomplete

Inputmask различает:

  • полностью валидное значение
  • частично заполненное значение
  • некорректный ввод

Частично заполненное состояние определяется через внутренний флаг isComplete.

input.addEventListener("blur", function () {
    const im = input.inputmask;
    console.log(im.isComplete());
});

Если маска не заполнена полностью, но не нарушена структура, значение считается «incomplete», а не «invalid».

Использование onBeforeValidate и oncomplete

Расширенная программная валидация может быть реализована через события жизненного цикла маски.

Inputmask({
  mask: "9999-9999",
  oncomplete: function () {
    console.log("complete");
  },
  onincomplete: function () {
    console.log("incomplete");
  },
  onBeforeWrite: function (event, buffer, caretPos, opts) {
    return {
      refreshFromBuffer: true
    };
  }
}).mask(input);

Ключевые точки контроля:

  • oncomplete — срабатывает при полном соответствии маске
  • onincomplete — при потере соответствия после ввода
  • onBeforeWrite — возможность вмешательства в процесс записи

Программная проверка без DOM

Inputmask позволяет выполнять валидацию как чистую функцию преобразования строки.

const mask = new Inputmask({
  mask: "(999) 999-9999"
});

const result = mask.isValid("(123) 456-7890");

Такой режим используется:

  • при валидации данных API
  • при проверке импортированных значений
  • в серверных и Node.js сценариях (при наличии адаптации окружения)

Валидация с кастомными definitions

Система definitions позволяет расширять правила допустимых символов, что напрямую влияет на программную валидацию.

Inputmask.extendDefinitions({
  "h": {
    validator: "[A-Fa-f0-9]",
    casing: "upper"
  }
});

Маска:

const im = new Inputmask("hh-hh-hh");

Проверка:

im.isValid("AF-1B-3C");

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

Регулярные выражения как основа валидации

Inputmask поддерживает режим regex, где вся валидация делегируется регулярному выражению.

const im = new Inputmask({
  regex: "[0-9]{4}-[A-Z]{3}"
});

Проверка:

im.isValid("1234-ABC");

В этом режиме:

  • маска не разбивается на позиции
  • вся строка проверяется целиком
  • отсутствует пошаговая валидация ввода

Программная инвалидация и сброс состояния

Сброс маски приводит к очищению состояния и повторной инициализации буфера:

const im = new Inputmask("999-999");

im.setValue("");

При этом:

  • очищается buffer
  • сбрасываются флаги complete/incomplete
  • пересчитывается caret position
  • состояние становится нейтральным

Валидация вставляемых значений

Вставка (paste) обрабатывается как отдельный поток данных. При программной проверке учитывается:

  • последовательная обработка символов
  • применение маски ко всей вставленной строке
  • фильтрация недопустимых символов

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

input.value = "123ABC456";
input.dispatchEvent(new Event("input"));

Inputmask преобразует строку в допустимый формат или блокирует вставку частично.

Проверка через metadata состояния маски

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

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

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

const im = input.inputmask;

console.log(im.maskset);
console.log(im.opts);

Хотя прямое использование этих структур не является публичным API, они часто применяются для глубокой диагностики состояния валидации.

Комбинированная программная проверка

Сложные сценарии используют комбинацию методов:

const im = new Inputmask("9999-AAAA");
im.mask(input);

function validate() {
  const value = im.getValue();
  const isValid = im.isValid(value);
  const isComplete = im.isComplete();

  return isValid && isComplete;
}

Такой подход позволяет различать:

  • технически корректные, но неполные значения
  • полностью завершённые валидные значения
  • синтаксически неверные вводы

Приоритеты валидации

Система Inputmask использует иерархию правил:

  1. definitions (символьные ограничения)
  2. mask pattern (структура)
  3. regex (если задан)
  4. пользовательские события (onBeforeWrite, onBeforePaste)
  5. финальная проверка isValid

Эта цепочка обеспечивает предсказуемость результата вне зависимости от источника данных.

Асинхронные сценарии и внешняя валидация

Хотя Inputmask является синхронной библиотекой, его результаты часто используются в асинхронных процессах:

  • отправка формы
  • валидация на сервере
  • проверка перед сохранением
async function submit() {
  const value = im.getValue();

  if (!im.isValid(value)) {
    return;
  }

  await sendToServer(value);
}

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

Оглавление