isEqual для точного сравнения

В библиотеке date-fns функция isEqual предназначена для строгого сравнения двух значений даты по абсолютному моменту времени. Сравнение выполняется не по календарным компонентам (день, месяц, год), а по числовому представлению времени — количеству миллисекунд с 1 января 1970 года (Unix epoch).

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

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

Принцип работы сравнения

В основе логики лежит приведение входных значений к объектам Date и сравнение их временного значения:

dateLeft.getTime() === dateRight.getTime()

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

Поведение функции

Полное совпадение времени

import { isEqual } from 'date-fns';

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

isEqual(a, b); // true

Даже минимальное расхождение во времени приводит к false.

Различие в миллисекундах

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

isEqual(a, b); // false

Типы входных данных

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

  • Date
  • timestamp (число)
  • строка даты (если корректно распознаётся)
isEqual(new Date('2026-01-01'), '2026-01-01'); // true (после приведения)
isEqual(1704067200000, new Date(1704067200000)); // true

Все входные значения приводятся к единому внутреннему виду перед сравнением.

Отличие от календарного сравнения

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

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

isEqual(a, b); // false

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

  • isSameDay
  • isSameMonth
  • isSameYear

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

Сравнение выполняется на основе UTC-значений, так как Date.getTime() всегда возвращает абсолютное время.

const a = new Date('2026-01-01T00:00:00+03:00');
const b = new Date('2025-12-31T21:00:00Z');

isEqual(a, b); // true

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

Обработка некорректных дат

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

isEqual(new Date('invalid'), new Date()); // false

Это поведение предотвращает ложные совпадения и упрощает проверку корректности данных.

Сравнение с другими подходами

Прямое сравнение объектов Date

a === b // всегда false для разных объектов

Даже одинаковые даты как объекты не равны, поскольку сравниваются ссылки.

Сравнение через getTime

a.getTime() === b.getTime()

isEqual фактически инкапсулирует этот подход, добавляя поддержку преобразования входных типов и обработку некорректных значений.

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

Проверка дубликатов событий

const eventExists = events.some(event =>
  isEqual(event.date, newEvent.date)
);

Используется для строгого выявления совпадающих временных меток.

Сравнение временных меток в синхронизации

if (isEqual(serverTimestamp, localTimestamp)) {
  // данные уже синхронизированы
}

Особенности точности

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

const a = new Date('2026-01-01T12:00:00.000');
const b = new Date('2026-01-01T12:00:00.999');

isEqual(a, b); // false

Использование с временными метками

Часто применяется при работе с API, где даты приходят в формате timestamp:

const apiDate = 1704067200000;
const localDate = Date.now();

isEqual(apiDate, localDate);

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

Вход 1 Вход 2 Результат
Date Date сравнение времени
Date number сравнение после приведения
string Date сравнение после парсинга
invalid Date false
invalid invalid false

Логическая модель функции

Функцию можно представить как последовательность преобразований:

  1. Приведение входных значений к объекту Date
  2. Получение числового представления времени
  3. Строгое сравнение чисел

Ограничения подхода

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

Использование в композиции с другими функциями

В связке с другими функциями date-fns часто строятся более сложные проверки:

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

isEqual(startOfDay(a), startOfDay(b));

Такой подход позволяет переходить от точного сравнения ко временно-нормализованному.

Поведение при работе с будущими и прошедшими датами

Функция не делает различий между прошедшим и будущим временем — учитывается только абсолютное совпадение:

isEqual(new Date('2026-01-01'), new Date('2026-01-01')); // true

Роль в типичных архитектурах

В прикладных системах isEqual используется как базовый строительный блок:

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

Итоговая модель поведения

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

Оглавление