Метод toMillis

Метод toMillis() в Luxon используется для преобразования момента времени, представленного объектом DateTime, в числовое значение — количество миллисекунд, прошедших с Unix-эпохи (1 января 1970 года 00:00:00 UTC). Это один из базовых способов перехода от высокоуровневого представления даты и времени к низкоуровневому числовому формату, который активно используется в JavaScript и смежных системах.

Назначение и область применения

Основная задача toMillis() — предоставить унифицированное числовое представление даты, независимое от форматирования, локали и временной зоны. Результат метода:

  • всегда выражается в UTC-ориентированном времени;
  • является типом Number;
  • может использоваться в математических операциях;
  • совместим с Date.now() и new Date().getTime().

Метод особенно полезен при:

  • сохранении временных меток в базах данных;
  • сравнении дат;
  • сериализации времени для API;
  • вычислении разницы между моментами времени.

Синтаксис

DateTime.toMillis()

Метод не принимает аргументов и возвращает число.

Базовое поведение

Объект DateTime в Luxon хранит дату с учётом временной зоны. При вызове toMillis() происходит нормализация к абсолютному моменту времени.

import { DateTime } from "luxon";

const dt = DateTime.local(2026, 1, 1, 12, 0);
const ms = dt.toMillis();

console.log(ms);

Результат — целое число, соответствующее этой дате в миллисекундах UTC.

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

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

import { DateTime } from "luxon";

const ny = DateTime.fromObject(
  { year: 2026, month: 1, day: 1, hour: 12 },
  { zone: "America/New_York" }
);

const tokyo = DateTime.fromObject(
  { year: 2026, month: 1, day: 1, hour: 12 },
  { zone: "Asia/Tokyo" }
);

console.log(ny.toMillis());
console.log(tokyo.toMillis());

Несмотря на одинаковые «локальные» часы, результат будет различаться, поскольку момент времени в UTC не совпадает.

Сравнение с Unix timestamp

Метод toMillis() возвращает расширенный вариант Unix timestamp:

  • Unix timestamp обычно выражается в секундах;
  • toMillis() — в миллисекундах.
const dt = DateTime.local();

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

Luxon также предоставляет метод toSeconds(), но toMillis() остаётся базовым и наиболее точным вариантом.

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

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

const start = DateTime.local().toMillis();

setTimeout(() => {
  const end = DateTime.local().toMillis();
  console.log(end - start);
}, 1000);

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

Проверка валидности объекта

Если DateTime невалиден, результат toMillis() будет NaN.

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

console.log(invalid.isValid); // false
console.log(invalid.toMillis()); // NaN

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

Особенности поведения

1. Независимость от форматирования

Любые настройки вывода (локаль, формат, toLocaleString) не влияют на toMillis().

2. Приведение к абсолютному времени

Метод всегда возвращает значение в UTC-координате времени, даже если исходный объект создан в локальной зоне.

3. Потеря человекочитаемости

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

Типичные сценарии использования

Хранение в базе данных

const record = {
  createdAt: DateTime.now().toMillis()
};

Числовой формат упрощает индексацию и сортировку.

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

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

console.log(a < b);

Работа с API

fetch("/api/events?timestamp=" + DateTime.now().toMillis());

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

Связанные методы

В рамках Luxon метод toMillis() тесно связан с другими способами представления времени:

  • toSeconds() — аналог в секундах;
  • valueOf() — возвращает то же значение, что и toMillis(), при неявном приведении;
  • fromMillis() — обратное преобразование из числа в DateTime.
const dt = DateTime.fromMillis(1700000000000);

Поведение при наследовании и преобразованиях

Объекты DateTime в Luxon не являются примитивами, поэтому при математических операциях происходит неявный вызов valueOf(), который фактически эквивалентен toMillis().

const dt = DateTime.now();

console.log(+dt); // число миллисекунд

Производительность и ограничения

Метод выполняется за константное время и практически не создаёт нагрузки. Основные затраты возникают не в вычислении, а в последующем использовании результата.

Следует учитывать:

  • преобразование в миллисекунды не сохраняет структуру даты;
  • обратное восстановление требует fromMillis();
  • точность ограничена JavaScript Number (до миллисекунд без дробной точности ниже этого уровня).

Практическая роль в архитектуре приложений

toMillis() часто выступает связующим звеном между:

  • объектной моделью Luxon;
  • хранилищами данных;
  • транспортными форматами (JSON);
  • системами очередей и событий.

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

Оглавление