getTime для получения timestamp

Функция getTime в библиотеке date-fns предназначена для извлечения числового timestamp (временной метки) из объекта Date. Результатом является количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 UTC, что соответствует стандарту Unix Epoch в JavaScript.

В отличие от нативного метода Date.prototype.getTime, функция из date-fns предоставляет функциональный стиль, удобный для композиции и работы в иммутабельных цепочках преобразований дат.

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

getTime(date)

Параметры:

  • date — объект Date, из которого извлекается timestamp

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

  • number — количество миллисекунд с Unix Epoch
  • NaN — если передан невалидный объект Date

Базовый принцип работы

Timestamp представляет собой универсальную форму представления времени, независимую от часовых поясов и локализации. Независимо от формата исходной даты, результат всегда приводится к UTC-основанной шкале времени.

import { getTime } from 'date-fns';

const date = new Date('2024-01-01T00:00:00Z');
const timestamp = getTime(date);

console.log(timestamp);
// 1704067200000

Эквивалентность с нативным JavaScript

Функция getTime из date-fns по сути повторяет поведение встроенного метода:

const date = new Date('2024-01-01T00:00:00Z');

date.getTime(); // нативный способ

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

getTime(date) === date.getTime(); // true

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

Работа с текущим временем

Для получения текущего timestamp можно передать new Date():

import { getTime } from 'date-fns';

const now = getTime(new Date());

Однако в прикладной разработке чаще используется более прямой вариант:

Date.now();

Несмотря на это, getTime сохраняет значение в цепочках преобразований.

Использование в цепочках преобразований

Одно из ключевых применений — интеграция в функциональные пайплайны:

import { pipe } from 'fp-ts/function';
import { parseISO, addDays, getTime } from 'date-fns';

const result = pipe(
  '2024-01-01T00:00:00Z',
  parseISO,
  addDays(7),
  getTime
);

console.log(result);
// timestamp даты + 7 дней

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

Обработка невалидных дат

Если в getTime передаётся некорректный объект Date, результатом становится NaN.

import { getTime } from 'date-fns';

const invalidDate = new Date('invalid');

console.log(getTime(invalidDate));
// NaN

Это поведение соответствует спецификации Jav * aScript: Invalid Date имеет внутреннее значение времени NaN.

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

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

Timestamp используется для быстрого сравнения:

import { getTime } from 'date-fns';

const a = getTime(new Date('2024-01-01'));
const b = getTime(new Date('2024-01-10'));

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

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

Кэширование и ключи

Timestamp часто применяется как ключ для кэш-структур:

import { getTime } from 'date-fns';

const cache = new Map();

const date = new Date('2024-01-01');
cache.set(getTime(date), { value: 'data' });

Сериализация

Timestamp удобен для передачи через API:

import { getTime } from 'date-fns';

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

JSON.stringify(payload);

Числовой формат легче сериализуется и занимает меньше места, чем ISO-строка.

Отличия от Date.now

Метод Источник Входные данные Результат
Date.now() нативный нет текущий timestamp
getTime(date) date-fns объект Date timestamp указанной даты

Ключевое различие заключается в том, что getTime работает с переданным объектом даты, а не с текущим временем.

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

Функция ожидает именно объект Date. Передача строки или числа приводит к неявным преобразованиям через new Date(...) только если это сделано вручную до вызова:

import { getTime } from 'date-fns';

getTime('2024-01-01'); 
// некорректное использование, результат NaN

Корректный вариант:

getTime(new Date('2024-01-01'));

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

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

import { getTime } from 'date-fns';

const localDate = new Date('2024-01-01T00:00:00+03:00');
const utcDate = new Date('2024-01-01T00:00:00Z');

console.log(getTime(localDate) === getTime(utcDate));
// false, так как разные моменты времени

Функция фиксирует абсолютный момент времени, а не его локальное представление.

Использование в фильтрации диапазонов

Timestamp часто применяется для фильтрации дат:

import { getTime } from 'date-fns';

const events = [
  { date: new Date('2024-01-01') },
  { date: new Date('2024-02-01') },
  { date: new Date('2024-03-01') }
];

const start = getTime(new Date('2024-01-15'));
const end = getTime(new Date('2024-03-01'));

const filtered = events.filter(e => {
  const t = getTime(e.date);
  return t >= start && t <= end;
});

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

Операция получения timestamp является константной по сложности и фактически равна вызову внутреннего метода объекта Date. Использование date-fns в данном случае не даёт ускорения, но обеспечивает:

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

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

getTime часто используется как финальный шаг после преобразований:

import { parseISO, subDays, getTime } from 'date-fns';

const timestamp = getTime(
  subDays(parseISO('2024-05-10'), 5)
);

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

Особенности возврата значения NaN

Возврат NaN возникает в случаях:

  • передан new Date('invalid')
  • объект Date повреждён или содержит некорректное внутреннее значение
  • результат предыдущих операций привёл к невалидной дате
const d = new Date('invalid');

Number.isNaN(getTime(d));
// true

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

Оглавление