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

Работа с датами и временем в Luxon строится вокруг универсального объекта DateTime, который служит центральной точкой преобразований. Любые внешние представления времени — строки, числовые метки, нативные объекты JavaScript, JSON-структуры — приводятся к DateTime, а затем экспортируются в нужный формат. Архитектура библиотеки ориентирована на симметрию входных и выходных преобразований, что упрощает построение цепочек сериализации и десериализации.

Документация Luxon: Luxon documentation

Входные форматы и создание DateTime

ISO-строки

Наиболее распространённый формат — ISO 8601. Он поддерживается напрямую и считается базовым стандартом для обмена данными.

import { DateTime } from "luxon";

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

ISO-строка может содержать временную зону:

DateTime.fromISO("2026-05-23T14:30:00+06:00");

При отсутствии зоны используется локальная зона выполнения среды.

Unix-время (timestamp)

Поддерживаются миллисекунды и секунды. Различие критично, поскольку большинство API используют миллисекунды.

DateTime.fromMillis(1716472200000);
DateTime.fromSeconds(1716472200);

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

Нативный объект JavaScript Date

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

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

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

Luxon поддерживает пользовательские шаблоны через fromFormat.

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

Форматирование строго соответствует токенам Luxon и не использует синтаксис Moment.js.

RFC и локализованные форматы

DateTime.fromRFC2822("Sat, 23 May 2026 14:30:00 +0600");
DateTime.fromHTTP("Sat, 23 May 2026 14:30:00 GMT");

Такие форматы применяются при обработке HTTP-заголовков и email-данных.

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

ISO-строки

Основной способ сериализации:

dt.toISO();
dt.toISODate();
dt.toISOTime();

Разделение позволяет получать только дату или время без лишних компонентов.

Unix timestamp

dt.toMillis();
dt.toSeconds();

Используется при сохранении данных в БД или передаче во внешние системы.

Нативный Date

dt.toJSDate();

Преобразование необходимо при работе с API браузера, сторонними библиотеками и DOM-инструментами.

JSON-сериализация

Метод toJSON автоматически вызывает ISO-представление:

JSON.stringify(dt);

Результат:

"2026-05-23T14:30:00.000+06:00"

Это поведение используется в структурах REST API и WebSocket-сообщениях.

Форматирование строк (экспорт в человекочитаемые форматы)

toFormat

Гибкий механизм преобразования в строку:

dt.toFormat("dd LLLL yyyy, HH:mm");

Используется система токенов:

  • dd — день месяца
  • LLLL — полное название месяца
  • yyyy — год
  • HH:mm — время

Локализованное форматирование

dt.toLocaleString(DateTime.DATETIME_MED);

Доступны предустановленные пресеты:

  • DATETIME_FULL
  • DATETIME_MED
  • DATE_SHORT
  • TIME_SIMPLE

Локализация зависит от текущей языковой настройки.

Обратные преобразования и восстановление объектов

fromObject → toObject

Luxon поддерживает объектное представление:

const obj = dt.toObject();
const restored = DateTime.fromObject(obj);

Структура:

{
  year: 2026,
  month: 5,
  day: 23,
  hour: 14,
  minute: 30
}

Используется при сериализации сложных структур без строкового формата.

Работа с временными зонами при конвертации

Переключение зоны без изменения момента времени

dt.setZone("Europe/Paris");

Семантика: момент времени остаётся тем же, изменяется интерпретация.

Пересчёт времени в новую зону

dt.setZone("Europe/Paris", { keepLocalTime: true });

В этом режиме локальное время сохраняется, но меняется абсолютная интерпретация.

Нормализация данных при конвертации

Приведение к UTC

dt.toUTC();

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

Приведение к локальному времени

dt.toLocal();

Применяется при отображении данных пользователю.

Потери точности при преобразованиях

Некоторые форматы не сохраняют всю информацию:

  • toISODate() — теряет время
  • toISOTime() — теряет дату
  • toFormat() — зависит от шаблона
  • toObject() — может не включать секунды/миллисекунды при их отсутствии

Понимание этих ограничений важно при сериализации для долговременного хранения.

Конвертация через эпоху как универсальный мост

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

const millis = dt.toMillis();
const dt2 = DateTime.fromMillis(millis);

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

Детерминированные преобразования в цепочках

Luxon допускает последовательные операции:

const result = DateTime
  .fromISO("2026-05-23T14:30:00")
  .setZone("UTC")
  .toFormat("yyyy-LL-dd HH:mm");

Каждый шаг возвращает новый DateTime, не изменяя исходный объект, что исключает побочные эффекты при конвертации.

Сериализация для API и межсервисного обмена

Рекомендуемая схема передачи

  • вход: ISO 8601 (fromISO)
  • хранение: millis (toMillis)
  • обмен: ISO (toISO)
  • отображение: toLocaleString или toFormat

Такая модель минимизирует неоднозначность и упрощает интеграцию между системами с разными часовыми поясами и стандартами времени.

Оглавление