Сокращения единиц

Работа с датами в Day.js основана на компактной системе обозначений временных единиц. Эти сокращения используются во множестве методов библиотеки: add, subtract, diff, startOf, endOf, а также в плагинах, расширяющих функциональность ядра. Понимание системы единиц является ключевым элементом корректной работы с временными интервалами и вычислениями.

Базовые единицы времени

В Day.js каждая временная единица представляется строковым сокращением. Эти сокращения унифицированы и применяются во всех API, где требуется указание интервала.

Основные сокращения

Полная единица Сокращение Описание
year y Год
month M Месяц
week w Неделя
day d День
hour h Час
minute m Минута
second s Секунда
millisecond ms Миллисекунда

Особенность системы заключается в том, что регистр символов имеет значение. Например, M (месяц) и m (минута) обозначают разные сущности.

Принцип использования сокращений

Сокращения единиц применяются как второй аргумент в методах изменения даты.

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

import dayjs from 'dayjs';

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

Каждое значение интерпретируется строго по переданному сокращению. При этом Day.js не выполняет автоматическую нормализацию смыслов: единица всегда соответствует указанному типу.

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

dayjs().subtract(1, 'year');
dayjs().subtract(30, 'second');
dayjs().subtract(5, 'week');

Метод subtract использует тот же набор сокращений, что и add, что обеспечивает симметрию API.

Сравнение дат через единицы

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

const a = dayjs('2025-01-01');
const b = dayjs('2026-01-01');

b.diff(a, 'year');   // 1
b.diff(a, 'month');  // 12
b.diff(a, 'day');    // 365 (или 366 в високосный год)

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

  • крупные единицы (y, M) могут включать усечения
  • мелкие единицы (d, h, ms) дают более точный результат

Округление границ времени

Методы startOf и endOf используют те же сокращения для установки временной границы.

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

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

  • year → начало/конец года
  • month → первый/последний день месяца
  • day → 00:00:00.000 или 23:59:59.999
  • hour → начало/конец часа

Особенности отдельных единиц

Месяцы (M) и минуты (m)

Наиболее частая ошибка связана с конфликтом регистров:

  • M — месяц
  • m — минута
dayjs().add(1, 'M'); // +1 месяц
dayjs().add(1, 'm'); // +1 минута

Эта разница критична при динамическом формировании параметров.

Недели (w)

Неделя является производной единицей и зависит от локали и настроек начала недели.

dayjs().add(2, 'w');
dayjs().startOf('w');

Неделя не всегда строго равна 7 дням в контексте календарных вычислений, особенно при работе с границами месяцев и лет.

Миллисекунды (ms)

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

dayjs().add(500, 'ms');
dayjs().diff(otherDate, 'ms');

Используются преимущественно в высокоточных измерениях и таймерах.

Сводная система единиц в API

Сокращения единиц используются не только в арифметических операциях, но и во всей экосистеме Day.js:

1. Арифметика дат

  • add(value, unit)
  • subtract(value, unit)

2. Разница между датами

  • diff(date, unit)

3. Округление времени

  • startOf(unit)
  • endOf(unit)

4. Плагины (например, advanced format, duration)

Дополнительные плагины также используют единицы:

dayjs.duration(2, 'hour');
dayjs.duration(90, 'minute');

Внутренняя логика интерпретации единиц

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

  • тип календарной операции (календарная или абсолютная)
  • способ округления
  • влияние на локаль и часовой пояс

Календарные единицы (year, month) зависят от структуры календаря, тогда как абсолютные (ms, s, m, h) опираются на фиксированные интервалы времени.

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

Нормализация времени до начала периода

const startOfWeek = dayjs().startOf('week');
const startOfMonth = dayjs().startOf('month');

Построение временных окон

const now = dayjs();

const windowStart = now.subtract(15, 'minute');
const windowEnd = now.add(15, 'minute');

Расчёт TTL (time-to-live)

const expiresAt = dayjs().add(30, 'day');

Взаимодействие единиц между собой

Комбинирование единиц требует понимания иерархии времени:

  • year > month > week > day > hour > minute > second > millisecond

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

dayjs().add(1, 'month').diff(dayjs(), 'day');

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

Ограничения и неоднозначности

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

  • week может варьироваться в зависимости от локали
  • month имеет переменную длину (28–31 день)
  • year зависит от високосных правил

Абсолютные единицы (ms, s, m, h) не имеют подобных неоднозначностей и используются для точных вычислений.

Совместимость единиц в цепочках вызовов

Сокращения единиц сохраняют консистентность при цепочечных вызовах:

dayjs()
  .add(2, 'day')
  .subtract(3, 'hour')
  .add(15, 'minute')
  .startOf('day');

Каждый шаг независимо интерпретирует единицу, не влияя на предыдущие операции.

Типовые ошибки при использовании сокращений

1. Перепутанный регистр

dayjs().add(1, 'm'); // минута, а не месяц

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

dayjs().add('1', 'day'); // допустимо, но теряет строгость типизации

3. Неверная интерпретация недель

dayjs().add(1, 'w'); // зависит от календарной локали

Семантическая модель единиц

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

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

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

Оглавление