Извлечение компонентов даты

В библиотеке js-joda модель даты строится на строгом разделении календарных и временных компонентов. Объекты типа LocalDate и LocalDateTime предоставляют неизменяемое представление даты, где каждый элемент извлекается через специализированные методы или универсальный доступ по полям времени.

Архитектура извлечения компонентов опирается на концепцию TemporalField, позволяющую получать значения как через высокоуровневые методы, так и через унифицированный интерфейс полей календаря.

Базовые компоненты LocalDate

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

  • год
  • месяц
  • день месяца
  • день года
  • день недели

Извлечение года, месяца и дня

Каждый компонент доступен через строго типизированные методы:

import { LocalDate } from '@js-joda/core';

const date = LocalDate.of(2026, 5, 24);

const year = date.getYear();
const month = date.getMonthValue();
const day = date.getDayOfMonth();

getYear() возвращает календарный год как целое число. getMonthValue() возвращает номер месяца в диапазоне от 1 до 12. getDayOfMonth() возвращает день месяца в диапазоне от 1 до 31.

Альтернативный доступ к месяцу осуществляется через объект Month, который предоставляет более выразительное представление:

const monthEnum = date.getMonth();

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

День недели и день года

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

const dayOfWeek = date.getDayOfWeek();
const dayOfYear = date.getDayOfYear();

getDayOfWeek() возвращает объект DayOfWeek, отражающий день недели по ISO-8601 (понедельник = 1, воскресенье = 7).

getDayOfYear() возвращает порядковый номер дня в году, начиная с 1 января.

Пример анализа календарного положения даты:

import { LocalDate } from '@js-joda/core';

const date = LocalDate.of(2026, 1, 15);

const info = {
  year: date.getYear(),
  month: date.getMonthValue(),
  day: date.getDayOfMonth(),
  dayOfWeek: date.getDayOfWeek().toString(),
  dayOfYear: date.getDayOfYear()
};

Извлечение компонентов через TemporalField

Помимо специализированных методов, js-joda поддерживает универсальный механизм доступа через ChronoField. Этот подход используется для динамического извлечения значений и построения абстрактных календарных операций.

import { LocalDate, ChronoField } from '@js-joda/core';

const date = LocalDate.of(2026, 5, 24);

const year = date.get(ChronoField.YEAR);
const month = date.get(ChronoField.MONTH_OF_YEAR);
const day = date.get(ChronoField.DAY_OF_MONTH);

Механизм get() работает через интерфейс TemporalAccessor, где каждое поле проверяется на поддерживаемость конкретным типом даты.

Дополнительно доступны расширенные поля:

const dayOfYear = date.get(ChronoField.DAY_OF_YEAR);
const dayOfWeek = date.get(ChronoField.DAY_OF_WEEK);

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

Компоненты LocalDateTime

LocalDateTime объединяет календарные и временные компоненты. В отличие от LocalDate, здесь добавляются часы, минуты, секунды и наносекунды.

import { LocalDateTime } from '@js-joda/core';

const dateTime = LocalDateTime.of(2026, 5, 24, 14, 35, 50);

Извлечение даты

const year = dateTime.getYear();
const month = dateTime.getMonthValue();
const day = dateTime.getDayOfMonth();

Эти методы полностью совпадают с интерфейсом LocalDate, так как дата является общей частью обеих моделей.

Извлечение времени

const hour = dateTime.getHour();
const minute = dateTime.getMinute();
const second = dateTime.getSecond();
const nano = dateTime.getNano();

Каждый компонент соответствует строго определённому диапазону:

  • часы: 0–23
  • минуты: 0–59
  • секунды: 0–59
  • наносекунды: 0–999_999_999

Унифицированный доступ к временным полям

LocalDateTime также поддерживает ChronoField, объединяя доступ к календарным и временным компонентам:

import { ChronoField } from '@js-joda/core';

const hour = dateTime.get(ChronoField.HOUR_OF_DAY);
const minute = dateTime.get(ChronoField.MINUTE_OF_HOUR);
const second = dateTime.get(ChronoField.SECOND_OF_MINUTE);

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

const nanoOfDay = dateTime.get(ChronoField.NANO_OF_DAY);
const secondOfDay = dateTime.get(ChronoField.SECOND_OF_DAY);

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

Особенности извлечения перечислений Month и DayOfWeek

Объекты Month и DayOfWeek в js-joda не являются примитивными числами. Они инкапсулируют логику календаря и предоставляют дополнительные методы.

Month

const month = date.getMonth();

const length = month.length(false); // количество дней в месяце без учёта високосного года

length(isLeapYear) позволяет учитывать особенности календаря при работе с февралем.

DayOfWeek

const dow = date.getDayOfWeek();

const value = dow.getValue();

getValue() возвращает числовое представление дня недели по ISO-стандарту.

Проверка доступности полей

Не все поля доступны для всех типов временных объектов. Для проверки используется метод isSupported:

import { ChronoField } from '@js-joda/core';

const supported = date.isSupported(ChronoField.HOUR_OF_DAY);

Для LocalDate результат будет отрицательным, так как объект не содержит временной части.

Для LocalDateTime поддержка времени возвращает положительные значения:

const supportedTime = dateTime.isSupported(ChronoField.SECOND_OF_MINUTE);

Извлечение всех компонентов как структура

Комбинирование методов позволяет формировать полное представление даты и времени:

import { LocalDateTime } from '@js-joda/core';

const dt = LocalDateTime.of(2026, 5, 24, 14, 35, 50);

const snapshot = {
  year: dt.getYear(),
  month: dt.getMonthValue(),
  day: dt.getDayOfMonth(),
  dayOfWeek: dt.getDayOfWeek().getValue(),
  hour: dt.getHour(),
  minute: dt.getMinute(),
  second: dt.getSecond(),
  nano: dt.getNano()
};

Такая структура часто используется при сериализации или передаче данных между слоями приложения.

Семантика неизменяемости при извлечении

Каждый вызов метода извлечения компонента не изменяет исходный объект. LocalDate и LocalDateTime остаются неизменяемыми, что обеспечивает предсказуемость поведения при многократных операциях доступа.

const original = LocalDate.of(2026, 5, 24);

const year = original.getYear();
const month = original.getMonthValue();

const same = original; // объект не изменён

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

Использование полей в вычислениях

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

const date = LocalDate.of(2026, 5, 24);

const nextYear = date.getYear() + 1;
const isStartOfMonth = date.getDayOfMonth() === 1;
const isWeekend = date.getDayOfWeek().getValue() >= 6;

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

Итоговая модель извлечения

Система извлечения компонентов в js-joda строится на трёх уровнях:

  • специализированные методы (getYear, getMonthValue, getHour)
  • объектные перечисления (Month, DayOfWeek)
  • универсальный доступ через ChronoField

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

Оглавление