Factory methods

В библиотеке Js-joda создание объектов временных типов построено вокруг набора статических фабричных методов. Конструкторы напрямую не используются: все экземпляры LocalDate, LocalTime, Instant, ZonedDateTime и других типов создаются через строго определённые точки входа. Такой подход обеспечивает неизменяемость, консистентность и контроль над внутренними представлениями даты и времени.

Общая концепция фабричных методов

Фабричные методы в Js-joda выполняют роль централизованного механизма создания объектов. Они заменяют конструкторы и позволяют:

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

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

Методы создания текущего времени

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

now()

Метод now() присутствует во всех основных временных типах:

  • LocalDate.now()
  • LocalTime.now()
  • LocalDateTime.now()
  • ZonedDateTime.now()
  • Instant.now()

Он возвращает текущее значение в зависимости от типа:

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

const date = LocalDate.now();
const time = LocalTime.now();
const dateTime = ZonedDateTime.now();

Особенность заключается в том, что now() учитывает системное время и, при необходимости, переданную временную зону:

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

const zone = ZoneId.of('Europe/Moscow');
const zoned = ZonedDateTime.now(zone);

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

Методы создания из компонентов

Для большинства типов Js-joda предусмотрены методы of(), которые позволяют явно задать все компоненты значения.

LocalDate.of(year, month, day)

Создаёт дату из трёх числовых параметров:

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

const date = LocalDate.of(2025, 5, 10);

Параметры строго валидируются. Неверные значения (например, 31 февраля) приводят к ошибке.

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

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

const date = LocalDate.of(2025, Month.MAY, 10);

LocalTime.of(hour, minute, second?, nano?)

Создание времени с точностью до наносекунд:

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

const time = LocalTime.of(14, 30);
const precise = LocalTime.of(14, 30, 15, 123000000);

Если необязательные параметры не переданы, они принимают значение 0.

Валидация диапазонов жёсткая:

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

LocalDateTime.of(...)

Комбинированное создание даты и времени:

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

const dt = LocalDateTime.of(2025, 5, 10, 14, 30);

Также поддерживаются расширенные формы:

const dt = LocalDateTime.of(2025, 5, 10, 14, 30, 15);
const dtFull = LocalDateTime.of(2025, 5, 10, 14, 30, 15, 123000000);

ZonedDateTime.of(...)

Создание временной метки с зоной:

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

const zone = ZoneId.of('Asia/Tokyo');

const zdt = ZonedDateTime.of(2025, 5, 10, 14, 30, 0, 0, zone);

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

Методы создания из мгновений и эпохи

Instant.ofEpochSecond() и Instant.ofEpochMilli()

Тип Instant представляет момент времени в UTC. Фабричные методы позволяют создавать его из эпохи Unix:

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

const i1 = Instant.ofEpochSecond(1_700_000_000);
const i2 = Instant.ofEpochMilli(1_700_000_000_000);

При необходимости можно добавить наносекунды:

const i = Instant.ofEpochSecond(1_700_000_000, 500000000);

Создание через разбор строк

Фабричные методы parse() отвечают за преобразование текстового представления в объект времени.

LocalDate.parse()

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

const date = LocalDate.parse('2025-05-10');

Формат строго соответствует ISO-8601.

LocalTime.parse()

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

const time = LocalTime.parse('14:30:15');

Поддерживаются доли секунды:

const time = LocalTime.parse('14:30:15.123');

LocalDateTime.parse()

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

const dt = LocalDateTime.parse('2025-05-10T14:30:15');

Разделитель даты и времени — T, как в ISO-формате.

Instant.parse()

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

const instant = Instant.parse('2025-05-10T14:30:15Z');

Обязательное указание зоны Z или смещения.

Парсинг с кастомным форматированием

Хотя базовые parse() работают с ISO-форматом, Js-joda поддерживает использование DateTimeFormatter:

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

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

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

Фабричный метод parse() в этом случае принимает дополнительный аргумент, определяющий правила разбора строки.

Методы создания на основе других объектов

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

from()

Используется для преобразования между совместимыми типами:

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

const zdt = ZonedDateTime.now();
const ldt = LocalDateTime.from(zdt);

Метод извлекает доступные компоненты и формирует новый объект без временной зоны.

Нормализация входных данных внутри фабричных методов

Фабричные методы Js-joda выполняют скрытую нормализацию данных:

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

Например, при создании даты:

LocalDate.of(2025, 2, 30);

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

Перегрузка фабричных методов

В Js-joda отсутствует классическая перегрузка функций, но фабричные методы реализуют её через вариативность параметров.

Пример LocalTime.of:

  • of(hour, minute)
  • of(hour, minute, second)
  • of(hour, minute, second, nano)

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

Роль фабричных методов в архитектуре библиотеки

Фабричные методы являются ключевым элементом архитектуры Js-joda:

  • все классы неизменяемы (immutable);
  • отсутствует публичный доступ к конструкторам;
  • гарантируется единый контроль создания объектов;
  • упрощается кэширование и оптимизация внутренних представлений;
  • исключается возможность создания некорректных состояний.

Каждый вызов of(), now(), parse() или from() возвращает полностью валидный объект, готовый к использованию без дополнительной проверки.

Связь фабричных методов с типовой системой времени

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

  • LocalDate — дата без времени
  • LocalTime — время без даты
  • LocalDateTime — комбинация даты и времени
  • ZonedDateTime — дата, время и зона
  • Instant — абсолютный момент времени

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

Оглавление