История изменений библиотеки

timeago.js прошёл путь от минималистичной утилиты до зрелой библиотеки с поддержкой TypeScript, ESM и расширенной системой локализации. Понимание истории помогает принимать правильные решения при миграции и обновлении зависимостей.

Начало: версии 1.x

Первоначальная версия timeago.js вышла около 2016 года как замена jQuery-плагинам для отображения относительного времени. Основные характеристики:

  • Только функция форматирования — нет render с автообновлением.
  • Ограниченное количество встроенных локалей.
  • Нет поддержки TypeScript.
  • Модуль в формате CommonJS (require/exports).
  • Минимальный размер — основной критерий разработки.

Версия 1.x была простым модулем без зависимостей, работавшим как в Node.js, так и в браузере.

Версия 2.x: автообновление и локали

Версия 2.x добавила ключевые функции:

  • Функция render для автоматического обновления DOM-элементов.
  • Функция cancel для остановки таймеров.
  • Значительное расширение библиотеки локалей (добавлены десятки языков).
  • Функция register для кастомных локалей.
  • Поддержка relativeDate в опциях форматирования.

Это сформировало основной API, который сохранился до сегодня.

Версия 3.x: TypeScript и ESM

Версия 3.x ввела:

  • Встроенные TypeScript деклараций (.d.ts).
  • ESM-сборку (timeago.js/esm).
  • Улучшенный треешейкинг — неиспользуемые локали не попадают в бандл.
  • Рефакторинг кода локалей в отдельные файлы.
# ESM импорт локали (появился в 3.x)
import ru from 'timeago.js/esm/lang/ru';

Версия 4.x: текущая

Версия 4.x — последний мажорный релиз на момент написания. Основные изменения:

  • Улучшена TypeScript типизация.
  • Добавлены/обновлены локали для ряда языков.
  • Оптимизирована производительность внутренних таймеров.
  • Исправлены проблемы с Safari.
npm install timeago.js@latest  # Устанавливает актуальную 4.x

Сравнение версий API

Функция 1.x 2.x 3.x 4.x
format ✓ ✓ ✓ ✓
render ✗ ✓ ✓ ✓
cancel ✗ ✓ ✓ ✓
register ✗ ✓ ✓ ✓
TypeScript типы ✗ ✗ ✓ ✓
ESM экспорты ✗ ✗ ✓ ✓
relativeDate ✗ ✓ ✓ ✓

Изменение системы локалей

В версиях 1.x и 2.x локали встраивались в основной бандл:

// Старый способ — всё в одном файле
const timeago = new TimeAgo('ru');

Начиная с 3.x — каждая локаль в отдельном файле:

import ru from 'timeago.js/esm/lang/ru';
register('ru', ru);

Это позволило сократить размер основного бандла при использовании только одной-двух локалей.

Изменение формата LocaleFunc

В ранних версиях функция локали могла иметь разные сигнатуры. Начиная с 3.x — стандартизирована:

// Текущий стандарт (3.x, 4.x)
type LocaleFunc = (number: number, index: number) => [string, string];

CHANGELOG: что проверять перед обновлением

При обновлении мажорной версии timeago.js проверить:

  1. Изменился ли формат LocaleFunc — кастомные локали требуют адаптации.
  2. Добавлены ли breaking changes в API format/render/cancel.
  3. Изменились ли пути ESM импортов локалей.
  4. Обновились ли TypeScript типы — могут потребоваться изменения в строгих проектах.

Версии зависимостей в package.json

{
  "dependencies": {
    "timeago.js": "^4.0.0"
  }
}

^4.0.0 — автоматически устанавливает новые минорные версии (4.x.x), но не мажорные. Это безопасная стратегия для production.

Альтернативные ответвления

В экосистеме существуют fork-и и вдохновлённые библиотеки:

  • react-timeago — React-компонент на основе timeago.js.
  • timeago-react — альтернативная React-обёртка.
  • vue-timeago — Vue-компонент.
  • angular-timeago — Angular-директива.

Эти библиотеки следуют за релизами timeago.js с задержкой, поэтому важно проверять совместимость версий.

Оглавление