Свойства и методы Duration

В Luxon длительность представляется объектом Duration, который описывает промежуток времени в абстрактных единицах (часы, минуты, дни и т.д.), не привязываясь к конкретной дате и часовому поясу. В отличие от DateTime, этот тип не указывает момент времени, а моделирует именно продолжительность.

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

Базовая структура и внутренние данные

Экземпляр Duration хранит набор значений в виде объекта полей времени:

{
  years,
  months,
  weeks,
  days,
  hours,
  minutes,
  seconds,
  milliseconds
}

Эти значения доступны через метод:

duration.toObject()

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

Основные свойства экземпляра Duration

isValid и invalid

Состояние валидности является ключевым свойством любого объекта Luxon.

  • isValid — булево значение, указывающее корректность длительности.
  • invalid — объект с причиной ошибки, если длительность некорректна.
const d = luxon.Duration.fromObject({ hours: 2 });
d.isValid; // true

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

locale и numberingSystem

Длительность может учитывать локализацию при форматировании.

  • locale — строка локали ("ru", "en", "de" и т.д.)
  • numberingSystem — система чисел (например, "latn")

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

const d = luxon.Duration.fromObject({ minutes: 5 }).setLocale("ru");

values (логическая модель хранения)

Хотя напрямую поле values не является публичным API, логически оно отражает структуру длительности. Для работы с ним используется:

duration.toObject()

Получение значений длительности

as(unit)

Метод возвращает значение длительности в указанной единице.

const d = luxon.Duration.fromObject({ hours: 2 });

d.as("minutes"); // 120
d.as("seconds"); // 7200

Поддерживаемые единицы: years, months, weeks, days, hours, minutes, seconds, milliseconds.

get(unit)

Возвращает значение конкретного поля без преобразования в другие единицы.

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

d.get("hours");   // 2
d.get("minutes"); // 30

В отличие от as, метод не выполняет пересчёт между единицами.

toObject()

Возвращает нормализованное представление длительности в виде объекта.

const d = luxon.Duration.fromObject({ minutes: 90 });

d.toObject(); // { minutes: 90 }

После нормализации (например, через normalize) структура может измениться.

valueOf() и toMillis()

Оба метода возвращают длительность в миллисекундах.

const d = luxon.Duration.fromObject({ seconds: 2 });

d.valueOf();  // 2000
d.toMillis(); // 2000

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

Арифметические операции над Duration

plus()

Сложение длительностей с автоматическим объединением единиц.

const d1 = luxon.Duration.fromObject({ hours: 1 });
const d2 = luxon.Duration.fromObject({ minutes: 30 });

const result = d1.plus(d2);
result.toObject(); // { hours: 1, minutes: 30 }

При наличии пересекающихся единиц Luxon может выполнять нормализацию.

minus()

Вычитание длительности.

const d1 = luxon.Duration.fromObject({ hours: 2 });
const d2 = luxon.Duration.fromObject({ minutes: 30 });

const result = d1.minus(d2);

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

negate()

Инверсия знака длительности.

const d = luxon.Duration.fromObject({ hours: 2 });
const neg = d.negate();

neg.toObject(); // { hours: -2 }

Используется при построении обратных интервалов.

Преобразование единиц и нормализация

mapUnits()

Позволяет трансформировать каждую единицу длительности через функцию.

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

const result = d.mapUnits(value => value * 2);

result.toObject(); // { hours: 4, minutes: 60 }

Метод полезен для масштабирования интервалов времени.

normalize()

Приводит длительность к «естественному» виду, перераспределяя значения между единицами.

const d = luxon.Duration.fromObject({ minutes: 120 });

const normalized = d.normalize();
normalized.toObject(); // { hours: 2 }

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

shiftTo()

Переводит длительность в заданные единицы, перераспределяя значения.

const d = luxon.Duration.fromObject({ seconds: 3600 });

const shifted = d.shiftTo("hours");
shifted.toObject(); // { hours: 1 }

Можно указывать несколько единиц:

d.shiftTo("hours", "minutes");

reconfigure()

Изменяет конфигурацию длительности без изменения самих значений.

const d = luxon.Duration.fromObject({ hours: 1 });

const updated = d.reconfigure({ locale: "ru" });

Метод используется для изменения параметров отображения.

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

toHuman()

Формирует человеко-читаемую строку с учётом локали.

const d = luxon.Duration.fromObject({ hours: 1, minutes: 30 });

d.toHuman(); // "1 hour, 30 minutes"

При установленной локали результат адаптируется под язык:

d.setLocale("ru").toHuman(); // "1 час, 30 минут"

toISO()

Возвращает ISO 8601 представление длительности.

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

d.toISO(); // "PT2H30M"

Формат соответствует стандарту ISO 8601 для интервалов времени.

toISOTime()

Представляет длительность как временной интервал, интерпретируемый как время суток.

const d = luxon.Duration.fromObject({ hours: 1, minutes: 15 });

d.toISOTime(); // "01:15:00"

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

toString()

Возвращает строковое представление объекта, обычно близкое к ISO.

const d = luxon.Duration.fromObject({ minutes: 90 });

d.toString(); // "PT1H30M" или аналогичный формат

Сравнение и приведение типов

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

const d1 = luxon.Duration.fromObject({ seconds: 10 });
const d2 = luxon.Duration.fromObject({ seconds: 20 });

d1 < d2; // true

Такое поведение возможно благодаря valueOf(), возвращающему числовое значение.

Работа с отрицательными и смешанными значениями

Duration поддерживает отрицательные интервалы:

const d = luxon.Duration.fromObject({ hours: -1, minutes: 30 });

При операциях сложения и вычитания отрицательные значения распространяются по правилам арифметики длительностей.

Особенности внутренней модели

  1. Длительность не привязана к календарю, но может учитывать его при нормализации.
  2. Разные единицы могут сосуществовать без автоматического преобразования.
  3. Преобразование в миллисекунды используется как базовая числовая модель.
  4. Форматирование отделено от вычислений и выполняется отдельно.

Комбинирование методов

Типичный сценарий обработки длительности включает цепочку преобразований:

const d = luxon.Duration
  .fromObject({ seconds: 5400 })
  .shiftTo("hours", "minutes")
  .normalize()
  .toHuman();

Каждый этап отвечает за отдельный аспект:

  • shiftTo — выбор единиц
  • normalize — перераспределение значений
  • toHuman — форматирование вывода
Оглавление