Объяснение ошибки через invalidExplanation

В библиотеке Luxon любые операции с датами и временем строго валидируются. Если входные данные некорректны или операция невозможна, результатом становится объект DateTime, находящийся в состоянии инвалидности (invalid). Вместо того чтобы возвращать null, undefined или выбрасывать исключение, Luxon формирует объект с признаком isValid === false. Центральным механизмом диагностики причин такой ошибки выступает свойство invalidExplanation.

Модель невалидного DateTime

Каждый экземпляр DateTime в Luxon содержит внутреннее состояние валидности. При успешном создании или преобразовании:

  • isValid === true
  • invalidReason === null
  • invalidExplanation === null

При ошибке:

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

Пример базового доступа:

import { DateTime } from "luxon";

const dt = DateTime.fromISO("2024-99-99");

console.log(dt.isValid); // false
console.log(dt.invalidReason); // 'unparsable'
console.log(dt.invalidExplanation); // подробное объяснение

invalidExplanation как диагностический слой

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

Он отвечает на вопрос не «что сломалось», а «почему это не удалось интерпретировать».

Типичная структура:

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

Основные причины появления invalidExplanation

Некорректный формат строки

При парсинге ISO-строки или пользовательского формата Luxon строго проверяет соответствие стандарту.

const dt = DateTime.fromISO("2023-13-40");
console.log(dt.invalidExplanation);

Типичная интерпретация:

  • месяц выходит за пределы 1–12
  • день не существует в указанном месяце

Ошибки в таймзоне

Luxon зависит от IANA time zone database. Любая ошибка в идентификаторе приводит к невалидному объекту.

const dt = DateTime.fromObject(
  { year: 2024, month: 5, day: 10 },
  { zone: "Europe/Mars" }
);

console.log(dt.invalidExplanation);

Типичная причина:

  • неизвестная или несуществующая зона времени

Отсутствующие обязательные поля

Некоторые методы требуют полного набора параметров. При их отсутствии формируется ошибка.

const dt = DateTime.fromObject({ month: 5, day: 10 });

console.log(dt.invalidExplanation);

Причина:

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

Несовместимые комбинации параметров

Luxon не позволяет логически противоречивые комбинации, например:

  • несуществующее время (25:61)
  • переходы DST, приводящие к пропущенным или повторяющимся часам
const dt = DateTime.fromObject({
  year: 2024,
  month: 3,
  day: 31,
  hour: 25
});

console.log(dt.invalidExplanation);

invalidExplanation и invalidReason: различие уровней

Свойство Назначение Формат
invalidReason Код ошибки короткая строка (unparsable, unsupported zone)
invalidExplanation текстовое объяснение человекочитаемое описание

invalidReason используется для программной логики:

if (dt.invalidReason === "unparsable") {
  // обработка ошибки парсинга
}

invalidExplanation используется для логирования, отладки и отображения:

console.log(dt.invalidExplanation);

Поведение invalidExplanation в разных сценариях

fromISO

При разборе ISO-строк Luxon пытается строго интерпретировать стандарт:

const dt = DateTime.fromISO("2024-02-30T10:00:00");

console.log(dt.invalidExplanation);

Причина формируется на основе:

  • невозможной даты (февраль не содержит 30 дней)
  • нарушения календарной логики

fromFormat

При пользовательских форматах ошибка чаще связана с несоответствием шаблону:

const dt = DateTime.fromFormat("31-02-2024", "dd-MM-yyyy");

console.log(dt.invalidExplanation);

Типичные причины:

  • несоответствие формату
  • невозможная календарная комбинация

fromObject

Этот метод наиболее чувствителен к логическим ошибкам:

const dt = DateTime.fromObject({
  year: 2024,
  month: 2,
  day: 30
});

console.log(dt.invalidExplanation);

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

Особенности генерации сообщений invalidExplanation

Luxon не использует статические строки для всех ошибок. Сообщение формируется динамически на основе:

  • типа операции (parsing, construction, conversion)
  • конкретного поля, вызвавшего сбой
  • контекста (таймзона, локаль, формат)

Это делает invalidExplanation более информативным, чем стандартные ошибки JavaScript.

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

Если DateTime уже находится в невалидном состоянии, все последующие операции сохраняют его состояние:

const dt1 = DateTime.fromISO("invalid-date");
const dt2 = dt1.plus({ days: 5 });

console.log(dt2.isValid); // false
console.log(dt2.invalidExplanation);

Причина не меняется — она наследуется от исходного сбоя.

Использование invalidExplanation в диагностике

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

  • выявление проблемных входных данных
  • диагностика API-ответов
  • логирование ошибок парсинга пользовательского ввода
  • отладка временных зон и DST-аномалий

Типичные категории сообщений invalidExplanation

Форматные ошибки

  • несоответствие шаблону
  • невозможный синтаксис даты

Календарные ошибки

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

Таймзонные ошибки

  • неизвестная зона
  • конфликт переходов DST

Неполные данные

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

Взаимосвязь invalidExplanation с внутренней моделью Luxon

Внутри Luxon объект DateTime не выбрасывает исключения, а сохраняет состояние ошибки в виде:

  • _isValid
  • _invalidReason
  • _invalidExplanation

Это обеспечивает:

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

Поведение при сериализации

При преобразовании в строку невалидный объект не маскирует ошибку:

const dt = DateTime.fromISO("2024-99-99");

console.log(dt.toISO()); // null
console.log(dt.invalidExplanation);

invalidExplanation остаётся доступным даже после попыток форматирования.

Практическая ценность invalidExplanation

В системах, где данные о времени поступают из внешних источников, это свойство становится ключевым инструментом:

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

Его основная роль — сделать ошибку объяснимой без необходимости разбирать внутренние коды Luxon или анализировать исходные строки вручную.

Оглавление