Адаптация кода

Работа с датами и временем в JavaScript традиционно связана с множеством скрытых сложностей: различия временных зон, особенности Date, отсутствие неизменяемости объектов, неоднозначность парсинга строк и различия между окружениями Node.js и браузера. Библиотека Luxon решает часть этих проблем за счёт строгой модели работы с датами, опоры на Intl и явного управления временными зонами.

Документация: Luxon documentation Исходный код: Luxon GitHub

Переход от встроенного Date к DateTime

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

Преобразование создания даты

// До Luxon
const now = new Date();

// Luxon
import { DateTime } from "luxon";

const now = DateTime.now();

Важное отличие заключается в том, что DateTime.now() возвращает объект с привязанной временной зоной окружения.

Адаптация форматов хранения данных

В большинстве систем данные дат приходят из API, базы данных или очередей сообщений. Эти форматы необходимо адаптировать к модели Luxon.

ISO 8601 как основной формат обмена

const dt = DateTime.fromISO("2026-05-23T10:15:30Z");

ISO-строки становятся основным контрактом между сервисами. В отличие от new Date("..."), парсинг Luxon является предсказуемым и не зависит от реализации движка.

Unix timestamp

const dt = DateTime.fromMillis(1716450000000);
const dtSeconds = DateTime.fromSeconds(1716450000);

При адаптации кода важно разделять миллисекунды и секунды, поскольку в интеграциях с внешними API часто используется второй формат.

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

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

const dt = DateTime.fromISO("2026-05-23T10:00:00", { zone: "utc" });
const local = dt.setZone("Asia/Almaty");

Встроенный Date хранит время в UTC, но не предоставляет прозрачного механизма работы с зонами. Luxon делает зону частью состояния объекта.

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

const utcTime = DateTime.utc();
const newYorkTime = utcTime.setZone("America/New_York");
const tokyoTime = utcTime.setZone("Asia/Tokyo");

При адаптации кода важно исключить ручные вычисления смещений (+3, -5), поскольку они не учитывают переход на летнее время.

Адаптация форматирования вывода

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

const dt = DateTime.now();

dt.toISO();
dt.toRFC2822();
dt.toLocaleString(DateTime.DATETIME_MED);

Использование предустановленных форматов снижает необходимость в ручных шаблонах.

Замена Moment.js и адаптация архитектуры

Во многих кодовых базах Luxon внедряется как замена Moment.js. Важно учитывать, что API не полностью совместим.

Сравнение подходов

Moment.js:

moment().add(1, "day").format("YYYY-MM-DD");

Luxon:

DateTime.now().plus({ days: 1 }).toFormat("yyyy-MM-dd");

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

Адаптация цепочек операций

Luxon строится вокруг неизменяемости объектов. Каждая операция возвращает новый экземпляр.

const base = DateTime.now();
const result = base
  .plus({ days: 2 })
  .minus({ hours: 3 })
  .setZone("UTC");

При адаптации кода важно исключить паттерны мутации:

// Неприменимо для Luxon
date.setDate(date.getDate() + 1);

Адаптация работы с JSON и API

Объекты DateTime не сериализуются напрямую через JSON.stringify. Это требует явной адаптации.

Сериализация

const dt = DateTime.now();

const payload = {
  timestamp: dt.toISO()
};

Десериализация

const dt = DateTime.fromISO(payload.timestamp);

В архитектурах с REST и GraphQL это становится стандартным способом передачи времени.

Адаптация к базе данных

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

  • ISO строки
  • Unix timestamp
  • специализированные форматы (PostgreSQL TIMESTAMP WITH TIME ZONE)

PostgreSQL совместимость

const dt = DateTime.fromSQL("2026-05-23 12:00:00");

const sql = dt.toSQL();

При адаптации кода важно фиксировать единый формат на уровне репозитория доступа к данным.

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

Работа с интервалами становится более строгой через Interval.

import { Interval } from "luxon";

const start = DateTime.now();
const end = start.plus({ hours: 5 });

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

Проверка пересечений

interval.contains(DateTime.now());

В старом коде такие проверки часто выполнялись через сравнение чисел времени.

Адаптация парсинга пользовательского ввода

Пользовательский ввод даты является одной из наиболее нестабильных частей системы.

const dt = DateTime.fromFormat("23-05-2026", "dd-MM-yyyy");

При адаптации важно избегать new Date("23-05-2026"), так как результат зависит от окружения.

Адаптация серверного и клиентского окружения

Luxon использует Intl, поэтому поведение зависит от поддержки ICU в среде исполнения.

Node.js

В Node.js необходимо учитывать полную или облегчённую ICU-конфигурацию.

const dt = DateTime.now().setLocale("ru");
dt.toLocaleString();

Браузер

В браузере поведение более стабильно, но зависит от версии движка.

Адаптация работы с календарями и локалями

const dt = DateTime.now().setLocale("ru");

Локализация влияет на:

  • названия месяцев
  • форматирование дат
  • порядок компонентов даты

В отличие от ручной реализации, Luxon использует системные стандарты Intl.

Адаптация legacy-кода с Date

При миграции больших кодовых баз используется поэтапная стратегия: обёртки и адаптеры.

function toDateTime(date) {
  return DateTime.fromJSDate(date);
}

function toJSDate(dt) {
  return dt.toJSDate();
}

Это позволяет сосуществовать старому и новому коду.

Адаптация работы с часовыми поясами в бизнес-логике

В системах бронирования, финансов и логистики временная зона становится частью доменной модели.

const bookingTime = DateTime.fromObject(
  { year: 2026, month: 5, day: 23, hour: 10 },
  { zone: "Asia/Almaty" }
);

При переносе логики из Date важно избегать предположения, что время всегда локальное или всегда UTC.

Адаптация обработки DST (летнего времени)

Luxon учитывает переходы на летнее время через IANA time zone database.

const dt = DateTime.fromISO("2026-03-29T02:30", {
  zone: "Europe/Berlin"
});

В старых реализациях такие моменты часто приводили к некорректным или несуществующим значениям времени.

Адаптация вычислительных операций с датами

const base = DateTime.now();

const nextWeek = base.plus({ weeks: 1 });
const lastMonth = base.minus({ months: 1 });

В отличие от ручных вычислений через миллисекунды, Luxon учитывает календарную специфику.

Адаптация тестирования

При тестировании временных функций необходимо фиксировать “сейчас”.

const fixed = DateTime.fromISO("2026-01-01T00:00:00Z");

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

Адаптация архитектуры модулей времени

При внедрении Luxon часто выделяется отдельный слой:

  • time-service
  • date-factory
  • timezone-adapter
export function nowUTC() {
  return DateTime.utc();
}

Это снижает связанность бизнес-логики с конкретной библиотекой.

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

В системах событийной обработки (Kafka, WebSocket) время приходит как строка или число.

function parseEvent(event) {
  return {
    ...event,
    time: DateTime.fromMillis(event.time)
  };
}

Адаптация ошибок парсинга

Luxon возвращает валидируемые объекты.

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

dt.isValid; // false
dt.invalidReason;

Это заменяет исключения, характерные для Date.parse.

Оглавление