Human-friendly Relative Time Formatter – human-time

The library outputs phrases like “just now”, “this morning”, “3 days ago”, or “in 5m” based on the time difference between the provided date and the current moment.

It supports both past and future dates, detects contextual time periods (morning, afternoon, evening), and works across Node.js, Bun, Deno, and browser environments.

Features:

• Zero Dependencies: The library consists of a single function with no external libraries required.
• Dual Direction Support: Handles both past timestamps (“5m ago”) and future timestamps (“in 5m”).
• Context-Aware Formatting: Detects time-of-day context to output “this morning”, “this afternoon”, or “late last night” for same-day events.
• Smart Fallback Logic: Automatically switches from relative time to absolute formats (month/day or year) when dates are older.

Use Cases:

• Social Media & Chat Applications: Display message timestamps or post ages in a natural, familiar way, similar to platforms like WhatsApp or X.com.
• Activity Logs & Dashboards: Present system events, user actions, or audit trails with readable time strings that are easy to scan.
• Notification Systems: Show when a notification arrived using phrases like “Just now” or “Yesterday” to improve clarity.
• E-commerce & Listings: Format the “posted date” or “last updated” time for products, articles, or blog posts.

How To Use It:

1. Install human-time-2026 and import it into your project.

# Yarn
$ yarn add human-time-2026

# NPM
$ npm install human-time-2026

# PNPM
$ pnpm install human-time-2026

# BUN
$ bun add human-time-2026

import humanTime from 'human-time-2026';

2. Pass the humanTime function a Date object or a timestamp. The library handles the rest.

// Recent past (under 5 seconds)
humanTime(Date.now() - 3000);
// Output: "just now"

// Seconds ago (5-59 seconds)
humanTime(Date.now() - 45000);
// Output: "45s ago"

// Minutes ago (1-59 minutes)
humanTime(Date.now() - (15 * 60 * 1000));
// Output: "15m ago"

// Same-day context (current day, different hour)
// If current time is 3:00 PM and target is 8:00 AM same day:
const morning = new Date();
morning.setHours(8, 0, 0, 0);
humanTime(morning);
// Output: "this morning"

// Previous day
const yesterday = Date.now() - (25 * 60 * 60 * 1000);
humanTime(yesterday);
// Output: "yesterday"

// Multiple days ago (2-6 days)
humanTime(Date.now() - (3 * 24 * 60 * 60 * 1000));
// Output: "3 days ago"

// Weeks ago (7-29 days)
humanTime(Date.now() - (14 * 24 * 60 * 60 * 1000));
// Output: "2w ago"

// Months ago (30-364 days)
humanTime(Date.now() - (90 * 24 * 60 * 60 * 1000));
// Output: "Mar 19" (shows month and day)

// Years ago (365+ days)
humanTime(new Date('2025-01-18'));
// Output: "2025"

// Future seconds
humanTime(Date.now() + 30000);
// Output: "in 30s"

// Future minutes
humanTime(Date.now() + (45 * 60 * 1000));
// Output: "in 45m"

// Tomorrow
humanTime(Date.now() + (25 * 60 * 60 * 1000));
// Output: "tomorrow"

// Future days
humanTime(Date.now() + (5 * 24 * 60 * 60 * 1000));
// Output: "in 5 days"

// If current time is 10:00 AM:

// Event at 2:00 AM today
const lateNight = new Date();
lateNight.setHours(2, 0, 0, 0);
humanTime(lateNight);
// Output: "late last night" (hours 0-4)

// Event at 9:00 AM today
const morning = new Date();
morning.setHours(9, 0, 0, 0);
humanTime(morning);
// Output: "this morning" (hours 5-11)

// Event at 2:00 PM today
const afternoon = new Date();
afternoon.setHours(14, 0, 0, 0);
humanTime(afternoon);
// Output: "this afternoon" (hours 12-16)

// Event at 7:00 PM today
const evening = new Date();
evening.setHours(19, 0, 0, 0);
humanTime(evening);
// Output: "this evening" (hours 17-23)

Alternatives:

• day.js: A 2KB library with date manipulation features including relative time via the relativeTime plugin.
• timeago.js: A 2KB library focused specifically on time ago formatting with built-in localization support for 40+ languages.
• 7 Best JavaScript Timeago Plugins For Human-readable Datetime Format

FAQs:

Q: How do I update the time string in real-time without page refresh?
A: Set up an interval that re-calls the humanTime function with your original timestamp.

Q: Does this work with timezones or do I need to handle timezone conversion separately?
A: The library uses the JavaScript Date object’s built-in timezone handling. When you pass a timestamp or Date object, JavaScript interprets it in the local timezone of the execution environment. The library calculates differences based on these local interpretations. If you need explicit timezone conversions, handle those before passing dates to humanTime.

Q: Why does the output sometimes jump from “this morning” to “yesterday” even though less than 24 hours passed?
A: The same-day context detection compares calendar dates, not 24-hour periods. An event from 11:00 PM yesterday will show “yesterday” at 1:00 AM today, even though only 2 hours elapsed.

The post Human-friendly Relative Time Formatter – human-time appeared first on CSS Script.