date-buddy

A tiny (~1KB), dependency-free JavaScript utility for human-friendly date/time formatting.

Features

• 🕒 Convert dates to "time ago" format (e.g., "3 hours ago")
• ⏳ Format future dates (e.g., "in 2 weeks")
• 📅 Clean date formatting with optional weekday names
• 💪 Works with both Date objects and date strings
• ⚡ Zero dependencies

Installation

npm install date-buddy

Usage

// CommonJS
const { timeAgo, timeUntil, formatDate, formatDateWithDay } = require('date-buddy');

// ESM
import { timeAgo, timeUntil, formatDate, formatDateWithDay } from 'date-buddy';

// Past dates
timeAgo(new Date('2025-10-29'));  // "1 day ago"
timeAgo('2025-10-15');           // "15 days ago"

// Future dates
timeUntil('2026-03-25');         // "in 5 months"
timeUntil(new Date('2026-01-01')); // "in 2 months"

// Date formatting
formatDate('2025-10-29');        // "October 29, 2025"
formatDateWithDay('2025-10-29'); // "Wednesday, October 29, 2025"

API

timeAgo(date)

• Input: Date object or date string
• Returns: Human-readable string for past dates (e.g., "3 hours ago")
• Invalid input: Returns "Invalid date"
• Future dates: Returns suggestion to use timeUntil

timeUntil(date)

• Input: Date object or date string
• Returns: Human-readable string for future dates (e.g., "in 2 days")
• Invalid input: Returns "Invalid date"
• Past dates: Returns suggestion to use timeAgo

formatDate(date)

• Input: Date object or date string
• Returns: Formatted date string (e.g., "October 29, 2025")
• Invalid input: Returns "Invalid date"

formatDateWithDay(date)

• Input: Date object or date string
• Returns: Formatted date with weekday (e.g., "Wednesday, October 29, 2025")
• Invalid input: Returns "Invalid date"

Contributing

Contributions are welcome! Open issues or PRs on GitHub.

License

MIT — See LICENSE for details.