Определение квартала: getQuarter

Функция getQuarter в библиотеке date-fns используется для определения календарного квартала, к которому относится переданная дата. Кварталы в данной системе нумеруются от 1 до 4 и соответствуют стандартному делению года на четырёхмесячные периоды: январь–март, апрель–июнь, июль–сентябрь, октябрь–декабрь.

Календарный год делится на четыре равные части:

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

Функция анализирует месяц даты и вычисляет принадлежность к одному из этих диапазонов. Логика основана на целочисленном делении номера месяца на 3 с последующим округлением вверх.

Синтаксис

getQuarter(date)

Параметр date может быть:

  • объектом Date
  • строкой, приводимой к дате
  • timestamp (число миллисекунд)

Возвращаемое значение — целое число от 1 до 4.

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

import { getQuarter } from 'date-fns'

getQuarter(new Date(2024, 0, 15)) // 1
getQuarter(new Date(2024, 3, 10)) // 2
getQuarter(new Date(2024, 6, 1))  // 3
getQuarter(new Date(2024, 9, 30)) // 4

В примере используется нумерация месяцев JavaScript, где январь соответствует 0, а декабрь — 11.

Логика вычисления

Внутренняя формула определения квартала сводится к преобразованию номера месяца:

quarter = Math.floor(month / 3) + 1

где month — это значение от 0 до 11.

Таким образом:

  • месяцы 0–2 дают квартал 1
  • месяцы 3–5 дают квартал 2
  • месяцы 6–8 дают квартал 3
  • месяцы 9–11 дают квартал 4

Работа с различными типами входных данных

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

getQuarter('2025-02-01')        // 1
getQuarter(1706745600000)       // 1 (timestamp)
getQuarter(new Date())          // зависит от текущей даты

Строковые значения интерпретируются через стандартный парсер Date, поэтому корректность результата зависит от формата строки.

Особенности обработки даты

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

Важные моменты:

  • некорректные строки приводят к Invalid Date
  • NaN или undefined не являются допустимыми значениями
  • поведение зависит от механизма преобразования Date внутри JavaScript

Применение в реальных задачах

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

Пример группировки продаж:

const sales = [
  { date: new Date(2024, 0, 10), amount: 120 },
  { date: new Date(2024, 2, 5), amount: 200 },
  { date: new Date(2024, 5, 18), amount: 150 },
]

const grouped = sales.reduce((acc, item) => {
  const q = getQuarter(item.date)
  acc[q] = (acc[q] || 0) + item.amount
  return acc
}, {})

console.log(grouped)
// { '1': 320, '2': 150 }

Кварталы в финансовой аналитике

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

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

Использование getQuarter упрощает привязку даты к отчетному периоду без ручных вычислений.

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

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

getQuarter(new Date('2024-03-31T23:30:00Z'))

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

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

Операция вычисления квартала является константной по сложности O(1) и не зависит от размера данных или внешних источников. Функция не выполняет сложных преобразований, кроме извлечения месяца и арифметического расчета.

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

На практике встречаются следующие проблемы:

  • передача строки в нестабильном формате даты
  • ожидание квартала в формате 0–3 вместо 1–4
  • игнорирование локального часового пояса
  • смешивание календарного и финансового года (если он отличается от календарного)

Связь с другими функциями date-fns

getQuarter часто используется вместе с функциями:

  • startOfQuarter — начало квартала
  • endOfQuarter — конец квартала
  • differenceInQuarters — разница между кварталами
  • addQuarters — прибавление кварталов к дате

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

Оглавление