getDaysInYear

Функция getDaysInYear предназначена для определения количества дней в конкретном календарном году на основе переданной даты. Она учитывает григорианский календарь, включая високосные годы, и возвращает либо 365, либо 366.

Назначение и область применения

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

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

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

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

getDaysInYear(date)

Параметры

  • date — объект Date или значение, приводимое к дате Может быть:

    • экземпляром Date
    • timestamp (число миллисекунд)
    • строкой даты, распознаваемой JavaScript

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

  • number — количество дней в году:

    • 365 для обычного года
    • 366 для високосного года

Логика работы функции

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

Год является високосным, если:

  • делится на 4 без остатка;
  • но при этом не делится на 100, если только не делится на 400.

Именно это правило определяет, будет ли в году 365 или 366 дней.

Важное поведение

Функция не принимает год напрямую — она извлекает его из переданной даты. Это позволяет:

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

Базовый пример использования

import { getDaysInYear } from 'date-fns'

getDaysInYear(new Date(2024, 0, 1))
// 366

Год 2024 является високосным, поэтому результат — 366.

getDaysInYear(new Date(2023, 0, 1))
// 365

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

Передача строки

getDaysInYear('2022-05-15')
// 365

Передача timestamp

getDaysInYear(1672531200000)
// 365

Функция корректно приводит входное значение к объекту Date.

Високосные годы и их влияние

Високосные годы возникают каждые 4 года, но с исключениями, связанными с кратностью 100 и 400.

Примеры:

Год Високосный Дней
2000 да 366
1900 нет 365
2020 да 366
2021 нет 365

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

Разница в один день влияет на:

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

Внутренний принцип определения года

Функция не анализирует календарь вручную, а опирается на вычисление даты внутри года. Концептуально процесс выглядит так:

  1. Из входной даты извлекается год.
  2. Проверяется, является ли этот год високосным.
  3. Возвращается 365 или 366.

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

Примеры практических сценариев

Расчёт доли года

const daysInYear = getDaysInYear(date)
const progress = dayOfYear / daysInYear

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

Финансовые расчёты

const interest = principal * rate * (daysElapsed / getDaysInYear(date))

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

Нормализация временных рядов

При анализе данных важно учитывать разную длину годов:

  • 2023 → 365 дней
  • 2024 → 366 дней

Без этой поправки сравнение годовых показателей становится некорректным.

Особенности и ограничения

1. Зависимость от системной даты

Входные значения интерпретируются через стандартный Date, поэтому:

  • некорректные строки приводят к Invalid Date;
  • поведение зависит от реализации JavaScript-движка.

2. Игнорирование временной зоны

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

  • результат не зависит от часового пояса;
  • переходы UTC не влияют на итоговое значение.

3. Отсутствие параметризации календаря

Функция ориентирована строго на григорианский календарь:

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

Сравнение с близкими функциями date-fns

В рамках библиотеки существует несколько функций, работающих с годом:

  • getYear — возвращает номер года;
  • startOfYear — начало года;
  • endOfYear — конец года;
  • getDaysInYear — количество дней в году.

Отличие getDaysInYear

  • не возвращает дату;
  • не работает с диапазонами;
  • выполняет узкую календарную задачу.

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

При передаче даты в конце декабря или начале января результат будет зависеть только от года, а не от конкретного дня:

getDaysInYear(new Date(2024, 11, 31))
// 366

getDaysInYear(new Date(2025, 0, 1))
// 365

Обе даты принадлежат разным годам, и функция корректно отражает это.

Производительность

Функция имеет постоянную сложность O(1), так как:

  • выполняется простая проверка високосности;
  • отсутствуют циклы или итерации;
  • не производится вычисление календарных таблиц.

Это делает её пригодной для массового использования в больших датасетах.

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

Передача некорректной даты

getDaysInYear('invalid-date')
// NaN

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

Предположение о фиксированном году

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

Роль функции в работе с временными интервалами

getDaysInYear часто используется как базовый элемент при построении более сложных вычислений:

  • расчёт долей времени;
  • масштабирование временных метрик;
  • приведение данных к единому годовому масштабу.

Она служит точкой нормализации между календарной логикой и числовыми моделями времени.

Оглавление