differenceInWeeks и другие функции

Библиотека date-fns предоставляет набор чистых функций для работы с датами без мутаций объектов Date, что делает её предсказуемой и удобной для функционального стиля программирования. Одним из наиболее часто используемых блоков функций являются операции сравнения и вычисления разницы между датами, где ключевую роль играет семейство differenceIn*, включая differenceInWeeks.

Функция differenceInWeeks возвращает количество полных календарных недель между двумя датами.

Базовая сигнатура

differenceInWeeks(dateLeft, dateRight, [options])
  • dateLeft — конечная дата
  • dateRight — начальная дата
  • options — дополнительные настройки (например, округление)

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

Разница вычисляется по календарным неделям, а не по фиксированным 7×24 часам в строгом смысле. Это означает, что результат зависит от границ недель и локали (если используется опция weekStartsOn).

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

import { differenceInWeeks } from 'date-fns';

const result = differenceInWeeks(
  new Date(2026, 0, 1),
  new Date(2025, 11, 1)
);

console.log(result); // 4

Особенности поведения

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

differenceInDays: разница в днях

Функция differenceInDays вычисляет количество полных календарных дней между датами.

import { differenceInDays } from 'date-fns';

differenceInDays(
  new Date(2026, 0, 10),
  new Date(2026, 0, 1)
); // 9

Особенности

  • игнорирует время суток
  • работает в рамках календарных суток
  • не зависит от часовых поясов на уровне логики вычисления (используется локальное время объекта Date)

differenceInMonths: разница в месяцах

Функция differenceInMonths возвращает количество полных календарных месяцев между датами.

import { differenceInMonths } from 'date-fns';

differenceInMonths(
  new Date(2026, 6, 1),
  new Date(2026, 0, 1)
); // 6

Поведение на границах месяцев

Если день месяца не совпадает, остаток не учитывается:

differenceInMonths(
  new Date(2026, 1, 28),
  new Date(2026, 0, 31)
); // 0

differenceInYears: разница в годах

Функция differenceInYears аналогична месячной логике, но на уровне лет.

import { differenceInYears } from 'date-fns';

differenceInYears(
  new Date(2030, 0, 1),
  new Date(2026, 0, 1)
); // 4

Характеристика

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

differenceInHours, differenceInMinutes, differenceInSeconds

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

differenceInHours

import { differenceInHours } from 'date-fns';

differenceInHours(
  new Date(2026, 0, 1, 12),
  new Date(2026, 0, 1, 0)
); // 12

differenceInMinutes

import { differenceInMinutes } from 'date-fns';

differenceInMinutes(
  new Date(2026, 0, 1, 0, 30),
  new Date(2026, 0, 1, 0, 0)
); // 30

differenceInSeconds

import { differenceInSeconds } from 'date-fns';

differenceInSeconds(
  new Date(2026, 0, 1, 0, 0, 10),
  new Date(2026, 0, 1, 0, 0, 0)
); // 10

differenceInMilliseconds: точная разница

Наиболее низкоуровневая функция из серии.

import { differenceInMilliseconds } from 'date-fns';

differenceInMilliseconds(
  new Date(2026, 0, 1, 0, 0, 0, 500),
  new Date(2026, 0, 1, 0, 0, 0, 0)
); // 500

Используется при измерении производительности, таймингов, задержек.

differenceInCalendarWeeks: календарные недели

Отличается от differenceInWeeks более строгим календарным подходом.

import { differenceInCalendarWeeks } from 'date-fns';

differenceInCalendarWeeks(
  new Date(2026, 0, 15),
  new Date(2026, 0, 1)
);

Отличие от differenceInWeeks

  • differenceInWeeks может учитывать правила округления и начало недели
  • differenceInCalendarWeeks ориентируется на календарные переходы недель

differenceInQuarters: разница по кварталам

import { differenceInQuarters } from 'date-fns';

differenceInQuarters(
  new Date(2026, 9, 1),
  new Date(2026, 0, 1)
); // 3

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

Применяется в финансовых и аналитических системах, где отчётность ведётся по кварталам.

Сравнительная модель поведения difference-функций

Календарные единицы

К ним относятся:

  • differenceInWeeks
  • differenceInMonths
  • differenceInYears
  • differenceInQuarters
  • differenceInCalendarWeeks

Характеристика:

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

Абсолютные временные единицы

  • differenceInHours
  • differenceInMinutes
  • differenceInSeconds
  • differenceInMilliseconds

Характеристика:

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

Поведение при отрицательных значениях

Все функции семейства differenceIn* возвращают отрицательные значения, если dateLeft раньше dateRight.

differenceInDays(
  new Date(2026, 0, 1),
  new Date(2026, 0, 10)
); // -9

Работа с временными зонами

Несмотря на то что объекты Date в JavaScript хранят время в UTC, вычисления в date-fns выполняются на основе локального представления даты.

Это приводит к важным последствиям:

  • возможны различия при смене часового пояса
  • календарные функции ориентируются на локальные даты
  • абсолютные функции (milliseconds, seconds) менее подвержены влиянию

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

Пример вычисления длительности события

import {
  differenceInDays,
  differenceInHours,
  differenceInMinutes
} from 'date-fns';

const start = new Date(2026, 0, 1, 10, 0);
const end = new Date(2026, 0, 3, 12, 30);

differenceInDays(end, start);    // 2
differenceInHours(end, start);   // 50
differenceInMinutes(end, start); // 3030

Типовые сценарии применения

Аналитика и отчётность

  • differenceInMonths
  • differenceInQuarters
  • differenceInYears

Интерфейсы и UX

  • differenceInDays
  • differenceInWeeks

Таймеры и измерение времени

  • differenceInSeconds
  • differenceInMilliseconds

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

  • differenceInCalendarWeeks
  • differenceInDays

Особенности округления

Во всех differenceIn* функциях применяется усечение (truncation), а не математическое округление.

Пример:

differenceInHours(
  new Date(2026, 0, 1, 1, 59),
  new Date(2026, 0, 1, 0, 0)
); // 1

Даже при 1 часе 59 минутах результат равен 1 часу.

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

Функции differenceIn* часто комбинируются с:

  • addDays, addWeeks, addMonths
  • startOfDay, startOfWeek
  • isBefore, isAfter
  • format

Пример связки:

import { differenceInDays, startOfDay } from 'date-fns';

differenceInDays(
  startOfDay(new Date(2026, 0, 10)),
  startOfDay(new Date(2026, 0, 1))
);

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

Функции построены на следующих принципах:

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

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

Оглавление