Создание и инициализация

js-joda — библиотека для работы с датой и временем в JavaScript, основанная на концепциях java.time из Java 8. Главная цель библиотеки — предоставить строгую, предсказуемую и безопасную модель времени без типичных проблем стандартного объекта Date.

Ключевые особенности:

• неизменяемые объекты;
• разделение даты, времени и часовых поясов;
• поддержка ISO-8601;
• отсутствие скрытых преобразований;
• высокая точность вычислений;
• удобная работа с временными интервалами.

Библиотека состоит из нескольких основных типов:

Тип	Назначение
LocalDate	Только дата
LocalTime	Только время
LocalDateTime	Дата и время без часового пояса
ZonedDateTime	Дата, время и временная зона
Instant	Точка времени UTC
Duration	Длительность
Period	Период между датами

---

Установка библиотеки

Установка через npm:

npm install @js-joda/core

Подключение:

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

Для ES-модулей:

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

---

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

LocalDate хранит только календарную дату:

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

console.log(date.toString());

Результат:

2026-05-24

Параметры метода of

LocalDate.of(year, month, day)

Параметр	Описание
year	Год
month	Месяц
day	День месяца

---

Использование перечисления Month

Месяц можно задавать через enum Month:

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

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

console.log(date.toString());

Это делает код более читаемым и исключает ошибки при указании номера месяца.

---

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

Метод now() возвращает текущую дату:

const today = LocalDate.now();

console.log(today.toString());

Дата определяется на основе системного времени.

---

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

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

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

console.log(date.toString());

Формат ISO-8601 поддерживается по умолчанию.

---

Создание LocalTime

LocalTime представляет только время без даты.

Создание через of

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

console.log(time.toString());

Результат:

14:30:15

---

Миллисекунды и наносекунды

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

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

console.log(time.toString());

Результат:

10:15:30.500

Параметры:

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

---

Текущее время

const now = LocalTime.now();

console.log(now.toString());

---

Парсинг времени

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

console.log(time.toString());

---

Создание LocalDateTime

LocalDateTime объединяет дату и время.

Создание через of

const dateTime = LocalDateTime.of(
    2026,
    5,
    24,
    18,
    30,
    45
);

console.log(dateTime.toString());

Результат:

2026-05-24T18:30:45

---

Создание из LocalDate и LocalTime

const date = LocalDate.of(2026, 5, 24);
const time = LocalTime.of(12, 15);

const dateTime = LocalDateTime.of(date, time);

console.log(dateTime.toString());

---

Текущая дата и время

const current = LocalDateTime.now();

console.log(current.toString());

---

Парсинг LocalDateTime

const value = LocalDateTime.parse(
    '2026-05-24T21:15:30'
);

console.log(value.toString());

---

Создание Instant

Instant представляет абсолютную временную точку UTC.

Создание текущего момента

const instant = Instant.now();

console.log(instant.toString());

Пример результата:

2026-05-24T10:22:15.123Z

Суффикс Z означает UTC.

---

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

const instant = Instant.parse(
    '2026-05-24T10:15:30Z'
);

console.log(instant.toString());

---

Создание ZonedDateTime

ZonedDateTime хранит:

• дату;
• время;
• часовую зону.

Создание через now

const zoned = ZonedDateTime.now();

console.log(zoned.toString());

---

Указание временной зоны

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

console.log(tokyo.toString());

---

Создание ZonedDateTime из компонентов

const zoned = ZonedDateTime.of(
    2026,
    5,
    24,
    15,
    45,
    30,
    0,
    ZoneId.of('Europe/Berlin')
);

console.log(zoned.toString());

---

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

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

npm install @js-joda/timezone

Подключение:

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

После подключения становятся доступны IANA-зоны:

ZoneId.of('Europe/Moscow');
ZoneId.of('America/New_York');
ZoneId.of('Asia/Almaty');

---

Создание Duration

Duration описывает длительность времени.

Создание в часах

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

const duration = Duration.ofHours(5);

console.log(duration.toString());

Результат:

PT5H

---

Создание Duration в минутах

const duration = Duration.ofMinutes(90);

console.log(duration.toString());

---

Duration из секунд

const duration = Duration.ofSeconds(45);

console.log(duration.toString());

---

Создание Period

Period хранит календарный период.

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

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

console.log(period.toString());

Результат:

P1Y2M15D

Параметры:

Period.of(years, months, days)

---

Инициализация через parse

Большинство объектов поддерживают статический метод parse.

Примеры

LocalDate.parse('2026-05-24');

LocalTime.parse('10:15:30');

LocalDateTime.parse(
    '2026-05-24T10:15:30'
);

Instant.parse(
    '2026-05-24T10:15:30Z'
);

---

Инициализация из стандартного Date

Проблема объекта Date

Стандартный Date:

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

js-joda позволяет безопасно конвертировать значения.

---

Преобразование Date → Instant

const jsDate = new Date();

const instant = Instant.ofEpochMilli(
    jsDate.getTime()
);

console.log(instant.toString());

---

Преобразование Instant → Date

const instant = Instant.now();

const jsDate = new Date(
    instant.toEpochMilli()
);

console.log(jsDate);

---

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

Epoch milliseconds

const instant = Instant.ofEpochMilli(
    1760000000000
);

console.log(instant.toString());

---

Epoch seconds

const instant = Instant.ofEpochSecond(
    1760000000
);

console.log(instant.toString());

---

Инициализация через фабричные методы

В библиотеке активно используются статические фабрики.

Основные методы:

Метод	Назначение
of()	Создание из компонентов
now()	Текущее время
parse()	Создание из строки
from()	Создание из другого temporal-объекта

---

Использование метода from

const dateTime = LocalDateTime.parse(
    '2026-05-24T12:30:00'
);

const date = LocalDate.from(dateTime);

console.log(date.toString());

---

Создание объектов с nanos precision

const instant = Instant.ofEpochSecond(
    1000,
    500000000
);

console.log(instant.toString());

Второй параметр — наносекунды.

---

Неизменяемость объектов

Все типы js-joda immutable.

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

const changed = date.plusDays(5);

console.log(date.toString());
console.log(changed.toString());

Результат:

2026-05-24
2026-05-29

Исходный объект не изменяется.

---

Создание минимальных и максимальных значений

Минимальное время

const min = LocalTime.MIN;

Максимальное время

const max = LocalTime.MAX;

Начало дня

const start = LocalTime.MIDNIGHT;

Полдень

const noon = LocalTime.NOON;

---

Создание даты начала эпохи

const epoch = LocalDate.ofEpochDay(0);

console.log(epoch.toString());

Результат:

1970-01-01

---

Создание времени из секунд дня

const time = LocalTime.ofSecondOfDay(
    3600
);

console.log(time.toString());

Результат:

01:00

---

Создание времени из наносекунд дня

const time = LocalTime.ofNanoOfDay(
    5000000000
);

console.log(time.toString());

---

Создание даты из номера дня года

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

console.log(date.toString());

---

Ошибки и исключения при создании объектов

Некорректные значения вызывают исключения.

Неверный месяц

LocalDate.of(2026, 15, 10);

Ошибка:

DateTimeException

---

Неверный день

LocalDate.of(2026, 2, 30);

---

Ошибочный формат строки

LocalDate.parse('24-05-2026');

---

Проверка корректности данных

Часто используется try/catch.

try {

    const date = LocalDate.parse(
        '2026-15-99'
    );

} catch (error) {

    console.log(error.message);

}

---

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

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

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

const clock = Clock.systemUTC();

const now = Instant.now(clock);

console.log(now.toString());

---

Фиксированное время

Полезно для тестирования.

const fixedClock = Clock.fixed(
    Instant.parse(
        '2026-05-24T10:00:00Z'
    ),
    ZoneId.UTC
);

const now = Instant.now(fixedClock);

console.log(now.toString());

---

Системные часы

UTC

Clock.systemUTC();

Системная таймзона

Clock.systemDefaultZone();

---

Создание объектов через цепочки

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

const dateTime = date.atTime(18, 30);

console.log(dateTime.toString());

---

Создание ZonedDateTime из LocalDateTime

const local = LocalDateTime.of(
    2026,
    5,
    24,
    12,
    0
);

const zoned = local.atZone(
    ZoneId.of('Europe/Paris')
);

console.log(zoned.toString());

---

ISO-8601 как основной стандарт

Все базовые методы ориентированы на ISO-8601:

YYYY-MM-DD
YYYY-MM-DDTHH:mm:ss
YYYY-MM-DDTHH:mm:ssZ

Примеры:

2026-05-24
2026-05-24T18:30:00
2026-05-24T18:30:00Z

---

Практический пример полной инициализации

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

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

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

const time = LocalTime.of(
    14,
    45,
    30
);

const dateTime = LocalDateTime.of(
    date,
    time
);

const zoned = dateTime.atZone(
    ZoneId.of('Asia/Almaty')
);

console.log(zoned.toString());

Результат:

2026-05-24T14:45:30+05:00[Asia/Almaty]