Luxon

Luxon представляет собой современную библиотеку для работы с датой и временем в JavaScript, разработанную с учётом ограничений встроенного объекта Date и потребностей сложных приложений, требующих корректной работы с часовыми поясами, локалями и календарными операциями.

В основе Luxon лежит модель неизменяемых (immutable) объектов. Каждый объект даты и времени не изменяется после создания — любые операции возвращают новый экземпляр.

Ключевые принципы:

  • неизменяемость данных
  • строгая работа с временными зонами
  • явное управление локалями
  • разделение понятий DateTime, Duration и Interval
  • использование Intl API браузера и Node.js

Такой подход снижает количество скрытых ошибок, характерных для мутируемых библиотек дат.

Основные сущности библиотеки

DateTime

DateTime — центральная сущность Luxon. Она объединяет дату, время, часовой пояс и локаль в одном объекте.

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

import { DateTime } from "luxon";

const now = DateTime.now();

Создание из конкретных компонентов:

const dt = DateTime.local(2026, 5, 23, 14, 30);

Создание в UTC:

const utc = DateTime.utc(2026, 5, 23, 14, 30);

Особенность: все операции возвращают новый DateTime, не изменяя исходный.

Duration

Duration описывает промежутки времени: дни, часы, минуты, секунды.

import { Duration } from "luxon";

const dur = Duration.fromObject({ hours: 2, minutes: 30 });

Duration используется для арифметики времени и преобразований.

Interval

Interval описывает временной диапазон между двумя моментами.

import { DateTime, Interval } from "luxon";

const start = DateTime.local(2026, 1, 1);
const end = DateTime.local(2026, 12, 31);

const interval = Interval.fromDateTimes(start, end);

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

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

const ny = DateTime.now().setZone("America/New_York");
const tokyo = DateTime.now().setZone("Asia/Tokyo");

Важные особенности:

  • поддержка IANA time zone database
  • автоматическая конвертация времени
  • сохранение локального момента времени при смене зоны (при необходимости)

Конвертация между зонами:

const utc = DateTime.utc();
const local = utc.setZone("Europe/Berlin");

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

Luxon предоставляет гибкую систему форматирования через toFormat.

const dt = DateTime.now();

dt.toFormat("yyyy-MM-dd HH:mm");

Примеры токенов:

  • yyyy — год
  • MM — месяц
  • dd — день
  • HH — часы (24-часовой формат)
  • mm — минуты

Форматирование с локалью:

dt.setLocale("ru").toLocaleString(DateTime.DATE_FULL);

Парсинг данных

Luxon умеет создавать даты из строк и ISO-форматов.

ISO парсинг

const dt = DateTime.fromISO("2026-05-23T14:30:00");

Кастомный формат

const dt = DateTime.fromFormat("23-05-2026 14:30", "dd-MM-yyyy HH:mm");

Unix timestamp

const dt = DateTime.fromSeconds(1716460200);

Арифметика дат

Luxon позволяет выполнять операции сложения и вычитания времени.

Добавление времени

const dt = DateTime.now().plus({ days: 3, hours: 5 });

Вычитание

const dt = DateTime.now().minus({ months: 1 });

Обе операции возвращают новый объект.

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

Сравнение осуществляется через методы startOf, endOf, diff и обычные операторы сравнения после приведения к числу.

Разница между датами

const a = DateTime.local(2026, 1, 1);
const b = DateTime.local(2026, 2, 1);

const diff = b.diff(a, "days").days;

Начало и конец временных единиц

Luxon позволяет нормализовать дату до начала или конца периода.

const dt = DateTime.now();

dt.startOf("day");
dt.endOf("month");

Поддерживаемые единицы:

  • year
  • month
  • week
  • day
  • hour
  • minute

Локализация

Luxon использует встроенный Intl API.

DateTime.now().setLocale("fr").toLocaleString(DateTime.DATE_FULL);

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

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

Luxon поддерживает корректную работу с различными календарными сценариями через локали и Intl.

Особое внимание уделяется:

  • неделям (ISO недели)
  • началу недели (зависит от локали)
  • форматам отображения дат

Преобразования и сериализация

ISO строка

DateTime.now().toISO();

JSON

const json = DateTime.now().toJSON();

Unix timestamp

DateTime.now().toMillis();

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

Каждая операция возвращает новый объект:

const dt1 = DateTime.now();
const dt2 = dt1.plus({ days: 1 });

dt1 === dt2; // false

Это предотвращает:

  • случайные изменения состояния
  • побочные эффекты
  • ошибки в асинхронных сценариях

Работа с валидностью данных

Luxon отслеживает корректность даты.

const dt = DateTime.fromISO("invalid-date");

dt.isValid; // false
dt.invalidReason;

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

Взаимодействие с JavaScript Date

Luxon может конвертироваться в стандартный Date:

const jsDate = DateTime.now().toJSDate();

И обратно:

const dt = DateTime.fromJSDate(new Date());

Производительность и внутреннее устройство

Luxon оптимизирован для:

  • минимизации мутаций
  • использования нативных API
  • кеширования форматов через Intl
  • быстрого создания объектов DateTime

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

Типичные сценарии применения

Планирование задач

const deadline = DateTime.now().plus({ days: 7 });

Таймзоны в глобальных системах

const event = DateTime.fromObject(
  { year: 2026, month: 5, day: 23 },
  { zone: "UTC" }
);

Расчёт интервалов

const interval = Interval.fromDateTimes(
  DateTime.local(2026, 1, 1),
  DateTime.local(2026, 6, 1)
);

interval.length("days");

Ограничения модели

Несмотря на функциональность, Luxon имеет особенности:

  • зависимость от Intl API
  • больший размер по сравнению с лёгкими библиотеками
  • необходимость явного управления зонами
  • отсутствие мутируемого API (что может усложнять миграцию из старых решений)
Оглавление