Настройка первого дня недели

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

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

Параметр weekStartsOn

Параметр weekStartsOn принимает целое число от 0 до 6:

  • 0 — воскресенье
  • 1 — понедельник
  • 2 — вторник
  • 3 — среда
  • 4 — четверг
  • 5 — пятница
  • 6 — суббота

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

Пример локального применения:

import { startOfWeek } from "date-fns";

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

// Неделя начинается с понедельника
const result = startOfWeek(date, { weekStartsOn: 1 });

console.log(result);

В данном случае результатом будет дата, соответствующая понедельнику текущей недели, содержащей указанную дату.

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

Функция startOfWeek

Функция startOfWeek вычисляет начало недели для заданной даты с учётом параметра weekStartsOn.

Сигнатура:

startOfWeek(date, options)

Параметры:

  • date — исходная дата
  • options.weekStartsOn — день начала недели

Пример использования:

import { startOfWeek } from "date-fns";

const date = new Date(2026, 4, 22);

console.log(startOfWeek(date, { weekStartsOn: 0 })); // воскресенье
console.log(startOfWeek(date, { weekStartsOn: 1 })); // понедельник

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

Функция endOfWeek и симметрия интервалов

Функция endOfWeek дополняет startOfWeek, возвращая конец недели с учётом того же параметра.

import { startOfWeek, endOfWeek } from "date-fns";

const date = new Date(2026, 4, 22);

const start = startOfWeek(date, { weekStartsOn: 1 });
const end = endOfWeek(date, { weekStartsOn: 1 });

console.log(start, end);

Согласованность параметров критична: различие в weekStartsOn между двумя вызовами приводит к некорректным интервалам.

Глобальная настройка через setDefaultOptions

Для устранения необходимости передачи weekStartsOn в каждом вызове используется функция setDefaultOptions.

import { setDefaultOptions, startOfWeek } from "date-fns";

setDefaultOptions({
  weekStartsOn: 1
});

const date = new Date(2026, 4, 22);

console.log(startOfWeek(date));

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

Особенности глобальной конфигурации

  • применяется ко всем функциям библиотеки в текущем контексте
  • может быть переопределена локальными параметрами
  • влияет только на функции, поддерживающие weekStartsOn

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

Влияние локалей на начало недели

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

Пример использования локали:

import { startOfWeek } from "date-fns";
import { ru } from "date-fns/locale";

const date = new Date(2026, 4, 22);

const result = startOfWeek(date, {
  locale: ru
});

console.log(result);

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

Сравнение подходов

  • weekStartsOn — явное управление логикой
  • locale — культурно обусловленное поведение

При конфликте приоритет обычно отдаётся явному параметру.

Неделя и нумерация через getWeek

Функция getWeek возвращает номер недели в году, и её результат напрямую зависит от начала недели.

import { getWeek } from "date-fns";

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

console.log(getWeek(date, { weekStartsOn: 0 }));
console.log(getWeek(date, { weekStartsOn: 1 }));

Разные значения weekStartsOn могут смещать нумерацию, особенно на границах года.

Влияние на форматирование дат

При использовании функций форматирования, таких как format, параметр начала недели влияет на токены, связанные с неделями (w, ww, I, II в ISO-режиме).

import { format } from "date-fns";

const date = new Date(2026, 4, 22);

console.log(format(date, "w"));

При изменении начала недели меняется распределение дат по неделям, что отражается на выводе.

ISO-неделя и независимость от weekStartsOn

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

Функции:

  • startOfISOWeek
  • getISOWeek
  • endOfISOWeek

Пример:

import { startOfISOWeek } from "date-fns";

const date = new Date(2026, 4, 22);

console.log(startOfISOWeek(date));

ISO-логика используется в международных стандартах отчётности и не зависит от локальных параметров.

Типичные сценарии конфигурации

Корпоративный стандарт понедельника

import { setDefaultOptions } from "date-fns";

setDefaultOptions({
  weekStartsOn: 1
});

Используется в системах планирования задач и финансовой отчётности.

Веб-приложения с локализацией

import { startOfWeek } from "date-fns";
import { enUS, ru } from "date-fns/locale";

startOfWeek(new Date(), { locale: ru });
startOfWeek(new Date(), { locale: enUS });

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

Гибридная модель

Комбинация глобальной настройки и локального переопределения:

setDefaultOptions({ weekStartsOn: 1 });

startOfWeek(date); // понедельник
startOfWeek(date, { weekStartsOn: 0 }); // воскресенье

Ошибки при работе с началом недели

Несогласованность параметров

Различие между функциями в одном модуле приводит к логическим ошибкам:

startOfWeek(date, { weekStartsOn: 1 });
endOfWeek(date, { weekStartsOn: 0 });

Интервал становится некорректным.

Игнорирование глобальных настроек

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

Конфликт локали и weekStartsOn

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

Архитектурное значение настройки начала недели

Выбор начала недели влияет на:

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

Единая стратегия определения недели обеспечивает согласованность данных во всех слоях приложения.

Оглавление