Полный список классов

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

const { LocalDate } = require('@js-joda/core');

const date = LocalDate.now();

console.log(date.toString()); // 2026-05-25

Создание даты

const date1 = LocalDate.of(2025, 3, 15);

const date2 = LocalDate.parse('2025-03-15');

Получение компонентов даты

console.log(date1.year());       // 2025
console.log(date1.monthValue()); // 3
console.log(date1.dayOfMonth()); // 15

Изменение даты

Объекты Js-joda неизменяемы. Любая операция возвращает новый экземпляр.

const nextWeek = date1.plusWeeks(1);

const previousMonth = date1.minusMonths(1);

Сравнение дат

const a = LocalDate.parse('2025-01-01');
const b = LocalDate.parse('2025-12-31');

console.log(a.isBefore(b)); // true
console.log(a.isAfter(b));  // false
console.log(a.equals(b));   // false

Работа с концом месяца

const end = LocalDate
    .of(2025, 2, 1)
    .withDayOfMonth(28);

---

LocalTime

LocalTime хранит время без даты и без часового пояса.

const { LocalTime } = require('@js-joda/core');

const time = LocalTime.now();

console.log(time.toString());

Создание времени

const time1 = LocalTime.of(14, 30);

const time2 = LocalTime.parse('18:45:10');

Получение частей времени

console.log(time2.hour());
console.log(time2.minute());
console.log(time2.second());

Арифметика времени

const result = time1
    .plusHours(2)
    .minusMinutes(15);

console.log(result.toString());

Наносекунды

Js-joda поддерживает точность до наносекунд.

const nano = LocalTime.of(10, 15, 30, 500000000);

console.log(nano.nano());

---

LocalDateTime

LocalDateTime объединяет дату и время без информации о часовом поясе.

const { LocalDateTime } = require('@js-joda/core');

const dt = LocalDateTime.now();

Создание объекта

const dt1 = LocalDateTime.of(
    2025,
    6,
    10,
    12,
    45,
    30
);

Парсинг строки

const dt2 = LocalDateTime.parse(
    '2025-06-10T12:45:30'
);

Изменение даты и времени

const changed = dt2
    .plusDays(5)
    .minusHours(3);

Преобразование в LocalDate и LocalTime

const date = dt2.toLocalDate();

const time = dt2.toLocalTime();

---

ZonedDateTime

ZonedDateTime хранит дату, время и часовой пояс.

const {
    ZonedDateTime,
    ZoneId
} = require('@js-joda/core');

Создание объекта

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

Работа с часовыми поясами

const tokyo = ZonedDateTime.now(
    ZoneId.of('Asia/Tokyo')
);

console.log(tokyo.zone().id());

Конвертация между часовыми поясами

const london = tokyo.withZoneSameInstant(
    ZoneId.of('Europe/London')
);

Важность ZonedDateTime

Класс особенно важен для:

• серверных приложений;
• международных систем;
• расписаний;
• логирования;
• работы с API;
• хранения времени событий.

---

OffsetDateTime

OffsetDateTime содержит дату, время и смещение UTC.

const {
    OffsetDateTime,
    ZoneOffset
} = require('@js-joda/core');

const offset = OffsetDateTime.now(
    ZoneOffset.UTC
);

Разница между OffsetDateTime и ZonedDateTime

Класс	Содержит
ZonedDateTime	полноценный часовой пояс
OffsetDateTime	только UTC-смещение

Пример смещения:

const date = OffsetDateTime.of(
    2025,
    1,
    10,
    15,
    0,
    0,
    0,
    ZoneOffset.ofHours(3)
);

---

OffsetTime

OffsetTime представляет время со смещением UTC, но без даты.

const {
    OffsetTime,
    ZoneOffset
} = require('@js-joda/core');

const time = OffsetTime.of(
    12,
    30,
    0,
    0,
    ZoneOffset.UTC
);

---

Instant

Instant хранит момент времени в UTC.

const { Instant } = require('@js-joda/core');

const instant = Instant.now();

Особенности Instant

• всегда UTC;
• не зависит от локали;
• используется для timestamp;
• удобен для хранения времени в БД.

Создание Instant

const i1 = Instant.parse(
    '2025-01-01T00:00:00Z'
);

Epoch milliseconds

const epoch = instant.toEpochMilli();

---

Duration

Duration хранит временной интервал в секундах и наносекундах.

const {
    Duration,
    LocalTime
} = require('@js-joda/core');

const start = LocalTime.of(10, 0);
const end = LocalTime.of(12, 30);

const duration = Duration.between(start, end);

console.log(duration.toHours()); // 2

Создание Duration

const d1 = Duration.ofHours(5);

const d2 = Duration.ofMinutes(90);

Арифметика

const total = d1.plusMinutes(30);

---

Period

Period хранит период в годах, месяцах и днях.

const { Period } = require('@js-joda/core');

const period = Period.of(1, 2, 15);

Компоненты периода

console.log(period.years());
console.log(period.months());
console.log(period.days());

Разница между Duration и Period

Класс	Используется для
Duration	часы, минуты, секунды
Period	годы, месяцы, дни

---

Year

Year представляет отдельный год.

const { Year } = require('@js-joda/core');

const year = Year.of(2025);

Проверка високосного года

console.log(year.isLeap());

---

YearMonth

YearMonth хранит комбинацию года и месяца.

const { YearMonth } = require('@js-joda/core');

const ym = YearMonth.of(2025, 7);

Количество дней в месяце

console.log(ym.lengthOfMonth());

---

MonthDay

MonthDay хранит месяц и день без года.

const { MonthDay } = require('@js-joda/core');

const birthday = MonthDay.of(5, 20);

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

Подходит для:

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

---

ZoneId

ZoneId представляет идентификатор часового пояса.

const { ZoneId } = require('@js-joda/core');

const zone = ZoneId.of('Europe/Berlin');

Популярные зоны

ZoneId.of('UTC');

ZoneId.of('Asia/Tokyo');

ZoneId.of('America/New_York');

---

ZoneOffset

ZoneOffset хранит фиксированное смещение UTC.

const { ZoneOffset } = require('@js-joda/core');

const offset = ZoneOffset.ofHours(3);

Создание сложных смещений

ZoneOffset.of('+05:30');

---

Month

Month — перечисление месяцев.

const { Month } = require('@js-joda/core');

console.log(Month.JANUARY);

Получение числового значения

console.log(
    Month.AUGUST.value()
);

Операции

const next = Month.MARCH.plus(2);

---

DayOfWeek

DayOfWeek представляет дни недели.

const { DayOfWeek } = require('@js-joda/core');

console.log(DayOfWeek.MONDAY);

Значения

День	Значение
MONDAY	1
TUESDAY	2
WEDNESDAY	3
THURSDAY	4
FRIDAY	5
SATURDAY	6
SUNDAY	7

---

DateTimeFormatter

DateTimeFormatter используется для форматирования и парсинга.

const {
    DateTimeFormatter,
    LocalDate
} = require('@js-joda/core');

Форматирование

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

const date = LocalDate.now();

console.log(
    date.format(formatter)
);

Парсинг

const parsed = LocalDate.parse(
    '25.12.2025',
    formatter
);

Основные шаблоны

Шаблон	Значение
yyyy	год
MM	месяц
dd	день
HH	часы
mm	минуты
ss	секунды

---

ChronoUnit

ChronoUnit содержит единицы времени.

const {
    ChronoUnit,
    LocalDate
} = require('@js-joda/core');

const start = LocalDate.of(2025, 1, 1);

const end = LocalDate.of(2025, 12, 31);

const days = ChronoUnit.DAYS.between(
    start,
    end
);

Основные единицы

• NANOS
• MICROS
• MILLIS
• SECONDS
• MINUTES
• HOURS
• DAYS
• WEEKS
• MONTHS
• YEARS

---

TemporalAdjusters

TemporalAdjusters содержит готовые корректировки дат.

const {
    TemporalAdjusters,
    LocalDate,
    DayOfWeek
} = require('@js-joda/core');

Последний день месяца

const result = LocalDate.now()
    .with(
        TemporalAdjusters.lastDayOfMonth()
    );

Следующий понедельник

const nextMonday = LocalDate.now()
    .with(
        TemporalAdjusters.next(
            DayOfWeek.MONDAY
        )
    );

---

Clock

Clock используется как источник текущего времени.

const { Clock } = require('@js-joda/core');

const clock = Clock.systemUTC();

Виды часов

Clock.systemDefaultZone();

Clock.systemUTC();

Clock.fixed(
    Instant.now(),
    ZoneOffset.UTC
);

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

Clock.fixed() позволяет создавать предсказуемые тесты.

const fixedClock = Clock.fixed(
    Instant.parse('2025-01-01T00:00:00Z'),
    ZoneOffset.UTC
);

---

DecimalStyle

DecimalStyle управляет локализованными символами форматирования.

const { DecimalStyle } = require('@js-joda/core');

Используется редко, в основном при сложной локализации.

---

ResolverStyle

ResolverStyle определяет строгость парсинга.

const {
    ResolverStyle,
    DateTimeFormatter
} = require('@js-joda/core');

Режимы

Режим	Описание
STRICT	строгая проверка
SMART	интеллектуальный режим
LENIENT	мягкий режим

---

SignStyle

SignStyle управляет отображением знаков числа.

const { SignStyle } = require('@js-joda/core');

Используется внутри форматтеров даты и времени.

---

ValueRange

ValueRange описывает допустимый диапазон значений.

const { ValueRange } = require('@js-joda/core');

const range = ValueRange.of(1, 12);

Проверка значения

console.log(
    range.isValidValue(5)
);

---

UnsupportedTemporalTypeException

Исключение, возникающее при неподдерживаемой временной операции.

try {
    LocalDate.now().hour();
} catch (e) {
    console.log(e);
}

---

DateTimeException

Базовое исключение библиотеки.

try {
    LocalDate.of(2025, 15, 1);
} catch (e) {
    console.log(e);
}

---

NullPointerException

Выбрасывается при передаче null там, где это запрещено.

try {
    LocalDate.parse(null);
} catch (e) {
    console.log(e);
}

---

ArithmeticException

Возникает при арифметическом переполнении.

try {
    LocalDate.now().plusYears(999999999);
} catch (e) {
    console.log(e);
}

---

Основные интерфейсы

Temporal

Базовый интерфейс временных объектов.

TemporalAccessor

Интерфейс для чтения временных данных.

TemporalAdjuster

Интерфейс корректировки даты и времени.

TemporalAmount

Интерфейс для периодов и длительностей.

TemporalUnit

Интерфейс единиц времени.

TemporalField

Интерфейс полей даты и времени.

---

Архитектура Js-joda

Библиотека построена вокруг нескольких принципов:

Неизменяемость

Все объекты immutable.

const a = LocalDate.now();

const b = a.plusDays(1);

console.log(a !== b);

Потокобезопасность

Объекты безопасны для многопоточного использования.

ISO-8601 как стандарт

По умолчанию библиотека работает по ISO-8601.

Отказ от Date

Js-joda не использует внутреннюю модель Date, что устраняет множество проблем Jav * aScript:

• ошибки timezone;
• автоматические преобразования;
• неточности;
• мутации объектов;
• неоднозначный парсинг строк.

---

Дополнительные модули

@js-joda/timezone

Добавляет поддержку IANA timezone database.

require('@js-joda/timezone');

@js-joda/locale

Добавляет локализацию форматирования.

@js-joda/extra

Содержит дополнительные классы и расширения.

---

Типичные комбинации классов

Хранение даты рождения

LocalDate

Хранение timestamp

Instant

Международное событие

ZonedDateTime

Интервал выполнения задачи

Duration

Календарный период

Period

Время без даты

LocalTime

Год и месяц отчёта

YearMonth

Ежегодный праздник

MonthDay