Проверка вхождения даты в интервал: isWithinInterval

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

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

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

isWithinInterval(date, interval)

Параметры

date Дата, которую необходимо проверить. Может быть передана в формате Date, timestamp или строка, совместимая с конструктором Date.

interval Объект интервала, содержащий две границы:

{
  start: Date | number,
  end: Date | number
}
  • start — начало интервала
  • end — конец интервала

Возвращаемое значение

Возвращает:

  • true — если дата находится внутри интервала (включая границы)
  • false — если дата выходит за пределы интервала

Включительность границ

Особенность реализации заключается в том, что границы интервала считаются включительными:

  • дата равная start считается входящей в интервал
  • дата равная end также считается входящей в интервал

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

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

import { isWithinInterval } from 'date-fns';

const date = new Date(2026, 0, 15);

const interval = {
  start: new Date(2026, 0, 10),
  end: new Date(2026, 0, 20),
};

const result = isWithinInterval(date, interval);
// true

Проверка выхода за границы интервала

const date = new Date(2026, 0, 5);

const interval = {
  start: new Date(2026, 0, 10),
  end: new Date(2026, 0, 20),
};

isWithinInterval(date, interval);
// false

Работа с timestamp

Функция поддерживает числовые значения времени (Unix timestamp в миллисекундах):

const date = Date.now();

const interval = {
  start: Date.now() - 10000,
  end: Date.now() + 10000,
};

isWithinInterval(date, interval);
// true

Преобразование строковых дат

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

const date = '2026-01-15T12:00:00Z';

const interval = {
  start: '2026-01-10T00:00:00Z',
  end: '2026-01-20T00:00:00Z',
};

isWithinInterval(date, interval);
// true

При этом внутри происходит преобразование в объекты Date, что требует корректного ISO-формата или совместимого представления.

Важность порядка границ

Функция предполагает, что start меньше или равен end. При нарушении этого условия поведение становится некорректным с точки зрения логики сравнения.

const interval = {
  start: new Date(2026, 0, 20),
  end: new Date(2026, 0, 10),
};

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

Использование в фильтрации массивов

Типичный сценарий — фильтрация списка дат:

const dates = [
  new Date(2026, 0, 5),
  new Date(2026, 0, 12),
  new Date(2026, 0, 18),
];

const interval = {
  start: new Date(2026, 0, 10),
  end: new Date(2026, 0, 15),
};

const filtered = dates.filter(date =>
  isWithinInterval(date, interval)
);

// [2026-01-12]

Применение в системах событий

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

const event = {
  start: new Date(2026, 0, 12),
  end: new Date(2026, 0, 14),
};

const range = {
  start: new Date(2026, 0, 10),
  end: new Date(2026, 0, 20),
};

isWithinInterval(event.start, range);
// true

isWithinInterval(event.end, range);
// true

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

date-fns работает с объектами Date, которые хранят время в формате UTC, но отображение зависит от локальной временной зоны среды выполнения.

Это означает:

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

Проверка текущей даты

Частый паттерн — проверка, находится ли текущее время в заданном диапазоне:

const interval = {
  start: new Date(2026, 0, 1),
  end: new Date(2026, 11, 31),
};

isWithinInterval(new Date(), interval);

Использование в бизнес-логике доступа

Функция часто применяется для контроля доступности ресурсов:

  • активные подписки
  • временные акции
  • окна доступа к API
  • расписания публикаций
const subscription = {
  start: new Date(2026, 0, 1),
  end: new Date(2026, 6, 1),
};

const now = new Date();

const active = isWithinInterval(now, subscription);

Сравнение с альтернативными подходами

Без date-fns аналогичная проверка выполняется вручную:

const result =
  date >= interval.start && date <= interval.end;

Однако использование isWithinInterval снижает вероятность ошибок:

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

Частые ошибки при использовании

1. Перепутанные границы

const interval = {
  start: new Date(2026, 0, 20),
  end: new Date(2026, 0, 10),
};

2. Передача некорректных типов

isWithinInterval("not a date", {
  start: new Date(),
  end: new Date()
});

3. Игнорирование включительности границ

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

Поведение при одинаковых границах

Если start и end совпадают, интервал становится точкой:

const interval = {
  start: new Date(2026, 0, 10),
  end: new Date(2026, 0, 10),
};

isWithinInterval(new Date(2026, 0, 10), interval);
// true

Любая другая дата даст false.

Интеграция в цепочки date-fns

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

  • parseISO для преобразования строк
  • addDays и subDays для формирования интервалов
  • format для вывода результатов
import { isWithinInterval, addDays } from 'date-fns';

const start = new Date();
const end = addDays(start, 7);

isWithinInterval(new Date(), { start, end });
Оглавление