Методы Duration

В библиотеке Luxon объект Duration представляет длительность времени, независимую от конкретной даты и времени. Он используется для описания интервалов вроде «2 часа 30 минут» или «5000 миллисекунд» и поддерживает преобразования между различными единицами измерения.

Duration.fromObject()

Создаёт длительность из набора полей времени.

Основные единицы:

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds
  • milliseconds

Пример структуры:

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

Особенности:

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

Duration.fromMillis()

Создаёт длительность из количества миллисекунд.

const dur = luxon.Duration.fromMillis(9000000);

Особенности:

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

Duration.fromISO()

Парсинг длительности в формате ISO 8601.

const dur = luxon.Duration.fromISO("PT2H30M");

Поддерживаемые форматы:

  • P1Y2M10D (годы, месяцы, дни)
  • PT5H20M10S (время)
  • комбинированные строки

Особенности:

  • строго соответствует стандарту ISO 8601
  • используется при обмене данными между системами
  • поддерживает дробные значения

Преобразование Duration в другие формы

toObject()

Преобразует Duration в обычный объект JavaScript.

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

Особенности:

  • возвращает только активные единицы
  • удобно для сериализации и логирования
  • сохраняет структуру исходных данных

toMillis()

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

const dur = luxon.Duration.fromObject({ seconds: 90 });
dur.toMillis();
// 90000

Особенности:

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

valueOf()

Возвращает числовое представление Duration.

const dur = luxon.Duration.fromObject({ seconds: 10 });
+dur; // 10000

Особенности:

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

Форматирование Duration

toISO()

Преобразует Duration в строку ISO 8601.

const dur = luxon.Duration.fromObject({ hours: 2, minutes: 30 });
dur.toISO();
// "PT2H30M"

Особенности:

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

toISOTime()

Преобразует Duration в формат времени.

const dur = luxon.Duration.fromObject({
  hours: 1,
  minutes: 45,
  seconds: 30
});
dur.toISOTime();
// "01:45:30"

Особенности:

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

toHuman()

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

const dur = luxon.Duration.fromObject({
  hours: 3,
  minutes: 5
});
dur.toHuman();
// "3 hours, 5 minutes"

Особенности:

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

Арифметика длительностей

plus()

Складывает две длительности.

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

a.plus(b).toObject();
// { hours: 1, minutes: 30 }

Особенности:

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

minus()

Вычитает одну длительность из другой.

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

a.minus(b).toObject();

Особенности:

  • поддерживает отрицательные значения
  • возвращает новый объект Duration
  • корректно обрабатывает переходы единиц

Манипуляции с единицами измерения

shiftTo()

Переводит Duration в указанные единицы.

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

dur.shiftTo("hours").toObject();
// { hours: 1 }

Особенности:

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

normalize()

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

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

dur.normalize().toObject();
// { hours: 2 }

Особенности:

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

Работа с отдельными единицами

get()

Возвращает значение конкретной единицы.

const dur = luxon.Duration.fromObject({
  hours: 5,
  minutes: 20
});

dur.get("hours"); // 5

Особенности:

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

set()

Изменяет значения единиц.

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

const upd ated = dur.se t({ minutes: 45 });

Особенности:

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

Проверка состояния Duration

isValid

Проверяет корректность объекта Duration.

const dur = luxon.Duration.invalid("error");
dur.isValid; // false

Особенности:

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

invalidExplanation

Возвращает описание ошибки.

dur.invalidExplanation;

Особенности:

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

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

as()

Возвращает длительность в заданной единице.

const dur = luxon.Duration.fromObject({ hours: 2 });
dur.as("minutes"); // 120

Особенности:

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

Внутренние особенности поведения Duration

Duration в Luxon строится как неизменяемая структура. Любая операция — будь то сложение, изменение единиц или преобразование формата — возвращает новый объект.

Ключевые принципы:

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

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

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

toFormat()

Форматирует Duration по пользовательскому шаблону.

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

dur.toFormat("hh:mm");
// "02:05"

Особенности:

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

Поведение при смешанных единицах

При работе с разными единицами (например, дни и минуты одновременно) Duration не приводит значения автоматически до вызова соответствующих методов. Это позволяет сохранить семантику исходных данных.

const dur = luxon.Duration.fromObject({
  days: 1,
  minutes: 90
});

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

  • normalize()
  • toMillis()
  • арифметических операций

Такой подход предотвращает неожиданное изменение структуры данных.

Оглавление