Миграция с версии 3.x на 4.x

Переход с timeago.js 3.x на 4.x — как правило, менее болезненный, чем переход с 2.x на 3.x. Тем не менее существуют изменения, требующие внимания.

Подготовка к миграции

Перед обновлением:

  1. Зафиксировать текущую версию в package.json.
  2. Написать тесты на ключевые вызовы format, render, cancel.
  3. Сделать снэпшоты вывода для используемых локалей.
  4. Запустить тесты — убедиться, что все проходят.
# Зафиксировать текущую версию
cat package.json | grep timeago
# "timeago.js": "^3.0.2"

Проверка несовместимостей

# Установить новую версию в изолированном окружении
npm install timeago.js@4 --dry-run

Проверить CHANGELOG на GitHub:

# Посмотреть список изменений
npm show timeago.js@4 description

Изменение импортов

В 4.x именованные экспорты остались без изменений:

// Остаётся тем же
import { format, render, cancel, register } from 'timeago.js';

Если в проекте использовался дефолтный импорт:

// Устаревший стиль (может не работать)
import timeago from 'timeago.js';
const { format } = timeago;

// Заменить на именованный импорт
import { format } from 'timeago.js';

Изменение путей локалей

Проверить, что пути к локалям актуальны:

// 3.x
import ru from 'timeago.js/esm/lang/ru';

// 4.x — путь остался тем же, но стоит проверить для кастомных/редких локалей
import ru from 'timeago.js/esm/lang/ru'; // OK

Для проверки:

ls node_modules/timeago.js/esm/lang/

Обновление TypeScript типов

// Проверить, что типы подтягиваются из пакета (не из @types)
import type { LocaleFunc, FormatOptions } from 'timeago.js';

const fn: LocaleFunc = (n, i) => ['давно', 'скоро']; // Должно работать

Если был установлен @types/timeago.js — удалить:

npm uninstall @types/timeago.js

Изменение LocaleFunc типа

В 4.x тип LocaleFunc может быть более строгим. Убедиться, что кастомные локали соответствуют сигнатуре:

import type { LocaleFunc } from 'timeago.js';

// Должно компилироваться без ошибок
const myLocale: LocaleFunc = (number, index) => {
  // index от 0 до 14
  return ['давно', 'скоро'];
};

Проверка поведения для граничных случаев

После обновления запустить расширенный набор тестов:

const NOW = new Date('2025-06-01T12:00:00Z').getTime();
jest.setSystemTime(NOW);

const testCases = [
  { input: new Date(NOW),             expected: /только что|just now/ },
  { input: new Date(NOW - 30_000),   expected: /секунд/              },
  { input: new Date(NOW - 60_000),   expected: /минут/               },
  { input: new Date(NOW - 3600_000), expected: /час/                 },
  { input: new Date(NOW - 86400_000),expected: /день/                },
  { input: new Date(NOW + 60_000),   expected: /через/               },
];

testCases.forEach(({ input, expected }) => {
  const result = format(input, 'ru');
  expect(result).toMatch(expected);
});

Обновление package-lock.json

# Обновить timeago.js до 4.x
npm install timeago.js@^4.0.0

# Зафиксировать новый lock-файл
git add package.json package-lock.json
git commit -m "update: timeago.js 3.x → 4.x"

Откат при проблемах

# Вернуться к предыдущей версии
npm install timeago.js@^3.0.2

# Или установить конкретную версию
npm install timeago.js@3.0.2

Чеклист миграции 3.x → 4.x

Оглавление