Создание Duration

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

Внутренне Duration хранит набор полей (например, hours, minutes, seconds, milliseconds) и обеспечивает их нормализацию, преобразование и сериализацию. Создание экземпляра может происходить через несколько специализированных фабричных методов, каждый из которых ориентирован на определённый тип входных данных.

Создание из миллисекунд

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

Метод:

  • Duration.fromMillis(ms)

Миллисекунды представляют собой наиболее атомарную единицу времени в JavaScript-экосистеме, поэтому данный способ часто используется при работе с таймерами, измерениями производительности и низкоуровневыми временными расчётами.

Пример логики:

Duration.fromMillis(1500)

Внутри происходит разложение значения:

  • 1500 мс → 1 секунда и 500 миллисекунд
  • нормализация выполняется автоматически при форматировании

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

Создание из объекта единиц времени

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

Метод:

  • Duration.fromObject(obj)

Объект может содержать следующие поля:

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

Пример логики:

Duration.fromObject({
  hours: 2,
  minutes: 30
})

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

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

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

Пример неканонического входа:

Duration.fromObject({
  minutes: 90
})

После нормализации:

  • 1 час 30 минут

Парсинг из ISO-формата

ISO 8601 определяет стандарт представления длительностей, например PT2H30M.

Метод:

  • Duration.fromISO(isoString)

Формат начинается с P, затем следует временная часть T:

  • P — период
  • T — разделитель даты и времени
  • H, M, S — единицы времени

Примеры:

Duration.fromISO("PT2H30M")
Duration.fromISO("PT45S")
Duration.fromISO("P1DT2H")

Поддерживаются составные конструкции, включая дни и более крупные единицы периода.

Внутренний парсинг включает:

  • разбор строки по спецификации ISO 8601
  • преобразование в объект единиц
  • нормализацию значений

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

Создание из строк времени (ISO time)

Отдельный способ связан с интерпретацией времени как длительности без привязки к дате.

Метод:

  • Duration.fromISOTime(timeString)

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

  • HH:mm
  • HH:mm:ss
  • HH:mm:ss.SSS

Примеры:

Duration.fromISOTime("02:30")
Duration.fromISOTime("01:15:20")

Особенности интерпретации:

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

Пример расширенного значения:

Duration.fromISOTime("36:10:00")

Это соответствует 36 часам и 10 минутам.

Создание из разности дат

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

Метод:

  • DateTime.diff(otherDateTime)

Результатом является Duration.

Пример логики:

end.diff(start)

Особенности результата:

  • возвращается точная разница между моментами времени
  • единицы можно задать явно:
end.diff(start, "hours")

или комбинированно:

end.diff(start, ["hours", "minutes", "seconds"])

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

Нормализация и внутреннее представление

Любая созданная длительность проходит стадию нормализации, в ходе которой:

  • меньшие единицы преобразуются в большие при необходимости
  • устраняются переполнения (например, 90 минут → 1 час 30 минут)
  • поддерживается согласованная структура

Поведение нормализации зависит от контекста операций и параметров форматирования.

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

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

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

Типичный поток данных:

  • ISO-строка → объект единиц → Duration
  • миллисекунды → разложение → объект
  • разница дат → нормализованный Duration

Пример концептуальной цепочки:

Duration.fromMillis(90000)
// 90 000 мс → 1 минута 30 секунд

или:

Duration.fromISO("PT1H30M")

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

Практические паттерны создания длительности

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

При работе с API и сериализацией чаще используется ISO:

Duration.fromISO(apiResponse.duration)

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

Duration.fromObject({
  hours: userHours,
  minutes: userMinutes
})

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

Duration.fromMillis(performance.now() - startTime)

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

end.diff(start, ["days", "hours", "minutes"])

Каждый способ соответствует определённому уровню абстракции:

  • низкий уровень — миллисекунды
  • структурный уровень — объект единиц
  • стандартизированный уровень — ISO
  • вычислительный уровень — diff между датами
Оглавление