Обработка ошибок при разборе

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

Основная модель ошибок разбора

При любом разборе строки или объекта в DateTime результатом всегда является экземпляр DateTime, даже если входные данные некорректны.

Ключевое поведение:

  • при успешном разборе создаётся валидный DateTime
  • при ошибке создаётся объект DateTime, помеченный как невалидный
  • исключения по умолчанию не выбрасываются

Состояние определяется через свойства:

  • isValid
  • invalidReason
  • invalidExplanation

Поведение методов разбора

ISO-разбор

Метод:

DateTime.fromISO(value)

При корректной строке ISO возвращается валидный объект. При ошибках форматирования результат остаётся объектом DateTime, но с флагом невалидности.

Примеры некорректных входных данных:

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

Разбор по формату

Метод:

DateTime.fromFormat(value, format)

Механизм более чувствителен к несоответствию шаблону. Ошибки возникают при:

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

При этом результат не вызывает исключение, а возвращает невалидный DateTime.

Разбор из JS Date

Метод:

DateTime.fromJSDate(date)

Ошибки возникают при:

  • передаче Invalid Date
  • передаче некорректного объекта вместо Date

Проверка валидности результата

Главный механизм обработки ошибок основан на проверке:

dt.isValid

Если значение false, объект считается невалидным и не должен использоваться в вычислениях.

Дополнительно доступны диагностические свойства:

  • dt.invalidReason — краткий код причины
  • dt.invalidExplanation — текстовое описание проблемы

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

Наиболее распространённые значения invalidReason:

  • unsupported — неподдерживаемая операция или формат
  • unparsable — невозможность разобрать входную строку
  • invalidInput — некорректный тип входных данных
  • outOfRange — значение выходит за допустимые границы календаря

Каждая причина отражает конкретный этап внутреннего процесса парсинга: токенизация, проверка диапазонов или интерпретация формата.

Объект Invalid DateTime

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

Создание такого объекта возможно напрямую:

DateTime.invalid("reason", "explanation")

Это позволяет:

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

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

Все методы DateTime сохраняют принцип «не прерывать цепочку при ошибке».

Пример логики:

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

Это означает, что первичная причина сохраняется и распространяется дальше по цепочке.

Строгое поведение через настройки

Luxon содержит глобальную настройку, влияющую на стратегию обработки ошибок:

Settings.throwOnInvalid = true

При включении:

  • вместо возврата невалидного DateTime выбрасывается исключение
  • контроль ошибок переносится на уровень try/catch
  • поведение становится ближе к классическим API с исключениями

При выключенном режиме:

  • ошибки инкапсулируются в объекте
  • выполнение продолжается без прерывания

Ошибки локали и зоны времени

Некорректные значения могут возникать не только при разборе даты, но и при интерпретации дополнительных параметров:

Часовые пояса

Ошибки:

  • неизвестная временная зона
  • некорректный идентификатор зоны

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

Типовые сценарии некорректного разбора

Некорректный ISO-формат

DateTime.fromISO("2024-99-99")

Результат:

  • isValid = false
  • причина: выход за диапазон календаря

Несоответствие формату строки

DateTime.fromFormat("31/02/2024", "dd/MM/yyyy")

Результат:

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

Некорректный тип входных данных

DateTime.fromISO(null)

Результат:

  • invalidInput
  • объяснение: ожидалась строка

Диагностический анализ ошибок

При работе с невалидными объектами основную роль играет комбинация трёх свойств:

  • isValid — бинарное состояние
  • invalidReason — классификация ошибки
  • invalidExplanation — человекочитаемая диагностика

Такая модель позволяет:

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

Особенности распространения ошибок

В цепочках преобразований поведение стабильно:

  • ошибка не изменяется при вызове .setZone, .plus, .minus
  • повторное форматирование не исправляет состояние
  • любые вычисления возвращают невалидный результат

Это предотвращает скрытое восстановление некорректных данных.

Сравнение двух стратегий обработки

Без исключений (по умолчанию)

  • ошибки инкапсулируются в объект
  • выполнение не прерывается
  • требуется проверка isValid

С исключениями

  • ошибки выбрасываются сразу
  • контроль переносится на try/catch
  • используется явная обработка потока выполнения

Внутренний механизм фиксации ошибки

При парсинге Luxon выполняет последовательность этапов:

  1. первичная проверка типа входных данных
  2. разбор строки по токенам
  3. валидация диапазонов календаря
  4. сборка внутреннего представления
  5. установка состояния валидности

На любом этапе может быть зафиксировано состояние ошибки, после чего объект переводится в режим invalid.

Стабильность поведения при ошибках

Система обработки ошибок построена таким образом, чтобы:

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

Такая архитектура делает обработку дат детерминированной даже при некорректных входных данных.

Оглавление