Установка по дню года

В JavaScript-библиотеках для работы с датами концепция «день года» (day of year) используется для представления даты как порядкового номера в пределах календарного года. Значение находится в диапазоне от 1 до 365, а в високосный год — до 366. Такая модель упрощает задачи анализа временных рядов, календарных расчётов и нормализации дат.

В Day.js работа с днём года реализуется через дополнительный плагин dayOfYear, поскольку базовая сборка библиотеки не включает эту функциональность.

Подключение плагина dayOfYear

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

npm install dayjs

Далее подключается основной модуль и плагин:

import dayjs from 'dayjs'
import dayOfYear from 'dayjs/plugin/dayOfYear'

dayjs.extend(dayOfYear)

После расширения экземпляры Day.js получают доступ к методу dayOfYear().

Получение дня года

Метод без аргументов возвращает порядковый номер дня в году:

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

console.log(date.dayOfYear()) // например: 143

Поведение метода зависит от локальной даты и учитывает:

  • количество дней в месяце
  • високосные годы
  • временную зону (если используется локальная дата)

Установка дня года

Метод dayOfYear(value) позволяет задать дату, исходя из порядкового номера дня в году:

const date = dayjs().dayOfYear(100)

console.log(date.format('YYYY-MM-DD'))

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

Особенности изменения даты через dayOfYear

При установке значения Day.js пересчитывает дату относительно начала года:

const base = dayjs('2026-01-01')
const updated = base.dayOfYear(60)

console.log(updated.format('YYYY-MM-DD'))

Логика преобразования:

  • берётся 1 января текущего года
  • добавляется (n - 1) дней
  • возвращается новый объект Day.js

Работа с високосными годами

В високосные годы диапазон расширяется до 366 дней:

const leap = dayjs('2024-12-31')
console.log(leap.dayOfYear()) // 366

При установке значения, превышающего допустимый диапазон, поведение нормализуется:

dayjs('2024-01-01').dayOfYear(370)

Результат будет перенесён на следующий год с корректировкой остатка дней.

Преобразование дня года в дату

Частая задача — восстановление даты из порядкового номера дня:

function fromDayOfYear(year, n) {
  return dayjs(`${year}-01-01`).dayOfYear(n)
}

console.log(fromDayOfYear(2026, 200).format('YYYY-MM-DD'))

Такая конструкция используется при обработке:

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

Проверка корректности значения

Перед установкой дня года часто требуется ограничение диапазона:

function safeDayOfYear(date, n) {
  const max = date.isLeapYear() ? 366 : 365
  const clamped = Math.min(Math.max(n, 1), max)

  return date.dayOfYear(clamped)
}

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

Сравнение с обычной работой с датами

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

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

Пример эквивалентного вычисления:

const a = dayjs('2026-02-01').dayOfYear()
const b = dayjs('2026-05-23').dayOfYear()

console.log(b - a)

Практическое применение

Механизм дня года используется в сценариях, где календарная структура менее важна, чем линейная шкала времени:

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

Нормализация при переходе границ года

При работе с большими значениями происходит автоматическое смещение:

dayjs('2025-12-31').dayOfYear(10)

Такой вызов приведёт к переходу на следующий год и корректному вычислению даты относительно нового начала года.

Использование в цепочках преобразований

Метод dayOfYear хорошо комбинируется с другими операциями Day.js:

const result = dayjs('2026-01-01')
  .add(2, 'year')
  .dayOfYear(150)
  .format('YYYY-MM-DD')

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

Оглавление