Поддерживаемые единицы

Библиотека Day.js оперирует строго фиксированным набором строковых идентификаторов, которые определяют единицы измерения времени. Эти единицы используются в методах add, subtract, diff, startOf, endOf и других API, связанных с преобразованием дат.

Ключевая особенность системы единиц — строгость написания: строки чувствительны к регистру и не допускают вариативных форм.

Основные календарные единицы:

  • year — год
  • month — месяц
  • week — неделя
  • day — день

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

Пример:

dayjs().add(1, 'year');
dayjs().subtract(2, 'month');
dayjs().diff(otherDate, 'day');

Часовые и поддневные единицы

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

  • hour — час
  • minute — минута
  • second — секунда
  • millisecond — миллисекунда

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

Пример использования:

dayjs().add(3, 'hour');
dayjs().subtract(15, 'minute');
dayjs().diff(otherDate, 'second');

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

  • 1 hour = 60 minutes
  • 1 minute = 60 seconds
  • 1 second = 1000 milliseconds

Неделя как календарная единица

Единица week относится к календарным интервалам и зависит от конфигурации локали. Неделя может начинаться с понедельника или воскресенья в зависимости от локализации.

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

При этом неделя не всегда равна строго 7 * 24 часа в вычислительном смысле, так как привязана к календарным границам.

Месяцы и годы как неравномерные единицы

Единицы month и year являются календарными и не имеют фиксированной длительности в миллисекундах.

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

  • месяц может содержать 28, 29, 30 или 31 день
  • год может быть високосным (366 дней)

Пример:

dayjs('2024-01-31').add(1, 'month'); // поведение зависит от нормализации даты

Day.js автоматически корректирует переполнение дат, «сдвигая» результат к последнему допустимому дню месяца при необходимости.

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

Единица quarter представляет собой квартал года (3 месяца).

Используется для финансовых и аналитических расчётов:

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

Кварталы:

  • Q1: январь — март
  • Q2: апрель — июнь
  • Q3: июль — сентябрь
  • Q4: октябрь — декабрь

Использование единиц в основных операциях

add / subtract

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

dayjs().add(10, 'day');
dayjs().subtract(5, 'minute');

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

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

diff

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

dayjs(dateA).diff(dateB, 'hour');

Результат зависит от выбранной единицы:

  • при millisecond возвращается точное значение
  • при day или month результат округляется

startOf / endOf

Методы обрезки даты до начала или конца интервала:

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

Поддерживаемые единицы определяют уровень точности:

  • year → начало/конец года
  • month → начало/конец месяца
  • week → начало/конец недели
  • day → границы суток
  • hour, minute, second, millisecond → соответствующие уровни времени

Нормализация строковых единиц

Day.js принимает только строго определённые строки. Недопустимые варианты:

  • days ❌
  • Day ❌
  • DAY ❌
  • mins ❌

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

  • day
  • minute
  • month

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

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

Календарные единицы (year, month, week) не преобразуются напрямую в фиксированное количество миллисекунд. Это приводит к важным последствиям:

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

Пример:

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

Результат зависит от внутренней логики нормализации, а не от простого прибавления 30 дней.

Особенности работы с временными единицами

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

dayjs().add(3600, 'second');

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

Согласованность единиц в API

Все основные методы Day.js используют единый набор идентификаторов:

  • add(value, unit)
  • subtract(value, unit)
  • diff(date, unit)
  • startOf(unit)
  • endOf(unit)

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

Взаимодействие единиц и округление

При использовании diff и некоторых операций нормализации происходит округление:

  • floor для календарных единиц
  • точное значение для миллисекунд

Пример:

dayjs('2024-01-01').diff('2023-01-01', 'month');

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

Итоговые группы единиц в системе Day.js

Все поддерживаемые единицы можно условно разделить на три категории:

Календарные:

  • year
  • month
  • week
  • quarter

Суточные:

  • day

Точные временные:

  • hour
  • minute
  • second
  • millisecond

Каждая группа определяет способ интерпретации операций и влияет на результат вычислений внутри API библиотеки.

Оглавление