Метод format

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

Сигнатура

format(
  date: Date | string | number,
  locale?: string,
  opts?: { relativeDate?: Date | number }
): string

Параметры

date — обязательный аргумент, входная дата. Поддерживаемые типы:

  • Date — JavaScript-объект даты
  • number — timestamp в миллисекундах
  • string — строка даты, совместимая с new Date()

locale — необязательная строка-идентификатор локали. Если не указана, используется 'en_US'.

opts — необязательный объект с настройками: * relativeDate — опорная дата вместо Date.now()

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

Строка в формате выбранной локали:

format(Date.now() - 60000);       // → "1 minute ago"
format(Date.now() - 60000, 'ru'); // → "1 минуту назад"

Примеры вызова

С объектом Date:

import { format } from 'timeago.js';

const date = new Date('2025-05-26T10:00:00Z');
format(date, 'ru');
// → "4 часа назад"

С timestamp:

format(1716720000000, 'ru');

С ISO-строкой:

format('2025-05-26T10:00:00Z', 'ru');

С опорной датой:

const base = new Date('2025-06-01T00:00:00Z');
format('2025-05-26T00:00:00Z', 'ru', { relativeDate: base });
// → "6 дней назад"

Внутренняя логика

При вызове format(input, locale, opts):

  1. Входное значение конвертируется в timestamp: new Date(input).getTime().
  2. Вычисляется разница: relativeDate.getTime() - inputTimestamp (или Date.now() - inputTimestamp).
  3. Определяется направление: если разница отрицательна — будущее.
  4. По абсолютному значению разницы выбирается индекс из таблицы порогов.
  5. Вычисляется number — количество единиц (делением на divisor).
  6. Вызывается функция локали: localeFunc(number, index).
  7. Из возвращённого массива выбирается нужный элемент ([0] для прошлого, [1] для будущего).
  8. Плейсхолдер %s заменяется на number.

Работа без явной локали

format(Date.now() - 3600000);
// → "1 hour ago"

По умолчанию используется встроенная en_US.

Несколько форматов в одном вызове

const date = '2025-05-26T08:00:00Z';

const labels = {
  ru: format(date, 'ru'),
  en: format(date, 'en_US'),
  de: format(date, 'de'),
};

Функция не сохраняет состояния между вызовами.

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

const posts = [
  { id: 1, createdAt: '2025-05-26T10:00:00Z' },
  { id: 2, createdAt: '2025-05-25T08:00:00Z' },
];

const enriched = posts.map(p => ({
  ...p,
  timeLabel: format(p.createdAt, 'ru'),
}));

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

const message = `Пост опубликован ${format(post.createdAt, 'ru')}`;

Чистота функции

format не изменяет никаких внешних структур:

  • не обновляет DOM;
  • не создаёт таймеры;
  • не модифицирует переданные аргументы;
  • не имеет глобального состояния (кроме использования реестра локалей для чтения).

Это делает format безопасной для серверного рендеринга, тестирования и мемоизации.

Мемоизация

При частых вызовах с одинаковыми аргументами:

import { format } from 'timeago.js';

const cache = new Map();

function memoFormat(date, locale = 'ru') {
  const key   = `${new Date(date).getTime()}-${locale}`;
  const now   = Date.now();

  if (cache.has(key)) {
    const { result, timestamp } = cache.get(key);
    if (now - timestamp < 30000) return result; // кэш 30 секунд
  }

  const result = format(date, locale);
  cache.set(key, { result, timestamp: now });
  return result;
}

TypeScript-типизация

import { format } from 'timeago.js';

const result: string = format(new Date(), 'ru');

Функция всегда возвращает string. Входной тип — Date | string | number.

Поведение при некорректном вводе

Ввод Поведение
null Ошибка или “NaN years ago”
undefined Ошибка
"invalid" Некорректная строка из локали
NaN Некорректный результат
new Date(0) Корректно, далёкое прошлое
-Infinity Некорректный результат

Рекомендуется валидировать входные данные перед передачей в format.

Оглавление