@puraty/intl-time-ago

A lightweight, type-safe relative time formatter that leverages the native JavaScript Intl.RelativeTimeFormat API. This package provides high localization accuracy and minimal bundle size by avoiding heavy date manipulation libraries.

It supports both past ("5 minutes ago") and future ("in 2 days") relative time formatting.

Installation

npm install @puraty/intl-time-ago

Usage

The package exports a single, simple function: timeAgo.

Example 1: Basic Usage (Past)

import { timeAgo } from '@puraty/intl-time-ago';

// 5 minutes ago
const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;

// English (en-US) - Default locale
console.log(timeAgo(fiveMinutesAgo)); 
// Output: "5 minutes ago" 

// Japanese (ja-JP)
console.log(timeAgo(fiveMinutesAgo, 'ja-JP')); 
// Output: "5 分前"

Example 2: Future Dates and Different Units

import { timeAgo } from '@puraty/intl-time-ago';

// 3 days from now
const futureDate = Date.now() + 3 * 24 * 60 * 60 * 1000;

// French (fr-FR)
console.log(timeAgo(futureDate, 'fr-FR')); 
// Output: "dans 3 jours" 

// Just now / Soon
const justNow = Date.now() - 15000; // 15 seconds ago
console.log(timeAgo(justNow, 'en-US')); 
// Output: "just now" (or "in 0 seconds", depending on Intl implementation)

API Reference

timeAgo(date: Date | number, locale?: string): string

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | date | Date \| number | N/A | The date to format, provided as a Date object or a UNIX timestamp (milliseconds). | | locale | string | 'en-US' | The locale string to use for formatting (e.g., 'en-US', 'ja-JP', 'fr-FR'). |

License

This project is licensed under the ISC License. See the LICENSE file for details.

Contributing

Feel free to open issues or submit pull requests to improve this utility!