Названия месяцев и дней недели

В библиотеке js-joda календарные сущности, связанные с названиями месяцев и дней недели, представлены строго типизированными перечислениями, повторяющими модель Java Time API. Это обеспечивает предсказуемость поведения, отсутствие локализационных ошибок на уровне хранения данных и единый способ работы с календарными значениями независимо от формата вывода.

Month: структура и семантика месяцев

Константы Month

В js-joda каждый месяц представлен как часть перечисления Month:

  • Month.JANUARY
  • Month.FEBRUARY
  • Month.MARCH
  • Month.APRIL
  • Month.MAY
  • Month.JUNE
  • Month.JULY
  • Month.AUGUST
  • Month.SEPTEMBER
  • Month.OCTOBER
  • Month.NOVEMBER
  • Month.DECEMBER

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

Числовое представление месяца

Каждый месяц связан с числовым индексом в диапазоне 1–12:

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

Month.JANUARY.value();   // 1
Month.DECEMBER.value();  // 12

Использование value() важно при интеграции с внешними системами, где месяцы представлены числами (например, API, базы данных, протоколы обмена).

Получение месяца из числа

Обратное преобразование выполняется через of():

Month.of(1);  // JANUARY
Month.of(12); // DECEMBER

При передаче некорректного значения (0 или 13) возникает исключение, что позволяет выявлять ошибки на этапе выполнения, а не в логике обработки дат.

Сравнение месяцев

Перечисление поддерживает естественный порядок:

Month.JANUARY.compareTo(Month.MARCH); // < 0
Month.DECEMBER.compareTo(Month.APRIL); // > 0

Также доступны проверки:

Month.JANUARY.isBefore(Month.FEBRUARY); // true
Month.DECEMBER.isAfter(Month.APRIL);    // true

Операции с месяцами

Поддерживаются циклические операции:

Month.DECEMBER.plus(1); // JANUARY
Month.JANUARY.minus(1); // DECEMBER

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

DayOfWeek: структура дней недели

Константы DayOfWeek

Дни недели в js-joda представлены следующим образом:

  • DayOfWeek.MONDAY
  • DayOfWeek.TUESDAY
  • DayOfWeek.WEDNESDAY
  • DayOfWeek.THURSDAY
  • DayOfWeek.FRIDAY
  • DayOfWeek.SATURDAY
  • DayOfWeek.SUNDAY

Началом недели считается понедельник, что соответствует ISO-8601.

Числовая модель дней недели

Каждый день имеет фиксированное значение от 1 до 7:

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

DayOfWeek.MONDAY.value();   // 1
DayOfWeek.SUNDAY.value();   // 7

Эта модель важна для интероперабельности с системами, использующими ISO-нумерацию дней недели.

Создание DayOfWeek из числа

DayOfWeek.of(1); // MONDAY
DayOfWeek.of(7); // SUNDAY

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

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

DayOfWeek.MONDAY.compareTo(DayOfWeek.FRIDAY); // < 0
DayOfWeek.SUNDAY.compareTo(DayOfWeek.MONDAY); // > 0

Дополнительно:

DayOfWeek.MONDAY.isBefore(DayOfWeek.WEDNESDAY); // true
DayOfWeek.SATURDAY.isAfter(DayOfWeek.FRIDAY);   // true

Циклические операции

DayOfWeek.MONDAY.plus(1); // TUESDAY
DayOfWeek.SUNDAY.plus(1); // MONDAY

DayOfWeek.MONDAY.minus(1); // SUNDAY

Цикличность особенно важна при расчёте рабочих графиков и календарных расписаний.

Названия месяцев и дней недели (локализация)

Сами перечисления Month и DayOfWeek не содержат строковых названий. Для получения человекочитаемых форм используется форматирование через DateTimeFormatter и локализационные механизмы.

Форматирование через TextStyle

import { Month, DayOfWeek } from '@js-joda/core';
import { TextStyle, Locale } from '@js-joda/locale';

Month.JANUARY.getDisplayName(TextStyle.FULL, Locale.ENGLISH);
// "January"

DayOfWeek.MONDAY.getDisplayName(TextStyle.FULL, Locale.ENGLISH);
// "Monday"

Поддерживаются стили:

  • TextStyle.FULL — полное название
  • TextStyle.SHORT — сокращённое
  • TextStyle.NARROW — минимальное обозначение

Примеры локализаций

Month.JANUARY.getDisplayName(TextStyle.FULL, Locale.ENGLISH); // January
Month.JANUARY.getDisplayName(TextStyle.FULL, Locale.FRENCH);  // janvier
DayOfWeek.MONDAY.getDisplayName(TextStyle.SHORT, Locale.ENGLISH); // Mon
DayOfWeek.MONDAY.getDisplayName(TextStyle.SHORT, Locale.GERMAN);  // Mo

Использование в DateTimeFormatter

При форматировании дат названия месяцев и дней недели формируются автоматически:

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

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

const formatter = DateTimeFormatter.ofPattern('EEEE, d MMMM yyyy', Locale.ENGLISH);

date.format(formatter);
// "Sunday, 15 March 2026"

Ключевые шаблоны:

  • MMMM — полное название месяца
  • MMM — сокращённое название месяца
  • EEEE — полное название дня недели
  • E — короткая форма дня недели

Связь с LocalDate и календарной логикой

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

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

date.month();     // Month.MAY
date.dayOfWeek(); // DayOfWeek.MONDAY

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

Использование в логике расписаний

const isWeekend = (day) =>
  day === DayOfWeek.SATURDAY || day === DayOfWeek.SUNDAY;
const isFirstHalfOfYear = (month) =>
  month.value() <= 6;

Такие проверки остаются независимыми от локализации и форматов представления.

Сравнение с числовыми и строковыми моделями JavaScript

Проблемы встроенного Date

В стандартном Jav * aScript:

  • месяцы идут от 0 до 11
  • названия дней зависят от локали через строковые API
  • отсутствует типизация календарных сущностей

js-joda решает эти проблемы через:

  • явные перечисления Month и DayOfWeek
  • ISO-совместимую нумерацию
  • отделение модели данных от отображения

Преимущество строгой модели

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

Взаимодействие Month и DayOfWeek в календарных вычислениях

Вычисление следующего месяца

const nextMonth = Month.MARCH.plus(1); // APRIL

Получение следующего дня недели

const nextDay = DayOfWeek.FRIDAY.plus(1); // SATURDAY

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

let day = DayOfWeek.MONDAY;

for (let i = 0; i < 10; i++) {
  day = day.plus(1);
}

Особенности проектирования перечислений

Иммутабельность

Все значения Month и DayOfWeek неизменяемы, что исключает побочные эффекты при передаче между функциями.

Singleton-поведение

Каждое значение существует в единственном экземпляре, что позволяет безопасно сравнивать через ===:

Month.JANUARY === Month.of(1); // true

Интероперабельность с ISO-8601

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

Эта модель унифицирует работу с календарями в разных системах.

Оглавление