Разница в днях, часах, минутах

В библиотеке date-fns вычисление разницы между датами реализовано через набор специализированных функций, каждая из которых работает на определённой временной единице. Для анализа интервалов используются функции differenceInDays, differenceInHours, differenceInMinutes, а также более общая логика, основанная на вычислении абсолютной разницы между временными метками.

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

Базовый принцип вычисления разницы

Каждая функция принимает два аргумента:

differenceInX(dateLeft, dateRight)
  • dateLeft — конечная дата
  • dateRight — начальная дата

Результат вычисляется как:

dateLeft - dateRight → количество временных единиц

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

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

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

Сигнатура

import { differenceInDays } from 'date-fns';

differenceInDays(dateLeft, dateRight);

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

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

const result = differenceInDays(
  new Date('2024-01-10'),
  new Date('2024-01-01')
);

console.log(result); // 9

Особенности

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

Пример с временем внутри дня

differenceInDays(
  new Date('2024-01-02T23:59:00'),
  new Date('2024-01-01T00:01:00')
);

Результат:

1

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

Разница в часах: differenceInHours

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

Сигнатура

import { differenceInHours } from 'date-fns';

differenceInHours(dateLeft, dateRight);

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

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

const result = differenceInHours(
  new Date('2024-01-01T12:00:00'),
  new Date('2024-01-01T00:00:00')
);

console.log(result); // 12

Поведение при неполных часах

differenceInHours(
  new Date('2024-01-01T12:59:59'),
  new Date('2024-01-01T00:00:00')
);

Результат:

12

Одна минута до 13 часов не учитывается.

Особенности

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

Разница в минутах: differenceInMinutes

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

Сигнатура

import { differenceInMinutes } from 'date-fns';

differenceInMinutes(dateLeft, dateRight);

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

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

const result = differenceInMinutes(
  new Date('2024-01-01T00:10:00'),
  new Date('2024-01-01T00:00:00')
);

console.log(result); // 10

Отбрасывание секунд

differenceInMinutes(
  new Date('2024-01-01T00:10:59'),
  new Date('2024-01-01T00:00:00')
);

Результат:

10

Секунды полностью игнорируются при округлении вниз.

Особенности

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

Сравнение единиц измерения

Поведение функций можно систематизировать по уровню точности:

  • differenceInDays — календарные сутки
  • differenceInHours — 24-часовые блоки
  • differenceInMinutes — 60-минутные интервалы

Все функции основаны на одной концепции: преобразование разницы в миллисекундах в целевую единицу с последующим усечением результата.

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

Порядок аргументов напрямую влияет на знак результата:

differenceInHours(
  new Date('2024-01-02T00:00:00'),
  new Date('2024-01-01T00:00:00')
); // 24

Обратный порядок:

differenceInHours(
  new Date('2024-01-01T00:00:00'),
  new Date('2024-01-02T00:00:00')
); // -24

Это поведение сохраняется для всех функций разницы.

Работа с ISO-датами и парсинг

В практических сценариях часто используются ISO-строки:

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

differenceInDays(
  parseISO('2024-06-10'),
  parseISO('2024-06-01')
);

Использование parseISO обеспечивает корректное преобразование строки в объект Date, что снижает риск ошибок при работе с временными зонами и форматами.

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

Во всех функциях date-fns применяется усечение результата (truncation), а не математическое округление.

Пример:

differenceInHours(
  new Date('2024-01-01T01:59:59'),
  new Date('2024-01-01T00:00:00')
);

Результат:

1

Даже при значении почти в 2 часа возвращается 1.

Учет временных зон и переходов DST

При работе с датами в JavaScript важно учитывать поведение временных зон. date-fns опирается на встроенный объект Date, поэтому:

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

Пример ситуации DST:

  • день может содержать 23 или 25 часов
  • differenceInDays всё равно вернёт 1, если прошёл календарный день

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

Функции разницы применяются в задачах:

  • расчёт длительности сессий
  • логирование времени событий
  • построение аналитики активности
  • таймеры и обратные отсчёты
  • контроль SLA и сроков выполнения задач

Каждая единица измерения выбирается исходя из требуемой точности:

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