Создание LocalDate

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

Создание текущей даты

Наиболее распространённый способ получения экземпляра LocalDate — использование текущего системного времени.

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

const today = LocalDate.now();

Метод now() использует системные часы и возвращает дату в соответствии с локальной временной зоной среды выполнения.

Вариант с явным указанием часов:

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

const clock = Clock.system(ZoneId.of('Europe/Moscow'));
const today = LocalDate.now(clock);

Использование Clock позволяет детерминировать поведение, что особенно важно для тестирования.

Создание даты через год, месяц и день

Основной способ ручного создания даты — фабричный метод of.

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

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

Параметры строго типизированы:

  • year — целое число (например, 2026)
  • month — число от 1 до 12
  • dayOfMonth — день месяца, зависящий от календаря

При передаче некорректных значений будет выброшено исключение:

LocalDate.of(2026, 2, 30); // ошибка: февраль не содержит 30 дней

Создание через перечисление месяца

Для повышения читаемости можно использовать объект Month.

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

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

Такой способ снижает вероятность ошибок, связанных с порядковыми номерами месяцев.

Создание из дня года

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

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

const date = LocalDate.ofYearDay(2026, 150);

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

Парсинг строки ISO-формата

Стандартный способ преобразования строки в дату — метод parse.

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

const date = LocalDate.parse('2026-05-24');

Поддерживается строго формат ISO-8601:

YYYY-MM-DD

Любое отклонение от формата приводит к ошибке парсинга:

LocalDate.parse('24-05-2026'); // ошибка

Парсинг с пользовательским форматированием

Для нестандартных строк используется DateTimeFormatter.

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

const formatter = DateTimeFormatter.ofPattern('dd.MM.yyyy');

const date = LocalDate.parse('24.05.2026', formatter);

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

Создание из JavaScript Date

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

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

const jsDate = new Date();
const date = LocalDate.from(jsDate);

При этом учитывается локальная временная зона окружения.

Создание из epoch-дней

Внутреннее представление LocalDate может быть выражено через количество дней с эпохи (1970-01-01).

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

const date = LocalDate.ofEpochDay(20000);

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

Работа с календарными ограничениями

LocalDate строго соблюдает правила григорианского календаря. При создании объекта выполняется полная валидация:

  • корректность месяца (1–12)
  • корректность дня в месяце
  • учет високосных лет
  • соответствие диапазонам LocalDate (примерно от -999999999 до +999999999 года)

Примеры ошибок:

LocalDate.of(2026, 0, 10);   // ошибка
LocalDate.of(2026, 13, 10);  // ошибка
LocalDate.of(2026, 4, 31);   // ошибка (апрель 30 дней)

Неизменяемость и безопасность создания

Каждый способ создания LocalDate возвращает новый объект. Изменение существующего экземпляра невозможно.

const d1 = LocalDate.of(2026, 5, 24);
const d2 = d1.plusDays(1); // новый объект

Даже при использовании Clock или парсинга результат всегда остаётся неизменяемым значением.

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

LocalDate всегда абстрагируется от времени суток, но источник времени влияет на результат now():

const date1 = LocalDate.now(ZoneId.of('UTC'));
const date2 = LocalDate.now(ZoneId.of('Asia/Almaty'));

Разные зоны могут давать разные даты при переходе через полночь.

Особенности преобразования и совместимости

При создании LocalDate важно учитывать разницу между типами:

  • LocalDate — только дата
  • LocalDateTime — дата и время без зоны
  • ZonedDateTime — дата, время и зона

Ошибкой является попытка интерпретировать время как дату без явного преобразования.

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

const ldt = LocalDateTime.now();
const date = ldt.toLocalDate();

Типовые сценарии создания

Чаще всего используются следующие паттерны:

LocalDate.now();

LocalDate.of(2026, 1, 1);

LocalDate.parse('2026-12-31');

LocalDate.ofYearDay(2026, 365);

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

Обработка ошибок при создании

При некорректных данных библиотека выбрасывает исключения синхронно. Это позволяет обрабатывать ошибки на этапе создания объекта.

try {
  const date = LocalDate.parse('invalid-date');
} catch (e) {
  // обработка ошибки формата
}

Аналогично для фабричных методов:

try {
  const date = LocalDate.of(2026, 2, 30);
} catch (e) {
  // некорректная календарная дата
}
Оглавление