День недели по ISO

ISO-нумерация дней недели основана на стандарте ISO 8601, где неделя начинается с понедельника, а дни получают значения от 1 до 7. Понедельник соответствует 1, вторник — 2, и так далее до воскресенья, которое имеет значение 7. Такой подход отличается от привычной нумерации в JavaScript и многих локалях, где неделя часто начинается с воскресенья (0) или понедельника (1, но с иной семантикой).

В библиотеке Day.js работа с ISO-днями недели реализуется через плагин isoWeek и метод isoWeekday(), который предоставляет согласованное поведение с ISO 8601 и устраняет неоднозначности локальных календарных настроек.

Стандартный объект Date в JavaScript использует метод:

new Date().getDay()

который возвращает значения от 0 до 6:

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

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

ISO 8601 и нормализация недель

ISO 8601 определяет строгую модель:

  • неделя всегда начинается с понедельника
  • дни недели нумеруются от 1 до 7
  • неделя 1 года — та, которая содержит первый четверг января

В контексте дней недели важна именно линейная шкала:

День ISO-значение
Понедельник 1
Вторник 2
Среда 3
Четверг 4
Пятница 5
Суббота 6
Воскресенье 7

Day.js реализует эту модель через дополнительный API поверх базового ядра.

Подключение поддержки ISO-дней недели в Day.js

Для работы с ISO-нумерацией необходимо подключить плагин:

import dayjs from 'dayjs'
import isoWeek from 'dayjs/plugin/isoWeek'

dayjs.extend(isoWeek)

После расширения API появляется метод isoWeekday() и набор функций, связанных с ISO-неделями.

Метод isoWeekday(): получение дня недели

Основной метод работы:

dayjs().isoWeekday()

Он возвращает число от 1 до 7 в соответствии с ISO-стандартом.

Пример:

import dayjs from 'dayjs'
import isoWeek from 'dayjs/plugin/isoWeek'

dayjs.extend(isoWeek)

const d = dayjs('2026-05-22')

console.log(d.isoWeekday())

Результат будет интерпретирован как день недели по ISO-системе.

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

Метод isoWeekday() работает не только как геттер, но и как сеттер:

dayjs().isoWeekday(1)

Это устанавливает дату на ближайший понедельник текущей недели.

Пример изменения дня:

const date = dayjs('2026-05-22')

// перенос на понедельник той же недели
const monday = date.isoWeekday(1)

// перенос на воскресенье
const sunday = date.isoWeekday(7)

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

Различие между weekday() и isoWeekday()

Day.js также предоставляет метод weekday(), который приходит из другого плагина — weekday.

Подключение:

import weekday from 'dayjs/plugin/weekday'
dayjs.extend(weekday)

Ключевое различие:

  • weekday() зависит от локали и настройки начала недели
  • isoWeekday() всегда строго следует ISO 8601

Поведение weekday()

dayjs().weekday()

Значение может интерпретироваться по-разному в зависимости от локали:

  • в одной конфигурации неделя начинается с воскресенья
  • в другой — с понедельника

Это делает weekday() чувствительным к окружению.

Поведение isoWeekday()

dayjs().isoWeekday()

Всегда фиксированная модель:

  • 1 = понедельник
  • 7 = воскресенье

Нет зависимости от локали или пользовательских настроек.

Практическое применение ISO-дней

Сравнение дней недели

const a = dayjs('2026-05-20')
const b = dayjs('2026-05-22')

if (a.isoWeekday() < b.isoWeekday()) {
  // a раньше в рамках недели
}

Определение понедельника и воскресенья недели

const date = dayjs('2026-05-22')

const monday = date.isoWeekday(1)
const sunday = date.isoWeekday(7)

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

Построение недельных диапазонов

function getIsoWeekRange(date) {
  const d = dayjs(date)

  return {
    start: d.isoWeekday(1),
    end: d.isoWeekday(7)
  }
}

Результат всегда соответствует ISO-неделе независимо от входной даты.

Работа с переходами между неделями

При установке значения вне диапазона 1–7 Day.js нормализует результат, переходя в соседние недели:

dayjs().isoWeekday(8) // следующий понедельник
dayjs().isoWeekday(0) // предыдущая неделя воскресенье

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

Сочетание с ISO-неделями (isoWeek)

Плагин isoWeek дополняет isoWeekday() методами работы с номером недели:

dayjs.extend(isoWeek)

dayjs().isoWeek()       // номер ISO-недели
dayjs().isoWeekYear()   // ISO-год

Это важно в задачах, где требуется строгая календарная идентичность:

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

Сдвиг недели относительно ISO-дня

Комбинация isoWeekday() с арифметикой дат:

const base = dayjs('2026-05-22')

const nextTuesday = base.isoWeekday(2).add(1, 'week')

Такой подход фиксирует день недели и перемещает его по временной оси.

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

Использование getDay() вместо isoWeekday()

// некорректно для ISO-логики
const day = new Date().getDay()

Это приводит к смещению логики недели и необходимости дополнительных преобразований.

Предположение о неизменности локали

Метод weekday() может вести себя по-разному в зависимости от конфигурации окружения, что делает его ненадёжным для систем, где важна строгая календарная согласованность.

Игнорирование границ недели

Установка дня недели не меняет смысл даты как календарного объекта:

dayjs('2026-05-22').isoWeekday(1)

Результат — дата из той же недели, а не «абсолютный понедельник».

Особенности внутренней модели Day.js

Day.js опирается на immutable-архитектуру:

  • каждый вызов isoWeekday() возвращает новый объект
  • исходная дата не изменяется
  • цепочки методов остаются чистыми
const d = dayjs('2026-05-22')

const updated = d.isoWeekday(1)

console.log(d.format())
console.log(updated.format())

Использование в календарных интерфейсах

ISO-дни недели применяются при построении UI-компонентов:

  • сетки календаря
  • недельные планировщики
  • расписания задач

Типовой алгоритм формирования недели:

function buildWeek(date) {
  const start = dayjs(date).isoWeekday(1)

  return Array.from({ length: 7 }).map((_, i) =>
    start.add(i, 'day')
  )
}

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

Согласованность с международными системами

ISO-логика критична в интеграциях:

  • API календарей
  • Google Calendar-подобные системы
  • корпоративные ERP
  • банковские отчётные периоды

Day.js через isoWeekday() обеспечивает единый стандарт интерпретации дней недели без привязки к региональным настройкам среды выполнения.

Оглавление