time-by-now

A tiny utility to convert dates into human-readable strings like “2 hours ago” or “in 3 days”.

Table of Contents

• Installation
• Usage
• API
• Examples
• Contributing
• Changelog
• Support
• License

Installation

With npm:

npm install time-by-now

With yarn:

yarn add time-by-now

Usage

const { timeAgo, timeUntil } = require("time-by-now");

// Past times
console.log(timeAgo("2025-08-01")); 
// "1 month ago"

// Future times
console.log(timeUntil("2025-12-25")); 
// "in 3 months"

API

timeAgo(date)

• Converts a Date, timestamp, or date string into a human-friendly “time ago” format.
• Returns "just now" if less than a second has passed.

timeUntil(date)

• Converts a Date, timestamp, or date string into a human-friendly “time until” format.
• Returns "already passed" if the date is in the past.

Examples

timeAgo(new Date(Date.now() - 60000));     
// "1 minute ago"

timeAgo(Date.now() - 86400000);           
// "1 day ago"

timeUntil(Date.now() + 3600000);          
// "in 1 hour"

timeUntil("2030-01-01");                  
// "in 5 years"

Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repo
2. Create your feature branch (git checkout -b feature/YourFeature)
3. Commit your changes (git commit -m "Add some feature")
4. Push to your branch (git push origin feature/YourFeature)
5. Open a Pull Request

Changelog

See CHANGELOG.md for details on recent updates. We follow Semantic Versioning (MAJOR.MINOR.PATCH).

Support

• Found a bug? → Open an issue
• Have an idea? → Start a discussion or PR
• Like the project? → Give it a star on GitHub

📜 License

MIT © Arnab Sarkar