Добавление рабочих дней: addBusinessDays

Назначение функции

Функция addBusinessDays из библиотеки date-fns используется для прибавления к дате определённого количества рабочих дней. Под рабочими днями подразумеваются дни недели с понедельника по пятницу включительно, при этом суббота и воскресенье автоматически исключаются из расчёта.

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

Сигнатура функции

addBusinessDays(date, amount)

Параметры

date Исходная дата, от которой выполняется отсчёт. Может быть передана как объект Date, timestamp или строка, преобразуемая в дату.

amount Количество рабочих дней для добавления. Допустимы положительные и отрицательные значения:

  • положительное значение — движение вперёд по календарю
  • отрицательное значение — движение назад

Принцип работы

Функция выполняет итеративное прибавление дней к исходной дате, пропуская выходные:

  • Понедельник–пятница считаются рабочими днями
  • Суббота и воскресенье исключаются из счёта
  • Каждое увеличение на 1 рабочий день может соответствовать 1–3 календарным дням в зависимости от положения в неделе

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

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

import { addBusinessDays } from 'date-fns';

const result = addBusinessDays(new Date(2024, 0, 1), 5);
console.log(result);

Если начальная дата — понедельник, то добавление 5 рабочих дней приведёт к следующему понедельнику.

Пример перехода через выходные

import { addBusinessDays } from 'date-fns';

const date = new Date(2024, 0, 5); // пятница
const result = addBusinessDays(date, 1);

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

Поведение на границах недели

При добавлении нескольких рабочих дней функция корректно пересчитывает переходы через выходные:

import { addBusinessDays } from 'date-fns';

const date = new Date(2024, 0, 3); // среда
const result = addBusinessDays(date, 4);

Расчёт происходит так:

  • среда → четверг (1)
  • четверг → пятница (2)
  • пятница → понедельник (3, пропуск выходных)
  • понедельник → вторник (4)

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

Поддерживается обратный отсчёт рабочих дней:

import { addBusinessDays } from 'date-fns';

const date = new Date(2024, 0, 8); // понедельник
const result = addBusinessDays(date, -3);

Движение будет происходить назад с пропуском выходных.

Особенности вычислений

1. Игнорирование праздников

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

Для учёта праздников требуется дополнительная логика поверх функции.

2. Нормализация входных данных

Если передана строка или timestamp, происходит преобразование в дату:

addBusinessDays('2024-01-01', 2);
addBusinessDays(1704067200000, 2);

3. Неизменяемость исходной даты

Исходный объект Date не модифицируется. Возвращается новый экземпляр.

const date = new Date(2024, 0, 1);
const result = addBusinessDays(date, 3);

console.log(date);   // исходная дата остаётся неизменной
console.log(result); // новая дата

Типовые сценарии использования

Расчёт срока выполнения задачи

import { addBusinessDays } from 'date-fns';

const start = new Date(2024, 2, 1);
const deadline = addBusinessDays(start, 10);

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

import { addBusinessDays } from 'date-fns';

function getDeliveryDate(orderDate) {
  return addBusinessDays(orderDate, 3);
}

Финансовые расчёты

Используется для определения даты исполнения операций:

const settlementDate = addBusinessDays(tradeDate, 2);

Поведение при больших значениях

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

addBusinessDays(new Date(2024, 0, 1), 100);

Результат корректно учитывает многократные переходы через недели.

Сравнение с addDays

Функция addDays добавляет календарные дни без исключений.

addDays(date, 5); // 5 календарных дней
addBusinessDays(date, 5); // 5 рабочих дней

Разница особенно заметна при пересечении выходных: вторая функция автоматически компенсирует субботу и воскресенье.

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

1. Ожидание учёта праздников

addBusinessDays(new Date(2024, 0, 1), 1);

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

2. Использование для календарных интервалов

Функция не подходит для расчёта “через N календарных дней”, так как пропускает выходные.

3. Неверное понимание отрицательных значений

Отрицательное значение означает движение назад по рабочим дням, а не календарным.

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

Алгоритм работает за линейное время относительно количества дней, однако оптимизирован для типичных значений (1–30 рабочих дней). При больших интервалах влияние производительности минимально в реальных сценариях, так как расчёты остаются предсказуемыми и без внешних зависимостей.

Взаимодействие с другими функциями date-fns

Часто используется вместе с:

  • startOfDay — нормализация времени
  • format — вывод результата
  • differenceInBusinessDays — обратные расчёты
  • subBusinessDays — симметричное вычитание

Пример композиции:

import { addBusinessDays, format } from 'date-fns';

const date = addBusinessDays(new Date(), 7);
const formatted = format(date, 'yyyy-MM-dd');
Оглавление