Инспекция внутреннего состояния

Представление момента времени и базовые поля

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

Ключевым ядром служит момент времени в виде Unix-таймстампа:

  • ts — миллисекунды с эпохи Unix (UTC-основание)
  • zone — временная зона, определяющая интерпретацию ts
  • locale — локаль форматирования
  • invalid — состояние валидности объекта

Хотя Luxon скрывает внутреннюю структуру, логически она сводится к сочетанию абсолютного времени и набора метаданных, влияющих на отображение и преобразование.

Валидность как часть внутреннего состояния

Одним из ключевых аспектов инспекции является проверка корректности объекта. Любой DateTime может находиться в валидном или невалидном состоянии.

Основные свойства:

  • isValid — булево значение, отражающее корректность экземпляра
  • invalidReason — краткий код причины ошибки
  • invalidExplanation — человекочитаемое описание проблемы

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

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

Пример инспекции:

import { DateTime } from "luxon";

const dt = DateTime.fromISO("2025-02-30");

dt.isValid; // false
dt.invalidReason; // "invalidDate"
dt.invalidExplanation; // "the date is not valid because February 30 does not exist"

Состояние валидности распространяется на все последующие операции: любые преобразования сохраняют невалидность, если исходный объект был некорректен.

Временная зона как часть состояния

Внутреннее состояние включает информацию о временной зоне, которая влияет на интерпретацию timestamp.

Основные элементы:

  • zoneName (через zone.name) — идентификатор зоны (например, “UTC”, “Europe/Berlin”)
  • смещение относительно UTC
  • правила перехода на летнее время

Инспекция зоны:

const dt = DateTime.now().setZone("Europe/Berlin");

dt.zoneName;      // "Europe/Berlin"
dt.offset;        // смещение в минутах
dt.isInDST;       // участие в летнем времени

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

Локаль и культурный контекст

Отдельный слой состояния связан с локализацией:

  • locale — влияет на формат дат, названия месяцев и дней недели
  • numberingSystem — система счисления (например, латинская или арабская)
  • outputCalendar — календарная система (gregory, islamic, buddhist и др.)

Инспекция локали:

const dt = DateTime.now().setLocale("fr");

dt.locale; // "fr"
dt.toLocaleString(); // форматирование с французскими правилами

Локаль не влияет на внутренний timestamp, но определяет отображаемую форму.

Форматы представления и их связь с состоянием

Luxon предоставляет несколько способов инспекции текущего состояния объекта через сериализацию.

ISO-представление

dt.toISO();

Отражает состояние с учётом зоны и точности.

JSON-представление

dt.toJSON();

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

Преобразование в JS Date

dt.toJSDate();

Возвращает стандартный объект JavaScript, теряя часть контекста Luxon (например, локаль и зону как объектную сущность).

Внутренняя структура и неизменяемость

Объекты Luxon не модифицируются после создания. Любая операция порождает новый экземпляр с изменённым состоянием.

Примеры операций, создающих новые состояния:

  • setZone
  • setLocale
  • plus / minus
  • set
const dt1 = DateTime.now();
const dt2 = dt1.setZone("UTC");

dt1 === dt2; // false

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

Состояние при создании объекта

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

  • fromISO — парсинг ISO-строки
  • fromMillis — создание из timestamp
  • fromObject — сборка из компонент
  • now — текущее системное время

Каждый источник формирует различный набор внутренних флагов валидности и контекста.

DateTime.fromMillis(0).toISO(); // 1970-01-01T00:00:00.000Z
DateTime.fromObject({ year: 2024, month: 2, day: 30 }).isValid; // false

Инспекция через строковое представление

Для анализа состояния часто используются методы форматирования:

  • toString() — диагностическое представление
  • toFormat() — кастомное форматирование
  • toLocaleString() — локализованное отображение
const dt = DateTime.now();

dt.toString();
// например: "2026-01-24T10:15:30.000+03:00"

Строковое представление отражает сразу несколько аспектов состояния: timestamp, зону и смещение.

Календарная система и её влияние

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

  • gregory (по умолчанию)
  • islamic
  • buddhist
  • hebrew
const dt = DateTime.now().reconfigure({
  outputCalendar: "buddhist"
});

dt.outputCalendar;

Календарная система влияет на отображение года, месяца и дня, но не изменяет базовый timestamp.

Состояние длительностей и интервалов

Помимо DateTime, инспекция распространяется на другие сущности:

Duration

const dur = Duration.fromObject({ hours: 2, minutes: 30 });

dur.as("minutes"); // 150
dur.isValid;

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

Interval

const i = Interval.fromDateTimes(dt1, dt2);

i.isValid;
i.length("hours");

Интервал включает два DateTime, и его состояние зависит от корректности границ.

Ошибочные состояния и их диагностика

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

Типовые сценарии:

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

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

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

dt.isValid; // false
dt.invalidReason;
dt.invalidExplanation;

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

Каждая операция формирует новую версию состояния, сохраняя предыдущее неизменным:

const dt = DateTime.now()
  .setZone("UTC")
  .setLocale("de")
  .plus({ days: 1 });

На каждом этапе изменяется только часть состояния:

  • зона влияет на интерпретацию времени
  • локаль — на форматирование
  • арифметика — на timestamp

Сводная модель инспекции состояния

Внутреннее состояние DateTime можно концептуально разложить на слои:

  • Абсолютный слой: timestamp (ts)
  • Географический слой: временная зона (zone, offset)
  • Культурный слой: locale, numberingSystem, outputCalendar
  • Логический слой: valid/invalid состояние
  • Операционный слой: результаты цепочек преобразований

Такое разделение позволяет анализировать поведение объекта независимо от конкретного метода его создания или преобразования.

Оглавление