Методы add и subtract

В Day.js операции изменения даты строятся вокруг принципа неизменяемости (immutable): каждый вызов методов, модифицирующих дату, возвращает новый объект, не изменяя исходный экземпляр.

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

import dayjs from 'dayjs';

const base = dayjs('2026-01-01');

const result = base.add(5, 'day');

console.log(base.format());   // 2026-01-01T00:00:00+00:00
console.log(result.format()); // 2026-01-06T00:00:00+00:00

Метод add

Метод add используется для прибавления временного интервала к дате. Сигнатура метода:

dayjs().add(value, unit)
  • value — числовое значение (может быть отрицательным)
  • unit — единица измерения времени

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

Day.js поддерживает следующие основные единицы:

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

Базовое использование add

dayjs('2026-01-01').add(1, 'day');      // +1 день
dayjs('2026-01-01').add(2, 'week');     // +2 недели
dayjs('2026-01-01').add(3, 'month');    // +3 месяца
dayjs('2026-01-01').add(1, 'year');     // +1 год

Цепочка вызовов

Метод add можно комбинировать последовательно:

dayjs('2026-01-01')
  .add(1, 'month')
  .add(10, 'day')
  .add(2, 'hour')
  .format();

Каждый вызов работает с результатом предыдущего.

Отрицательные значения в add

add допускает отрицательные значения, фактически превращаясь в вычитание:

dayjs('2026-01-10').add(-5, 'day');

Однако в практическом коде предпочтительнее использовать subtract, так как он повышает читаемость.

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

Месяцы имеют переменную длину, поэтому добавление месяцев может приводить к «переполнению» даты.

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

Результат зависит от логики нормализации:

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

Пример:

dayjs('2026-01-31').add(1, 'month'); // 2026-02-28

Работа с неделями

Неделя в Day.js эквивалентна 7 дням:

dayjs('2026-01-01').add(1, 'week'); // +7 дней

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

Метод subtract

Метод subtract выполняет обратную операцию — вычитание временного интервала.

Сигнатура идентична add:

dayjs().subtract(value, unit)

Базовое использование subtract

dayjs('2026-01-10').subtract(1, 'day');
dayjs('2026-01-10').subtract(2, 'week');
dayjs('2026-01-10').subtract(3, 'month');
dayjs('2026-01-10').subtract(1, 'year');

Примеры цепочек subtract

dayjs('2026-12-31')
  .subtract(1, 'year')
  .subtract(2, 'month')
  .subtract(10, 'day')
  .format();

Эквивалентность add с отрицательным значением

Следующие выражения идентичны по результату:

dayjs('2026-01-10').subtract(5, 'day');
dayjs('2026-01-10').add(-5, 'day');

Но семантически различаются:

  • subtract — выражает намерение вычитания
  • add(-n) — математическое преобразование

Единицы времени и точность вычислений

При работе с add и subtract важно учитывать уровень точности:

  • миллисекунды — максимальная точность
  • секунды и минуты — стандартные интервалы
  • часы и дни — календарные смещения
  • месяцы и годы — календарная логика (не фиксированное количество дней)
dayjs().add(1500, 'millisecond');
dayjs().subtract(90, 'minute');

Иммутабельность и предсказуемость

Каждое изменение возвращает новый объект:

const d1 = dayjs('2026-01-01');
const d2 = d1.add(10, 'day');
const d3 = d2.subtract(5, 'day');

d1, d2, d3 — независимые экземпляры.

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

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

Расчёт дедлайнов

const createdAt = dayjs();

const deadline = createdAt.add(14, 'day');

Окна времени

const start = dayjs();
const end = start.add(30, 'minute');

Откат состояния

const snapshot = dayjs();

const rollback = snapshot.subtract(3, 'day');

Нормализация дат в цепочках

const normalized = dayjs('2026-01-01')
  .add(1, 'month')
  .subtract(1, 'day')
  .add(2, 'hour');

Особенности поведения при переходах календаря

При переходах через:

  • конец месяца
  • високосные годы
  • смену лет

Day.js автоматически корректирует результат в рамках календарной логики.

dayjs('2024-02-29').add(1, 'year'); // 2025-02-28

Использование в вычисляемых выражениях

Методы add и subtract часто применяются в вычисляемых цепочках без промежуточных переменных:

const deliveryDate = dayjs()
  .add(2, 'day')
  .add(4, 'hour')
  .subtract(15, 'minute');

Такой подход характерен для построения временных окон, расписаний и TTL-логики.

Работа с динамическими значениями

Значение интервала может быть вычисляемым:

const delay = 3;

const result = dayjs().add(delay * 2, 'day');

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

Путаница единиц

dayjs().add(1, 'dates'); // ошибка: неверная единица

Корректно:

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

Ожидание фиксированного количества дней в месяце

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

Результат зависит от календаря, а не арифметики 30/31.

Игнорирование иммутабельности

const d = dayjs('2026-01-01');
d.add(5, 'day'); // результат потерян

Корректно:

const d2 = d.add(5, 'day');
Оглавление