Метод fromMillis и fromSeconds

Метод DateTime.fromMillis в библиотеке Luxon используется для создания объекта даты и времени на основе Unix-времени, выраженного в миллисекундах. Это один из базовых способов преобразования числовых временных меток в полноценные объекты DateTime, которые поддерживают работу с часовыми поясами, форматированием и арифметикой времени.

Базовый синтаксис

DateTime.fromMillis(milliseconds, options)
  • milliseconds — число, представляющее количество миллисекунд с 1 января 1970 года (UTC).
  • options — объект конфигурации, позволяющий управлять зоной времени, локалью и другими параметрами.

Простейший пример

import { DateTime } from "luxon";

const dt = DateTime.fromMillis(1716451200000);

console.log(dt.toISO());

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

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

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

const dtUTC = DateTime.fromMillis(1716451200000, { zone: "utc" });
const dtNY = DateTime.fromMillis(1716451200000, { zone: "America/New_York" });

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

Важные особенности интерпретации

  • входное значение всегда считается временем Unix Epoch в миллисекундах;
  • Luxon не выполняет преобразование локального времени в UTC автоматически;
  • значение всегда трактуется как абсолютный момент времени.

Это означает, что ошибки чаще всего возникают не из-за Luxon, а из-за неправильного источника данных.

Параметры options

Объект options может содержать:

  • zone — временная зона;
  • locale — локаль форматирования;
  • setZone — сохранять ли указанную зону при преобразованиях.

Пример:

const dt = DateTime.fromMillis(1716451200000, {
  zone: "Europe/Paris",
  locale: "fr"
});

DateTime.fromSeconds: создание даты из секунд Unix-времени

Метод DateTime.fromSeconds аналогичен fromMillis, но принимает значение в секундах. Он используется в системах, где временные метки хранятся в формате Unix Timestamp (seconds since epoch), например в API, JWT и базах данных.

Синтаксис

DateTime.fromSeconds(seconds, options)
  • seconds — количество секунд с Unix epoch;
  • options — те же параметры, что и в fromMillis.

Пример использования

import { DateTime } from "luxon";

const dt = DateTime.fromSeconds(1716451200);

console.log(dt.toISO());

Отличие от fromMillis

Ключевая разница заключается в масштабе времени:

  • fromMillis работает с миллисекундами;
  • fromSeconds работает с секундами.

Эта разница критична при работе с внешними API.

Пример ошибки при неправильном выборе метода

DateTime.fromSeconds(1716451200000); // неверно
DateTime.fromMillis(1716451200000);   // корректно

В первом случае число интерпретируется как секунды, что приводит к дате далеко в будущем.

Сравнение fromMillis и fromSeconds

Единицы измерения

  • fromMillis — высокая точность, используется в браузерах и Node.js таймстемпах;
  • fromSeconds — стандарт Unix-систем и большинства API.

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

Разница в производительности отсутствует на практике, так как оба метода являются обёртками над одним и тем же внутренним механизмом Luxon.

Области применения

fromMillis чаще используется:

  • в JavaScript Date.now();
  • в событиях браузера;
  • в системах логирования с высокой точностью.

fromSeconds чаще используется:

  • в REST API;
  • в JWT (iat, exp);
  • в Unix-базированных базах данных.

Работа с текущим временем и преобразование

Хотя оба метода создают объект из фиксированной метки времени, они часто используются в связке с текущим временем.

const nowMillis = Date.now();
const now = DateTime.fromMillis(nowMillis);

или

const nowSeconds = Math.floor(Date.now() / 1000);
const now = DateTime.fromSeconds(nowSeconds);

Разница в точности становится важной при сравнении времени событий.

Потеря точности при переходе между форматами

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

const ms = Date.now();
const seconds = Math.floor(ms / 1000);

const a = DateTime.fromMillis(ms);
const b = DateTime.fromSeconds(seconds);

a и b будут отличаться максимум на 999 миллисекунд.

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

Оба метода возвращают полноценный объект DateTime, который можно форматировать:

const dt = DateTime.fromMillis(1716451200000);

console.log(dt.toFormat("yyyy-MM-dd HH:mm:ss"));
console.log(dt.toLocaleString(DateTime.DATETIME_FULL));

Форматирование не зависит от того, из какого источника создан объект.

Часовые пояса и неизменяемость времени

Luxon работает по принципу неизменяемости объектов. Это означает, что:

const dt = DateTime.fromSeconds(1716451200);
const shifted = dt.setZone("Asia/Tokyo");

Исходный объект не изменяется, создаётся новый экземпляр с другой зоной.

Это особенно важно при цепочках преобразований времени.

Типичные ошибки при использовании

Перепутанные единицы измерения

Самая частая ошибка:

DateTime.fromSeconds(Date.now()); // неверно

Двойное деление на 1000

DateTime.fromSeconds(Date.now() / 1000); // корректно только при отсутствии округления

Игнорирование временной зоны

DateTime.fromMillis(timestamp);

Без явного указания зоны результат зависит от окружения, что может приводить к несогласованности между серверами и клиентами.

Взаимное преобразование между форматами

Luxon позволяет легко переходить между миллисекундами и секундами:

const dt = DateTime.fromMillis(1716451200000);

const seconds = Math.floor(dt.toMillis() / 1000);
const millis = dt.toMillis();

Методы toMillis() и toSeconds() обеспечивают обратное преобразование без потери структуры объекта.

Работа с внешними API

При интеграции с API часто требуется нормализация входных данных:

function parseTimestamp(ts) {
  if (ts > 1e12) {
    return DateTime.fromMillis(ts);
  }
  return DateTime.fromSeconds(ts);
}

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

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

В event-driven архитектуре временные метки часто приходят в разных форматах:

const eventTime = DateTime.fromSeconds(event.timestamp).setZone("utc");

Явное приведение к UTC обеспечивает корректную синхронизацию событий между сервисами.

Влияние локали на представление времени

Локаль не влияет на внутреннее значение времени, но изменяет отображение:

const dt = DateTime.fromMillis(1716451200000, {
  locale: "ru"
});

console.log(dt.toLocaleString());

Это важно при разработке интерфейсов, где одна и та же дата должна отображаться по-разному для пользователей из разных регионов.

Поведение при некорректных значениях

Если передано некорректное значение:

DateTime.fromMillis("abc");

Luxon возвращает объект с состоянием Invalid DateTime. Проверка осуществляется через:

dt.isValid

Цепочки преобразований

Методы fromMillis и fromSeconds часто являются отправной точкой для цепочек операций:

const dt = DateTime
  .fromSeconds(1716451200)
  .setZone("Europe/Berlin")
  .plus({ days: 3 })
  .toISO();

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

Применение в кэшировании и дедупликации

Unix-время часто используется как ключ:

const key = DateTime.fromMillis(ts).toFormat("yyyyMMddHHmm");

или

const key = DateTime.fromSeconds(ts).startOf("minute").toISO();

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

Оглавление