Обработка различных форматов входных данных

Функция format в timeago.js принимает несколько типов входных данных для представления даты. Это позволяет использовать библиотеку с любыми источниками данных без дополнительного преобразования.

Поддерживаемые типы входных данных

Тип	Пример
`number`	`1716720000000` (timestamp в мс)
`Date`	`new Date('2025-05-26')`
`string`	`'2025-05-26T10:00:00Z'`

Числовой timestamp (миллисекунды)

Наиболее точный и однозначный формат:

import { format } from 'timeago.js';

// Текущее время минус 10 минут
const ts = Date.now() - 1000 * 60 * 10;

format(ts);
// → "10 minutes ago"

Unix timestamp в секундах необходимо конвертировать в миллисекунды:

const unixSeconds = 1716720000;

format(unixSeconds * 1000);

Объект Date

const date = new Date('2025-05-26T08:00:00Z');

format(date, 'ru');
// → "4 часа назад"

Объект Date — наиболее типобезопасный вариант при работе с TypeScript. Именно этот формат рекомендуется использовать в строго типизированных проектах.

Строковая дата

Строки передаются напрямую в конструктор Date через new Date(str). Это означает, что поддерживаются все форматы, которые корректно парсятся браузером или Node.js.

ISO 8601:

format('2025-05-26T10:00:00Z');
format('2025-05-26T10:00:00+03:00');
format('2025-05-26');

RFC 2822:

format('Mon, 26 May 2025 10:00:00 +0000');

Поведение при разных строковых форматах

Формат строки	Поведение
`'2025-05-26T10:00:00Z'`	Корректно, UTC
`'2025-05-26T10:00:00'`	Зависит от реализации браузера
`'2025-05-26'`	В браузерах — полночь UTC
`'26.05.2025'`	Не стандартизировано, риск ошибки
`'May 26 2025'`	Работает в большинстве браузеров
`'invalid string'`	NaN — неправильный вывод

Риски при использовании нестандартных строк

format('26/05/2025');
// Поведение не определено — в разных браузерах результат разный

Безопасный подход — всегда использовать ISO 8601 или объект Date:

// Безопасно
format(new Date(2025, 4, 26)); // месяц с 0

// Или
format('2025-05-26T00:00:00Z');

Входные данные из API

API чаще всего возвращают строки:

{
  "createdAt": "2025-05-26T08:30:00.000Z"
}

Эту строку можно передать в format напрямую:

const { createdAt } = apiResponse;
format(createdAt, 'ru');

Или с явным преобразованием для надёжности:

format(new Date(createdAt), 'ru');

Входные данные из базы данных

Даты из базы данных часто приходят как строки в формате MySQL или PostgreSQL:

// MySQL: "2025-05-26 10:00:00"
format(new Date('2025-05-26 10:00:00'.replace(' ', 'T') + 'Z'), 'ru');

Прямая передача "2025-05-26 10:00:00" может дать неверный результат из-за неоднозначности часового пояса.

Входные данные: null и undefined

Библиотека не защищена от null или undefined — такие значения вызовут ошибку или вернут некорректный результат:

format(null); // Ошибка или "NaN years ago"
format(undefined); // Аналогично

Защитная обёртка:

function safeFormat(date, locale = 'ru') {
  if (!date) return '';
  return format(date, locale);
}

Входные данные: объект Moment

Если в проекте используется Moment.js, его объекты не поддерживаются напрямую. Нужно конвертировать:

import moment from 'moment';
import { format } from 'timeago.js';

const m = moment('2025-05-26');

format(m.toDate(), 'ru');

Входные данные: объект Day.js

import dayjs from 'dayjs';
import { format } from 'timeago.js';

const d = dayjs('2025-05-26');

format(d.toDate(), 'ru');

Входные данные: числа в секундах (Unix timestamp)

const unixTimestamp = 1748260800; // секунды

format(unixTimestamp * 1000, 'ru');

Умножение на 1000 — стандартное преобразование из секунд в миллисекунды.

Входные данные из атрибута datetime

При использовании render() библиотека самостоятельно считывает атрибут datetime:

<time datetime="2025-05-26T10:00:00Z"></time>

Значение атрибута обрабатывается так же, как строковый аргумент в format. Поэтому рекомендуется использовать ISO 8601 в datetime.