Указание единиц измерения

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

Day.js поддерживает стандартный набор единиц, применяемых в большинстве API:

  • millisecond — миллисекунда (ms)
  • second — секунда (s)
  • minute — минута (m)
  • hour — час (h)
  • day — день (d)
  • week — неделя (w)
  • month — месяц (M)
  • quarter — квартал (Q)
  • year — год (y)

Единицы передаются в виде строковых литералов и чувствительны к точному написанию. Использование сокращений допустимо в ограниченном числе случаев (например, h, m, s), однако полные формы обеспечивают более предсказуемое поведение при чтении и поддержке кода.

Строковое представление единиц и правила интерпретации

Внутренний парсер Day.js приводит входные значения к заранее определённому набору идентификаторов. Любые отклонения от стандарта игнорируются или приводят к некорректным вычислениям.

Примеры корректных значений:

dayjs().add(1, 'day')
dayjs().add(2, 'month')
dayjs().add(15, 'minute')

Некорректные формы:

dayjs().add(1, 'days')      // не гарантируется поддержка множественного числа
dayjs().add(1, 'Day')       // регистр имеет значение
dayjs().add(1, 'minutes ')  // пробелы ломают интерпретацию

Единицы должны использоваться в строго нормализованной форме, поскольку Day.js не выполняет семантическое исправление входных строк.

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

Добавление времени

Метод add изменяет дату, увеличивая её на заданный интервал:

dayjs('2024-01-01').add(10, 'day')
dayjs('2024-01-01').add(3, 'month')
dayjs('2024-01-01').add(1, 'year')

Поведение зависит от типа единицы:

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

Вычитание времени

Метод subtract является симметричным add и использует те же единицы:

dayjs('2024-01-10').subtract(5, 'day')
dayjs('2024-06-01').subtract(2, 'month')

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

Особенности календарных единиц

Месяцы

Месяцы не имеют фиксированной длины. При операциях:

dayjs('2024-01-31').add(1, 'month')

результат зависит от контекста календаря. Если целевая дата не существует (например, 31 февраля), Day.js нормализует её до последнего дня месяца.

Годы

Годовая арифметика аналогична месячной, но с более выраженным влиянием високосных лет:

dayjs('2020-02-29').add(1, 'year')

Результат корректируется в соответствии с отсутствием 29 февраля в невисокосных годах.

Вычисление разницы между датами

Метод diff использует единицы измерения для определения точности результата:

dayjs('2024-01-10').diff('2024-01-01', 'day')
dayjs('2024-01-10').diff('2024-01-01', 'hour')
dayjs('2024-01-10').diff('2024-01-01', 'month')

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

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

Начало и конец интервалов

Методы startOf и endOf используют те же единицы для нормализации даты:

dayjs().startOf('day')
dayjs().endOf('month')
dayjs().startOf('year')

Поведение по единицам:

  • day — сброс времени до 00:00:00.000;
  • month — переход к первому дню месяца;
  • year — переход к 1 января;
  • hour, minute, second — последовательная обрезка точности.

Дополнительные единицы и расширения

Quarter (квартал)

Квартал используется для бизнес-логики:

dayjs().add(1, 'quarter')

Квартал интерпретируется как 3 месяца, но при вычислениях учитывается календарная структура года.

Неделя

Неделя зависит от локали и настроек начала недели:

dayjs().add(1, 'week')
dayjs().startOf('week')

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

Плагин duration и единицы измерения

Плагин duration расширяет модель времени, вводя абстракцию длительности:

dayjs.duration(5000, 'millisecond')
dayjs.duration(2, 'hour')
dayjs.duration(1, 'day')

Единицы в duration совпадают с базовыми, но интерпретация отличается:

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

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

const d = dayjs.duration(90, 'minute')
d.asHours() // 1.5

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

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

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

Корректная стратегия работы заключается в централизованном хранении единиц:

const TIME_UNITS = {
  DAY: 'day',
  MONTH: 'month',
  YEAR: 'year',
  HOUR: 'hour',
  MINUTE: 'minute',
  SECOND: 'second'
}

Поведение при некорректных единицах

При передаче неизвестной строки:

dayjs().add(1, 'dayss')

поведение становится непредсказуемым: значение может быть проигнорировано или интерпретировано как миллисекунды в зависимости от контекста внутреннего парсера. Это приводит к необходимости строгой валидации входных данных до вызова API Day.js.

Контекстная чувствительность единиц

Некоторые операции интерпретируют единицы по-разному:

  • add/subtract — абсолютное смещение даты;
  • diff — измерение расстояния между моментами времени;
  • startOf/endOf — приведение к границе временного интервала;
  • duration — независимая модель времени.

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

Оглавление