Работа с Unix timestamp

Unix timestamp представляет собой числовое значение, отражающее количество секунд, прошедших с 1 января 1970 года 00:00:00 UTC. В экосистеме JavaScript и библиотек работы с датами часто встречаются две формы представления времени:

секунды (Unix time) — классический формат Unix
миллисекунды (timestamp в JavaScript) — используется в стандартном объекте Date

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

Представление времени в Day.js

Библиотека Day.js оперирует внутренне миллисекундным представлением времени, аналогичным Date.getTime(). Это означает, что любое значение даты в Day.js хранится как число миллисекунд от Unix epoch.

Ключевая особенность:

Day.js ↔︎ миллисекунды
Unix timestamp ↔︎ секунды

Получение Unix timestamp из Day.js

Метод `.unix()`

Метод .unix() возвращает текущее значение объекта Day.js в секундах.

import dayjs from 'dayjs';

const now = dayjs();

const timestamp = now.unix();
console.log(timestamp);

Результат — целое число:

1716200000

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

возвращает секунды, а не миллисекунды
округляет значение до целого числа
всегда опирается на UTC-epoch

Отличие `.unix()` от `.valueOf()`

Методы часто путаются, но возвращают разные единицы измерения:

const d = dayjs();

console.log(d.unix());    // секунды
console.log(d.valueOf()); // миллисекунды

Фактически:

unix() = Math.floor(ms / 1000)
valueOf() = ms

Создание даты из Unix timestamp

Метод `dayjs.unix()`

Для преобразования Unix timestamp (секунды) в объект Day.js используется статический метод:

const d = dayjs.unix(1716200000);

console.log(d.format());

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

входное значение всегда интерпретируется как секунды
автоматически конвертируется в миллисекунды внутри библиотеки
удобен при работе с API, возвращающими Unix time

Частая ошибка при создании даты

Передача миллисекунд в dayjs.unix() приводит к некорректной дате:

// Ошибка
dayjs.unix(1716200000000);

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

Правильный подход:

dayjs(1716200000000);

или явное преобразование:

dayjs.unix(Math.floor(1716200000000 / 1000));

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

Из Day.js в Unix seconds

const d = dayjs('2025-01-01');

const seconds = d.unix();

Из Day.js в milliseconds timestamp

const ms = d.valueOf();

Из Unix seconds в milliseconds

const ms = dayjs.unix(seconds).valueOf();

Из milliseconds в Unix seconds

const seconds = dayjs(ms).unix();

Работа с API и внешними источниками данных

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

{
  "created_at": 1716200000
}

Обработка:

const createdAt = dayjs.unix(response.created_at);

console.log(createdAt.format('YYYY-MM-DD HH:mm:ss'));

Если API возвращает миллисекунды:

{
  "created_at": 1716200000000
}

Используется прямое создание:

const createdAt = dayjs(response.created_at);

Сравнение Unix timestamp в Day.js и Date

JavaScript Date

const d = new Date();

console.log(d.getTime()); // ms

Day.js

const d = dayjs();

console.log(d.valueOf()); // ms
console.log(d.unix());    // s

Сравнение:

Операция	Date	Day.js
миллисекунды	`getTime()`	`valueOf()`
секунды	нет	`unix()`

Математические операции с Unix timestamp

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

const future = dayjs.unix(1716200000).add(1, 'day').unix();

Вычитание времени

const past = dayjs().subtract(3600, 'second').unix();

Разница между датами

const a = dayjs.unix(1716200000);
const b = dayjs.unix(1716300000);

const diff = b.unix() - a.unix();

Результат выражается в секундах.

Конвертация Unix timestamp в разные форматы

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

dayjs.unix(1716200000).format('DD.MM.YYYY');

ISO строка

dayjs.unix(1716200000).toISOString();

Объект Date

const nativeDate = dayjs.unix(1716200000).toDate();

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

Unix timestamp всегда основан на UTC и не зависит от временной зоны. Day.js сохраняет это поведение:

dayjs.unix(1716200000).utc().format();