fromUnixTime для конвертации

date-fns date-fns

Функция fromUnixTime относится к базовому набору преобразований временных меток и используется для конвертации Unix timestamp (секунды с 1 января 1970 года UTC) в объект Date языка JavaScript. В контексте библиотеки date-fns date-fns она выполняет строго одно назначение — создание экземпляра даты из числового значения секунд, что отличает её от стандартного конструктора Date, ожидающего миллисекунды.

Unix-время представляет собой количество секунд, прошедших с начала эпохи Unix: 1970-01-01T00:00:00Z. Это универсальный формат, широко применяемый в API, базах данных, логах и серверных системах.

В JavaScript базовый объект Date работает с миллисекундами:

new Date(1710000000) // интерпретируется как миллисекунды

Это создаёт проблему несовместимости форматов: Unix timestamp в секундах требует дополнительного преобразования перед использованием в стандартном API.

Назначение fromUnixTime

fromUnixTime устраняет необходимость ручного умножения на 1000.

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

fromUnixTime(unixTime)

Параметры

  • unixTime (number) — количество секунд с Unix-эпохи

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

  • Date — объект даты JavaScript

Базовое использование

import { fromUnixTime } from 'date-fns'

const date = fromUnixTime(1710000000)

console.log(date)
// Date 2024-03-09T...

Функция выполняет эквивалент преобразования:

new Date(unixTime * 1000)

но делает это явно и семантически читаемо.

Сравнение с ручным преобразованием

Ручной подход

const unixTime = 1710000000
const date = new Date(unixTime * 1000)

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

import { fromUnixTime } from 'date-fns'

const date = fromUnixTime(1710000000)

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

Поведение и внутренние особенности

1. Работа только с секундами

Функция строго ожидает секунды. Передача миллисекунд приведёт к некорректной дате:

fromUnixTime(1710000000000)
// интерпретируется как секунды → дата далеко в будущем

2. Отсутствие временной зоны

fromUnixTime возвращает объект Date, который хранит момент времени в UTC-основанной внутренней форме, но отображение зависит от локальной временной зоны окружения.

const date = fromUnixTime(1710000000)

console.log(date.toISOString())

ISO-строка всегда будет в UTC, тогда как toString() зависит от локального часового пояса.

3. Иммутабельность результата

Возвращаемый объект Date является независимым:

const a = fromUnixTime(1710000000)
const b = fromUnixTime(1710000000)

console.log(a === b) // false

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

Работа с API

Многие серверы возвращают время в Unix формате:

{
  "created_at": 1710000000
}

Обработка:

import { fromUnixTime } from 'date-fns'

function mapUser(data) {
  return {
    ...data,
    createdAt: fromUnixTime(data.created_at)
  }
}

Базы данных

В системах, где хранится timestamp в секундах (например, Redis, PostgreSQL при кастомных схемах), функция используется для приведения к объекту Date.

Логи и события

При анализе логов Unix timestamp часто является стандартом:

const logEntry = {
  event: 'login',
  time: 1710000000
}

const readable = fromUnixTime(logEntry.time)

Взаимодействие с другими функциями date-fns

Форматирование

import { fromUnixTime, format } from 'date-fns'

const date = fromUnixTime(1710000000)

const formatted = format(date, 'yyyy-MM-dd HH:mm:ss')

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

import { fromUnixTime, isAfter } from 'date-fns'

const a = fromUnixTime(1710000000)
const b = fromUnixTime(1720000000)

console.log(isAfter(b, a)) // true

Добавление интервалов

import { fromUnixTime, addDays } from 'date-fns'

const base = fromUnixTime(1710000000)
const future = addDays(base, 10)

Ошибки и нестандартные ситуации

Передача миллисекунд

Одна из самых распространённых ошибок:

fromUnixTime(Date.now())

Date.now() возвращает миллисекунды, поэтому результат будет некорректным. Правильный вариант:

fromUnixTime(Math.floor(Date.now() / 1000))

Отрицательные значения

Unix timestamp может быть отрицательным:

fromUnixTime(-1000)

Это приведёт к датам до 1970 года.

Не числовые значения

Если передать строку, произойдёт приведение типа:

fromUnixTime("1710000000")

Но поведение зависит от JavaScript coercion и может приводить к NaN в сложных случаях, поэтому такие входные данные считаются некорректными.

Архитектурная роль в date-fns

Внутри date-fns date-fns функция fromUnixTime относится к категории низкоуровневых конструкторов дат. Она:

  • не зависит от локали
  • не использует форматирование
  • не выполняет валидацию бизнес-логики
  • обеспечивает чистое преобразование типов

Это делает её стабильным строительным блоком для более сложных операций.

Связь с Date API JavaScript

В стандартной библиотеке JavaScript нет прямого аналога fromUnixTime, поэтому эквивалент реализуется вручную:

const date = new Date(unixTime * 1000)

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

Производительность и накладные расходы

Функция является тонкой обёрткой:

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

Поэтому она эквивалентна по производительности нативному new Date(...), но выигрывает в читаемости и стандартизации кода в рамках библиотеки date-fns date-fns

Оглавление