Добавление времени: add и addDays, addMonths, addYears

Библиотека date-fns предоставляет набор функций для безопасной и удобной работы с датами. Одной из наиболее востребованных задач является добавление временных интервалов: дней, месяцев, лет, часов и других единиц времени.

Для этого используются как универсальная функция add, так и специализированные функции:

  • addDays
  • addMonths
  • addYears
  • addHours
  • addMinutes
  • addSeconds

Установка библиотеки

Через npm:

npm install date-fns

Импорт отдельных функций:

import { add, addDays, addMonths, addYears } from 'date-fns'

Главная особенность библиотеки — модульность. Импортируются только используемые функции, благодаря чему уменьшается размер итогового бандла.

Функция add

Общий синтаксис

add(date, duration)

Параметры

Параметр Описание
date Исходная дата
duration Объект с единицами времени

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

Объект duration может содержать:

{
  years,
  months,
  weeks,
  days,
  hours,
  minutes,
  seconds
}

Добавление нескольких единиц времени одновременно

import { add } from 'date-fns'

const date = new Date(2025, 0, 10)

const result = add(date, {
  years: 1,
  months: 2,
  days: 5
})

console.log(result)

Результат:

2026-03-15T00:00:00.000Z

Особенности работы add

Исходная дата не изменяется

Функции в date-fns являются immutable — они не мутируют оригинальный объект Date.

const original = new Date(2025, 0, 1)

const updated = addDays(original, 10)

console.log(original)
console.log(updated)

Это особенно важно при работе с состоянием в React, Redux и других системах управления данными.

Добавление дней: addDays

Синтаксис

addDays(date, amount)

Пример

import { addDays } from 'date-fns'

const date = new Date(2025, 4, 1)

const result = addDays(date, 7)

console.log(result)

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

Отрицательное число вычитает дни.

const result = addDays(new Date(2025, 4, 10), -3)

Результат:

2025-05-07

Работа с переходом между месяцами

const result = addDays(
  new Date(2025, 0, 30),
  5
)

Результат автоматически перейдёт в следующий месяц:

2025-02-04

Добавление месяцев: addMonths

Синтаксис

addMonths(date, amount)

Базовый пример

import { addMonths } from 'date-fns'

const date = new Date(2025, 0, 15)

const result = addMonths(date, 3)

console.log(result)

Проблема конца месяца

Добавление месяцев — одна из самых сложных операций при работе с датами.

Например:

const result = addMonths(
  new Date(2025, 0, 31),
  1
)

console.log(result)

Февраль не содержит 31 числа, поэтому результат будет скорректирован:

2025-02-28

В високосный год:

2024-02-29

Как работает корректировка

Алгоритм:

  1. Берётся исходный день месяца
  2. Добавляется нужное количество месяцев
  3. Если такого дня в целевом месяце нет — используется последний день месяца

Это защищает от появления невалидных дат.

Добавление нескольких месяцев

const result = addMonths(
  new Date(2025, 5, 10),
  18
)

Результат:

2026-12-10

Функция автоматически корректно переносит год.

Добавление лет: addYears

Синтаксис

addYears(date, amount)

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

import { addYears } from 'date-fns'

const date = new Date(2025, 0, 1)

const result = addYears(date, 5)

console.log(result)

Работа с високосными годами

Особое внимание необходимо уделять 29 февраля.

const result = addYears(
  new Date(2024, 1, 29),
  1
)

console.log(result)

2025 год не является високосным, поэтому дата будет скорректирована:

2025-02-28

Универсальный add против специализированных функций

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

add(date, {
  days: 10
})

Использование addDays

addDays(date, 10)

Когда использовать add

add подходит в ситуациях:

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

Пример:

const duration = {
  days: 3,
  months: 2,
  years: 1
}

const result = add(date, duration)

Когда использовать специализированные функции

addDays, addMonths, addYears удобнее:

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

Пример:

const expirationDate = addDays(now, 30)

Такой код читается проще, чем:

const expirationDate = add(now, {
  days: 30
})

Добавление времени меньшей точности

addHours

import { addHours } from 'date-fns'

const result = addHours(new Date(), 5)

addMinutes

import { addMinutes } from 'date-fns'

const result = addMinutes(new Date(), 30)

addSeconds

import { addSeconds } from 'date-fns'

const result = addSeconds(new Date(), 45)

Комбинирование функций

Функции можно комбинировать.

const result = addDays(
  addMonths(new Date(), 2),
  10
)

Однако более читаемым вариантом часто становится использование add:

const result = add(new Date(), {
  months: 2,
  days: 10
})

Практические сценарии

Срок действия токена

const expiresAt = addHours(new Date(), 2)

Дата окончания подписки

const subscriptionEnd = addMonths(new Date(), 1)

Дедлайн задачи

const deadline = addDays(new Date(), 14)

Планирование события через год

const nextConference = addYears(new Date(), 1)

Работа с timestamp

Функции принимают не только объект Date, но и timestamp.

const result = addDays(Date.now(), 5)

Преобразование строк

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

import { parseISO, addDays } from 'date-fns'

const date = parseISO('2025-05-10')

const result = addDays(date, 7)

Ошибки при работе с датами

Invalid Date

Если передать невалидную дату:

addDays(new Date('invalid'), 5)

Результат:

Invalid Date

Проверка валидности

Для проверки используется isValid.

import { isValid } from 'date-fns'

const date = new Date('invalid')

console.log(isValid(date))

Влияние часовых поясов

Функции работают с локальным часовым поясом JavaScript runtime.

const result = addDays(new Date(), 1)

Результат зависит от timezone среды выполнения:

  • браузера;
  • Node.js;
  • сервера.

Для сложной timezone-логики обычно используется дополнительно библиотека date-fns-tz.

Производительность

Функции date-fns:

  • не изменяют исходные объекты;
  • работают быстрее многих крупных date-библиотек;
  • импортируются по отдельности;
  • хорошо подходят для tree-shaking.

Сравнение с нативным Date

Нативный подход

const date = new Date()

date.setDate(date.getDate() + 5)

Недостатки:

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

Подход через date-fns

const result = addDays(new Date(), 5)

Преимущества:

  • декларативность;
  • предсказуемость;
  • immutable-подход;
  • единый API.

Типизация в TypeScript

Функции полностью поддерживают TypeScript.

import { addDays } from 'date-fns'

const result: Date = addDays(new Date(), 10)

Важные особенности addMonths

Сохранение конца месяца

addMonths(new Date(2025, 0, 31), 1)

Результат:

2025-02-28

Но:

addMonths(new Date(2025, 2, 31), 1)

Результат:

2025-04-30

Это поведение необходимо учитывать при:

  • финансовых расчётах;
  • подписках;
  • биллинге;
  • календарных системах.

Использование в бизнес-логике

Продление лицензии

function extendLicense(date) {
  return addYears(date, 1)
}

Расчёт пробного периода

function getTrialEnd() {
  return addDays(new Date(), 14)
}

Автоматическое планирование

function getNextPaymentDate(date) {
  return addMonths(date, 1)
}

Рекомендации по использованию

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

Для простых операций:

addDays(date, 5)

вместо:

add(date, {
  days: 5
})

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

add(date, {
  years: 1,
  months: 3,
  days: 10,
  hours: 5
})

Избегание ручной арифметики

Нежелательно:

date.setTime(
  date.getTime() + 86400000
)

Причины:

  • переходы летнего времени;
  • timezone;
  • плохая читаемость;
  • риск ошибок.

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

Функция Назначение
add Универсальное добавление
addDays Добавление дней
addMonths Добавление месяцев
addYears Добавление лет
addHours Добавление часов
addMinutes Добавление минут
addSeconds Добавление секунд
addWeeks Добавление недель
Оглавление