isSameYear и другие варианты

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

Функция isSameYear определяет, принадлежат ли две даты одному и тому же календарному году. Сравнение выполняется по локальному или заданному часовому поясу контексту (в зависимости от переданных параметров окружения).

import { isSameYear } from 'date-fns';

isSameYear(new Date(2024, 0, 1), new Date(2024, 11, 31));
// true

isSameYear(new Date(2024, 11, 31), new Date(2025, 0, 1));
// false

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

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

isSameMonth

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

import { isSameMonth } from 'date-fns';

isSameMonth(new Date(2024, 5, 1), new Date(2024, 5, 31));
// true

isSameMonth(new Date(2024, 5, 30), new Date(2024, 6, 1));
// false

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

Особенность заключается в том, что год также учитывается. Поэтому июнь 2023 и июнь 2024 считаются разными месяцами.

isSameDay

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

import { isSameDay } from 'date-fns';

isSameDay(
  new Date(2024, 5, 10, 10, 0),
  new Date(2024, 5, 10, 23, 59)
);
// true

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

Следует учитывать, что функция ориентируется на локальное время выполнения. В системах с несколькими часовыми поясами это может приводить к различиям в результатах при одинаковых UTC-значениях.

isSameHour

isSameHour расширяет концепцию до часового интервала. Две даты считаются совпадающими, если они находятся в одном и том же часе календарного времени.

import { isSameHour } from 'date-fns';

isSameHour(
  new Date(2024, 5, 10, 14, 0),
  new Date(2024, 5, 10, 14, 59)
);
// true

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

isSameMinute и isSameSecond

Для более точного сравнения используются функции isSameMinute и isSameSecond.

import { isSameMinute, isSameSecond } from 'date-fns';

isSameMinute(
  new Date(2024, 5, 10, 14, 30, 10),
  new Date(2024, 5, 10, 14, 30, 59)
);
// true

isSameSecond(
  new Date(2024, 5, 10, 14, 30, 10, 500),
  new Date(2024, 5, 10, 14, 30, 10, 900)
);
// true

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

isSameWeek

Функция isSameWeek определяет принадлежность дат к одной неделе. Важной особенностью является то, что неделя может определяться с учётом локальных настроек (начало недели — воскресенье или понедельник).

import { isSameWeek } from 'date-fns';

isSameWeek(new Date(2024, 5, 10), new Date(2024, 5, 12));
// true или false в зависимости от настроек

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

isSameISOWeek

В отличие от isSameWeek, функция isSameISOWeek следует стандарту ISO 8601, где неделя всегда начинается с понедельника, а первая неделя года определяется по правилам ISO.

import { isSameISOWeek } from 'date-fns';

isSameISOWeek(new Date(2024, 0, 1), new Date(2024, 0, 3));
// true или false в зависимости от ISO-нумерации недель

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

isSameQuarter

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

import { isSameQuarter } from 'date-fns';

isSameQuarter(new Date(2024, 0, 1), new Date(2024, 2, 31));
// true

isSameQuarter(new Date(2024, 3, 1), new Date(2024, 2, 31));
// false

Квартальная логика широко применяется в бизнес-аналитике, финансовых отчётах и планировании.

isSameDecade и isSameCentury (расширенные сравнения)

Некоторые версии и расширенные наборы функций включают сравнения более крупных временных интервалов: десятилетий и веков.

import { isSameDecade } from 'date-fns';

isSameDecade(new Date(2024, 0, 1), new Date(2029, 11, 31));
// true

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

Общие принципы поведения функций сравнения

Все функции семейства isSame* имеют общие свойства:

  • Иммутабельность: исходные даты не изменяются
  • Строгое сравнение календарных единиц: игнорируются менее значимые поля
  • Локальная интерпретация времени: результаты зависят от временной зоны окружения
  • Отсутствие частичного совпадения: функция возвращает только true или false

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

Сочетание с другими функциями

Функции isSame* часто используются вместе с фильтрацией и группировкой:

import { isSameDay, isToday } from 'date-fns';

const events = [
  new Date(2024, 5, 10, 10, 0),
  new Date(2024, 5, 10, 15, 0),
  new Date(2024, 5, 11, 9, 0),
];

const todayEvents = events.filter(date =>
  isSameDay(date, new Date())
);

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

Оглавление