Получение причины ошибки через invalidReason

В библиотеке Luxon любой объект DateTime, Duration или Interval может оказаться в состоянии невалидности. Это не исключение в привычном смысле, а встроенный механизм моделирования ошибок работы с датами и временем. Вместо выбрасывания исключений при каждом некорректном вводе Luxon возвращает объект с флагом isValid: false, а причину фиксирует в поле invalidReason.

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

Общее устройство механизма невалидных значений

Каждый экземпляр временных сущностей Luxon содержит три ключевых элемента состояния:

  • isValid — булев флаг корректности
  • invalidReason — краткий код причины ошибки
  • invalidExplanation — расширенное текстовое пояснение

Основная диагностическая логика сосредоточена именно в invalidReason, поскольку он стандартизирован и стабилен между версиями.

Когда появляется invalidReason

Поле invalidReason устанавливается только в случае, если объект не может быть корректно интерпретирован. При успешном создании значения оно остаётся null.

Типовые ситуации возникновения невалидности:

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

Основные значения invalidReason

unparsable

Возникает при невозможности разобрать входную строку или значение.

Типичные случаи:

  • DateTime.fromISO("abc")
  • DateTime.fromFormat("32-13-2020", "dd-MM-yyyy")

Причина фиксируется, когда парсер не может сопоставить вход с допустимым форматом.

invalid input

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

Примеры:

  • нечисловые значения для компонентов даты
  • NaN в полях времени
  • undefined в обязательных параметрах

unit out of range

Фиксируется при выходе числовых компонентов за допустимые границы календаря.

Примеры:

  • месяц 13
  • день 0
  • час 25

Luxon не нормализует такие значения автоматически, а помечает объект как невалидный.

missing field

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

Часто встречается при ручной сборке через DateTime.fromObject.

unsupported zone

Связан с некорректной или неизвестной временной зоной.

Примеры:

  • опечатка в идентификаторе зоны
  • использование несуществующего IANA-идентификатора

mismatched zone

Появляется при конфликте между указанной зоной и входными данными, особенно при парсинге строк с уже встроенной временной зоной.

invalid interval

Специфично для Interval. Возникает, когда:

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

Как работает связка isValid и invalidReason

Любой невалидный объект в Luxon следует единому принципу:

  • isValid === false — главный индикатор ошибки
  • invalidReason — код категории ошибки
  • invalidExplanation — человекочитаемое описание

Логика всегда начинается с проверки флага:

const dt = DateTime.fromISO("not-a-date");

if (!dt.isValid) {
  console.log(dt.invalidReason);
}

invalidReason никогда не используется без проверки isValid, так как для корректных объектов он равен null.

Приоритеты и неизменяемость invalidReason

После создания объекта значение invalidReason:

  • не изменяется при дальнейших операциях
  • не “исправляется” автоматически при chain-выражениях
  • наследуется при преобразованиях

Пример:

const dt = DateTime.fromISO("bad input")
  .plus({ days: 2 })
  .setZone("UTC");

Результат останется невалидным, а invalidReason сохранится прежним.

Поведение при цепочках операций

Любая операция над невалидным объектом:

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

Это важно для предотвращения «тихих» ошибок в вычислениях времени.

Отличие invalidReason от invalidExplanation

invalidReason

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

invalidExplanation

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

Пример связки:

  • invalidReason: "unsupported zone"
  • invalidExplanation: "zone 'Europe/Nowhere' is not recognized"

Диагностика сложных цепочек ошибок

В сложных вычислениях важно понимать, что Luxon фиксирует первую критическую ошибку и не пересчитывает причину дальше.

Пример:

DateTime.fromObject({
  year: 2020,
  month: 13,
  day: 40
});

Здесь будет зафиксирован unit out of range, даже если несколько полей некорректны одновременно.

Практическое использование invalidReason в логике приложений

Типичный паттерн обработки:

const dt = DateTime.fromFormat(input, "yyyy-MM-dd");

switch (dt.invalidReason) {
  case "unparsable":
    // обработка строки формата
    break;
  case "unit out of range":
    // корректировка пользовательского ввода
    break;
  case "unsupported zone":
    // fallback на UTC
    break;
}

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

Поведение в Duration и Interval

Duration

invalidReason появляется при:

  • отрицательных или некорректных компонентах
  • NaN значениях
  • невозможных комбинациях единиц

Interval

  • пересечение некорректных границ
  • отсутствие start/end
  • невалидные DateTime внутри интервала

Влияние строгого режима парсинга

Некоторые методы Luxon используют строгий парсинг, при котором:

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

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

Типовые причины в реальных приложениях

На практике чаще всего встречаются:

  • пользовательский ввод с неверным форматом даты
  • несоответствие локали при парсинге
  • неправильные временные зоны в API-ответах
  • ошибки сериализации JSON с датами
  • смещения времени при DST (daylight saving time)

Связь invalidReason и устойчивости системы

Модель ошибок Luxon построена так, чтобы:

  • исключить исключения (throw)
  • обеспечить детерминированность
  • дать точную причину сбоя
  • сохранить объектную модель даже при ошибке

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

Оглавление