Метод toSeconds

Метод toSeconds() в библиотеке Luxon используется для получения Unix-времени в секундах из объекта DateTime. Он преобразует внутреннее представление даты и времени в числовое значение, отражающее количество секунд, прошедших с 1 января 1970 года 00:00:00 UTC.

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

Сигнатура и поведение

Метод вызывается у экземпляра DateTime:

dateTime.toSeconds()

Возвращаемое значение:

  • тип: number
  • единицы измерения: секунды
  • база отсчёта: Unix epoch (1970-01-01T00:00:00Z)
  • точность: до миллисекунд (дробная часть числа)

При этом важно учитывать, что результат зависит от текущей временной зоны объекта DateTime, если он не приведён к UTC.

Принцип работы внутри Luxon

Объект DateTime в Luxon хранит время в виде набора полей (год, месяц, день, час, минута, секунда, миллисекунда) и привязку к временной зоне. При вызове toSeconds() выполняется:

  1. Преобразование локального времени в абсолютное (если задана временная зона).
  2. Расчёт разницы между текущей датой и Unix epoch.
  3. Перевод результата в секунды.
  4. Добавление дробной части, основанной на миллисекундах.

Фактически метод является удобной обёрткой над внутренним вычислением timestamp.

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

Получение текущего Unix-времени

import { DateTime } from "luxon";

const now = DateTime.now();
const timestamp = now.toSeconds();

console.log(timestamp);

Результат:

1716451234.582

Число содержит дробную часть, отражающую миллисекунды.

Преобразование конкретной даты

const dt = DateTime.fromISO("2025-01-01T00:00:00");
const seconds = dt.toSeconds();

console.log(seconds);

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

Использование с UTC

Для получения стабильного результата независимо от окружения используется UTC:

const dt = DateTime.fromISO("2025-01-01T00:00:00", { zone: "utc" });
console.log(dt.toSeconds());

В этом случае значение будет одинаковым во всех системах.

Отличие от toMillis

Метод toSeconds() часто сравнивается с toMillis(), так как оба возвращают Unix-время, но в разных единицах.

  • toSeconds() — секунды (с дробной частью)
  • toMillis() — миллисекунды (целое число)

Эквивалентность:

DateTime.now().toMillis() / 1000 === DateTime.now().toSeconds()

Разница проявляется в точности представления и удобстве интеграции с различными API.

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

Хранение временных меток

Unix-время в секундах используется в базах данных, где требуется компактное хранение:

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

Преимущество заключается в универсальности формата и лёгкости сортировки.

Сравнение времени

Сравнение временных точек через секунды упрощает арифметику:

const a = DateTime.fromISO("2025-01-01").toSeconds();
const b = DateTime.fromISO("2025-01-02").toSeconds();

console.log(b - a); // 86400

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

Интерфейсы с внешними API

Многие API принимают Unix timestamp именно в секундах:

const payload = {
  timestamp: DateTime.now().toSeconds()
};

Это снижает необходимость ручного преобразования форматов.

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

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

  • дробная часть представляет миллисекунды / 1000
  • точность выше миллисекунд не поддерживается
  • при математических операциях возможны стандартные особенности floating point

Пример:

const t = DateTime.now().toSeconds();
console.log(t.toFixed(3));

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

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

const dtLocal = DateTime.fromISO("2025-01-01T00:00:00");
const dtUTC = DateTime.fromISO("2025-01-01T00:00:00", { zone: "utc" });

console.log(dtLocal.toSeconds());
console.log(dtUTC.toSeconds());

Разница может быть значительной, если локальная зона отличается от UTC.

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

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

DateTime.fromISO("2025-01-01").toSeconds();

Такой код может давать разные результаты в разных средах.

Сравнение строк вместо чисел

DateTime.now().toSeconds() > "1716451234"

Строковое сравнение приводит к некорректной логике. Всегда использовать числовой тип.

Повторный вызов now()

DateTime.now().toSeconds() - DateTime.now().toSeconds()

Результат может быть отрицательным или равным нулю из-за различий во времени вызова.

Внутренняя совместимость с JavaScript Date

Метод toSeconds() фактически эквивалентен:

DateTime.now().toMillis() / 1000

и опирается на Date.getTime() внутри JavaScript Date API.

Практика оптимизации

При интенсивной работе с временными метками предпочтительно:

  • вычислять DateTime.now() один раз
  • переиспользовать значение
  • избегать повторных преобразований
const now = DateTime.now().toSeconds();

const a = now;
const b = now + 3600;

Роль в экосистеме Luxon

toSeconds() является одним из базовых методов экспорта времени, наряду с:

  • toMillis()
  • toISO()
  • toJSDate()

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

Оглавление