getUnixTime для Unix-времени

Функция getUnixTime из библиотеки date-fns предназначена для получения Unix-времени в секундах на основе объекта Date. Unix-время представляет собой количество секунд, прошедших с 1 января 1970 года 00:00:00 UTC, что делает его универсальным форматом для хранения и передачи временных меток в системах различного уровня.

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

В JavaScript стандартный объект Date хранит время в миллисекундах, прошедших с той же эпохи. Это создаёт необходимость преобразования между форматами:

  • JavaScript Date → миллисекунды
  • Unix time → секунды

Функция getUnixTime выполняет это преобразование, приводя значение к секундам.

Сигнатура функции

getUnixTime(date)

Параметры:

  • date — экземпляр Date или значение, которое может быть преобразовано в дату

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

  • целое число (Unix timestamp в секундах)

Базовое преобразование

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

Эквивалентное поведение можно представить следующим образом:

Math.floor(date.getTime() / 1000)

Однако использование getUnixTime предпочтительнее, так как функция уже оптимизирована и учитывает особенности реализации date-fns.

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

import { getUnixTime } from 'date-fns';

const date = new Date('2026-01-01T00:00:00Z');
const unixTime = getUnixTime(date);

console.log(unixTime);

Результат будет числом, например:

1767225600

Отличие от Date.now()

Метод Date.now() возвращает текущее время в миллисекундах:

Date.now(); // 1716360000000

getUnixTime возвращает значение в секундах:

getUnixTime(new Date()); // 1716360000

Ключевые различия:

  • Date.now() — миллисекунды
  • getUnixTime() — секунды
  • различие в точности — в 1000 раз

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

Преобразование временных зон

Unix-время не зависит от временной зоны. Любая локальная дата при преобразовании в Unix timestamp нормализуется к UTC.

const localDate = new Date('2026-01-01 12:00:00');
const unix = getUnixTime(localDate);

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

Использование с серверными API

Во многих API Unix timestamp используется как стандарт передачи времени:

const payload = {
  createdAt: getUnixTime(new Date()),
};

Причины популярности:

  • компактность (одно число вместо строки)
  • отсутствие проблем с форматами даты
  • простота сравнения

Сравнение дат через Unix time

Unix-время удобно использовать для сравнений:

const a = getUnixTime(new Date('2026-01-01'));
const b = getUnixTime(new Date('2026-01-02'));

console.log(a < b); // true

Сравнение чисел быстрее и надёжнее, чем сравнение объектов Date.

Работа с округлением

Так как Unix time измеряется в секундах, дробная часть миллисекунд отбрасывается:

const date = new Date('2026-01-01T00:00:00.999Z');
getUnixTime(date); // 1767225600

Миллисекунды игнорируются, поскольку происходит усечение вниз.

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

Если передать недопустимую дату:

getUnixTime(new Date('invalid'));

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

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

const date = new Date('invalid');

if (!isNaN(date)) {
  const unix = getUnixTime(date);
}

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

Функция принимает не только Date, но и значения, которые могут быть преобразованы в дату:

getUnixTime('2026-01-01T00:00:00Z');

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

Обратное преобразование

Для преобразования Unix timestamp обратно в Date используется связанная функция:

import { fromUnixTime } from 'date-fns';

const date = fromUnixTime(1767225600);

Связка getUnixTime ↔︎ fromUnixTime формирует симметричную пару преобразований:

  • Date → Unix time → Date

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

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

const record = {
  id: 1,
  timestamp: getUnixTime(new Date()),
};

Сортировка событий

events.sort((a, b) => a.timestamp - b.timestamp);

Ограничение времени действия

const now = getUnixTime(new Date());
const expires = getUnixTime(expiryDate);

if (now > expires) {
  // срок действия истёк
}

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

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

По сути, её роль сводится к:

  • извлечению времени из Date
  • конвертации миллисекунд в секунды
  • возврату числового значения

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

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

Ошибка: путаница секунд и миллисекунд

Date.now(); // миллисекунды
getUnixTime(new Date()); // секунды

Смешивание этих значений приводит к ошибкам в логике времени.

Ошибка: двойное деление

Math.floor(getUnixTime(date) / 1000);

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

Ошибка: использование без учёта UTC

Хотя Unix time независим от часового пояса, исходный Date может быть неправильно интерпретирован при создании из строки без указания зоны.

Роль в экосистеме date-fns

date-fns предоставляет функциональный подход к работе с датами, где каждая операция представлена отдельной чистой функцией. getUnixTime вписывается в эту модель как утилита преобразования, не изменяющая исходный объект.

В отличие от объектно-ориентированных подходов, здесь отсутствует состояние:

  • нет мутаций Date
  • нет скрытых преобразований
  • нет глобальных настроек

Каждая операция прозрачна и предсказуема.

Совместимость с другими функциями

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

  • format — для отображения даты
  • addDays, subDays — для вычислений
  • compareAsc — для сортировки
  • fromUnixTime — для обратного преобразования

Так формируется цепочка операций над датами, где Unix time выступает как промежуточный универсальный формат.

Оглавление