Свойство isValid

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

Любой объект DateTime в Luxon существует в одном из двух состояний:

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

Свойство isValid позволяет программно определить текущее состояние экземпляра без необходимости анализа внутренних полей.

Поведение свойства isValid

Свойство isValid возвращает логическое значение:

  • true — объект представляет корректную дату и время;
  • false — объект содержит ошибку и не может быть использован в вычислениях.

Простейший пример использования:

import { DateTime } from "luxon";

const dt1 = DateTime.now();
console.log(dt1.isValid); // true

Невалидное значение возникает, например, при некорректном разборе строки:

const dt2 = DateTime.fromISO("invalid-date");
console.log(dt2.isValid); // false

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

Внутреннее состояние невалидного DateTime

При создании невалидного объекта DateTime библиотека сохраняет дополнительную диагностическую информацию:

  • invalidReason — краткий код причины ошибки;
  • invalidExplanation — текстовое описание проблемы.
const dt = DateTime.fromISO("2024-99-99");

console.log(dt.isValid); // false
console.log(dt.invalidReason); // "unit out of range"
console.log(dt.invalidExplanation); // объяснение ошибки

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

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

Состояние isValid === false возникает в нескольких типичных ситуациях:

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

DateTime.fromISO("2024-13-40"); // месяц и день вне диапазона

Отсутствие обязательных компонентов

DateTime.fromObject({ year: 2024 }); // недостаточно данных для полной даты

Ошибки при преобразованиях

const dt = DateTime.now().setZone("Unknown/Zone");
console.log(dt.isValid); // false

Некорректные арифметические операции

Некоторые операции, приводящие к выходу за допустимые диапазоны, также могут формировать невалидные состояния.

Поведение методов при невалидных объектах

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

const dt = DateTime.fromISO("invalid");
const shifted = dt.plus({ days: 5 });

console.log(shifted.isValid); // false

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

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

Свойство isValid используется как базовый механизм защиты от ошибок при работе с датами:

const dt = DateTime.fromISO(userInput);

if (dt.isValid) {
  console.log(dt.toISO());
} else {
  console.log("Ошибка даты");
}

Игнорирование проверки приводит к распространению невалидных объектов по цепочке вычислений.

Связь isValid с другими свойствами DateTime

isValid тесно связан с внутренними диагностическими полями объекта:

  • при isValid === true поля invalidReason и invalidExplanation отсутствуют или пусты;
  • при isValid === false эти поля содержат информацию о причине сбоя.

Также влияние распространяется на методы форматирования:

const dt = DateTime.invalid("custom error");

console.log(dt.isValid); // false
console.log(dt.toString()); // содержит информацию о невалидности

Невалидные DateTime и форматирование

Методы форматирования ведут себя предсказуемо при невалидных значениях:

const dt = DateTime.fromISO("bad input");

console.log(dt.toISO());      // null или строка ошибки (в зависимости от метода)
console.log(dt.toFormat("dd.MM.yyyy")); // невалидный результат

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

Наследование невалидности

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

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

const result = base
  .plus({ days: 10 })
  .set({ year: 2030 });

console.log(result.isValid); // false

Это правило обеспечивает предсказуемость: ошибка не «исправляется» автоматически и не исчезает в процессе цепочки вызовов.

Диагностика через isValid в сложных сценариях

При обработке больших потоков данных isValid используется как фильтр для очистки некорректных значений:

const inputs = ["2024-01-01", "bad", "2025-12-31"];

const dates = inputs
  .map(DateTime.fromISO)
  .filter(dt => dt.isValid);

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

Особенности поведения при сериализации

При преобразовании объектов DateTime в строки или JSON невалидные значения не приводятся к стандартным датам:

const dt = DateTime.fromISO("invalid");

JSON.stringify(dt); // содержит служебные поля или пустое значение

Поведение сериализации зависит от реализации метода toJSON, но всегда сохраняет признак невалидности.

Влияние локали и временной зоны

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

DateTime.now().setZone("fake/zone").isValid; // false

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

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

В цепочках методов Luxon проверка isValid часто выполняется в конце:

const dt = DateTime
  .fromISO("2024-01-01")
  .setZone("Europe/Paris")
  .plus({ months: 2 });

if (dt.isValid) {
  console.log(dt.toString());
}

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

Поведение при создании DateTime.invalid

Luxon позволяет явно создавать невалидные объекты:

const dt = DateTime.invalid("manual error", "custom reason");

console.log(dt.isValid); // false

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

Оглавление