⏰ time-age

A lightweight, zero-dependency utility to format timestamps into human-readable relative time strings like "2 minutes ago" or "About a month ago".

✨ Features

• 🎯 Simple API - Single function, easy to use
• 📦 Tiny Bundle - Zero dependencies, minimal footprint
• 🔷 TypeScript Support - Full type definitions included
• 🌳 Tree-shakeable - ESM and CommonJS support
• ⚡ Accurate - Accounts for leap years and variable month lengths
• 🧪 Well Tested - Comprehensive test coverage

📦 Installation

npm install time-age

yarn add time-age

pnpm add time-age

🚀 Usage

ESM (Modern JavaScript/TypeScript)

import timeAge from "time-age";

// Current time
timeAge(new Date()); // "Just now"
timeAge(Date.now()); // "Just now"

// With time calculations
const SECOND = 1000;
const MINUTE = 60 * SECOND;
const HOUR = 60 * MINUTE;
const DAY = 24 * HOUR;

timeAge(Date.now() - 4 * SECOND); // "4 seconds ago"
timeAge(Date.now() - 2 * MINUTE); // "2 minutes ago"
timeAge(Date.now() - 2 * HOUR); // "2 hours ago"
timeAge(Date.now() - 1 * DAY); // "Yesterday"
timeAge(Date.now() - 3 * DAY); // "3 days ago"
timeAge(Date.now() - 30 * DAY); // "About a month ago"

// With ISO date strings
const postDate = "2026-01-20T10:00:00.000Z";
timeAge(postDate); // "4 days ago"

// Real-world examples
const blogPost = {
  title: "My Post",
  createdAt: new Date("2026-01-15")
};
console.log(`Published ${timeAge(blogPost.createdAt)}`); // "Published About a week ago"

const comment = {
  text: "Great article!",
  timestamp: Date.now() - 5 * HOUR
};
console.log(`Posted ${timeAge(comment.timestamp)}`); // "Posted 5 hours ago"

CommonJS (Node.js)

const timeAge = require("time-age");

const HOUR = 60 * 60 * 1000;

timeAge(Date.now()); // "Just now"
timeAge(Date.now() - 2 * HOUR); // "2 hours ago"

const user = {
  lastSeen: 1737720000000 // timestamp from DB
};
console.log(`Last seen ${timeAge(user.lastSeen)}`); // "Last seen 5 minutes ago"

Note: Both import styles work:

require("time-age"); // ✓ Recommended (clean)
require("time-age").default; // ✓ Works (backward compatible)

📖 API

timeAge(time: string | number | Date): string

Formats a timestamp into a human-readable relative time string.

Parameters

• time: string | number | Date
  • Date object: new Date()
  • Timestamp (milliseconds): Date.now() or 1234567890000
  • ISO 8601 string: "2026-01-24T12:00:00.000Z"

Returns

• string - Human-readable relative time

Output Examples

| Time Difference | Output | | --------------- | ----------------------------- | | < 1 second | "Just now" | | 1 second | "A second ago" | | 2-59 seconds | "X seconds ago" | | 1 minute | "A minute ago" | | 2-59 minutes | "X minutes ago" | | 1 hour | "An hour ago" | | 2-23 hours | "X hours ago" | | 1 day | "Yesterday" | | 2-6 days | "X days ago" | | 1 week | "About a week ago" | | 2-4 weeks | "About X weeks ago" | | 1 month | "About a month ago" | | 2-11 months | "About X months ago" | | 1 year | "About a year ago" | | 2+ years | "About X years ago" | | Future date | Returns formatted date string |

⚠️ Error Handling

The function throws a TypeError when an invalid date format is provided:

try {
  timeAge("invalid-date");
} catch (error) {
  console.error(error.message);
  // "Expected DateTime but got invalid-date instead.
  //  Ex. timeAge(new Date()) or timeAge(Date.now())"
}

🔍 Use Cases

• Social Media - "Posted 2 hours ago"
• Comments - "Comment from 3 days ago"
• Activity Feeds - "Updated About a month ago"
• Chat Applications - "Last seen 5 minutes ago"
• Blog Posts - "Published About a year ago"

🛠️ TypeScript

Full TypeScript support out of the box:

import timeAge from "time-age";

const timestamp: number = Date.now();
const result: string = timeAge(timestamp);

📄 License

MIT © Derek Oware

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check the issues page.

💖 Support

Give a ⭐️ if this project helped you!