isSameDay, isSameWeek, isSameMonth

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

Сигнатура

isSameDay(dateLeft, dateRight)

Параметры

  • dateLeft — первая дата (Date или значение, приводимое к Date)
  • dateRight — вторая дата (Date или значение, приводимое к Date)

Логика работы

Сравнение выполняется по локальному времени:

  • совпадает год
  • совпадает месяц
  • совпадает день месяца

Временная составляющая (часы, минуты, секунды, миллисекунды) игнорируется полностью.

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

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

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

Примеры

import { isSameDay } from 'date-fns';

const a = new Date(2026, 0, 10, 10, 0);
const b = new Date(2026, 0, 10, 23, 59);

isSameDay(a, b); // true
const a = new Date(2026, 0, 10, 23, 59);
const b = new Date(2026, 0, 11, 0, 1);

isSameDay(a, b); // false

isSameWeek

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

Сигнатура

isSameWeek(dateLeft, dateRight, options?)

Параметры

  • dateLeft — первая дата
  • dateRight — вторая дата
  • options — объект конфигурации

Опции

{
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
  locale?: Locale
}

  • weekStartsOn — определяет день начала недели

    • 0 — воскресенье
    • 1 — понедельник
    • и далее по индексу дня недели

  • locale — локаль, определяющая правила недели (например, европейские или американские стандарты)

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

Алгоритм вычисляет границы недели для каждой даты и проверяет, совпадают ли они:

  1. Определяется начало недели для dateLeft
  2. Определяется начало недели для dateRight
  3. Сравниваются вычисленные границы

Если обе даты попадают в один и тот же диапазон недели, результатом становится true.

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

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

  • при weekStartsOn: 0 неделя начинается в воскресенье
  • при weekStartsOn: 1 неделя начинается в понедельник

Это критично для аналитических систем, где неделя является единицей агрегации данных.

Также учитывается локаль, которая может переопределять стандартное начало недели.

Примеры

import { isSameWeek } from 'date-fns';

const a = new Date(2026, 4, 18);
const b = new Date(2026, 4, 20);

isSameWeek(a, b, { weekStartsOn: 1 }); // true
const a = new Date(2026, 4, 18);
const b = new Date(2026, 4, 25);

isSameWeek(a, b, { weekStartsOn: 1 }); // false

Пограничные случаи

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

isSameMonth

Функция isSameMonth определяет, принадлежат ли две даты одному календарному месяцу.

Сигнатура

isSameMonth(dateLeft, dateRight)

Параметры

  • dateLeft — первая дата
  • dateRight — вторая дата

Логика сравнения

Проверяются два компонента:

  • год
  • месяц

День месяца и время не учитываются.

Особенности

Сравнение происходит в локальном времени, что важно при работе с датами, полученными из разных источников (API, базы данных, пользовательский ввод).

Месяцы в JavaScript индексируются с нуля:

  • 0 — январь
  • 1 — февраль
  • …
  • 11 — декабрь

Это влияет на интерпретацию при ручном создании дат через new Date(year, monthIndex, day).

Примеры

import { isSameMonth } from 'date-fns';

const a = new Date(2026, 0, 1);
const b = new Date(2026, 0, 31);

isSameMonth(a, b); // true
const a = new Date(2026, 0, 31);
const b = new Date(2026, 1, 1);

isSameMonth(a, b); // false

Применение в календарной логике

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

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

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

Все три функции относятся к семейству сравнений календарных единиц времени, но оперируют разными уровнями гранулярности:

  • isSameDay — минимальная единица (день)
  • isSameWeek — агрегированная неделя с настраиваемой логикой
  • isSameMonth — месячный интервал как календарная сущность

Иерархия точности:

day < week < month

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

Оглавление