⏳ chronosFX: Lightweight Date & Time Utilities

A clean, modern, and dependency-free JavaScript date & time utility library.
Format dates, compare timestamps, calculate day differences, and generate human-friendly relative times — all in a tiny package.

📌 Status & Badges

📖 About chronosFX

chronosFX is a lightweight, beginner-friendly, and dependency-free date & time utility library written using pure JavaScript ES Modules.

It provides essential utilities like:

• Date formatting
• Time formatting
• Human-readable “time ago”
• Adding / subtracting days
• Checking valid dates
• Converting dates to ISO format
• Calculating the number of days between two dates

No dependencies.
Super lightweight.
Perfect for any JavaScript/Node.js project.

✨ Example Output

import chronos from "chronosfx";

chronos.formatDate("2025-11-14");
// "14 Nov 2025"

chronos.timeAgo(Date.now() - 60000);
// "1 minutes ago"

chronos.addDays("2025-11-14", 10);
// "2025-11-24"

🚀 Features

• 🗓 Format Dates → "14 Nov 2025"
• ⏱ Format Time → "06:22 PM" / "18:22"
• 🔁 Time Ago → "5 minutes ago"
• ➕ Add Days → "2025-11-21"
• 🔍 Validate Date Inputs
• 🔢 Days Between Two Dates
• 🔗 Convert to ISO Format
• ⚡ Get Current Timestamp
• 🟢 Zero Dependencies
• 📦 Tiny & Fast
• 🧑‍💻 Easy to Understand Code

📦 Installation

Using npm

npm install chronosfx

Using pnpm

pnpm add chronosfx

Using yarn

yarn add chronosfx

📚 Usage

✔ ES Module Import

import chronos from "chronosfx";

console.log(chronos.formatTime("2025-11-14T18:30:00"));
// "06:30 PM"

✔ Named Import

import { addDays, timeAgo } from "chronosfx";

addDays("2025-11-14", 7);
// "2025-11-21"

timeAgo(Date.now() - 3000);
// "3 seconds ago"

🛠 API Reference

isValidDate(input)

Checks if the input is a valid date.

formatDate(input)

Returns "DD Mon YYYY".

formatTime(input, { hour12: true })

Formats time in 12-hour or 24-hour format.

getCurrentTimestamp()

Returns the current timestamp in milliseconds.

toISO(input)

Converts any valid date to an ISO formatted string.

addDays(input, days)

Adds days and returns a formatted date:
"YYYY-MM-DD".

daysBetween(a, b)

Returns the number of days between two dates.

timeAgo(input)

Returns human-readable relative time such as:

• "just now"
• "5 minutes ago"
• "yesterday"

📂 Project Structure

chronosfx/
├── index.js         # Main ES module code
├── package.json     # Package metadata
├── README.md        # Documentation
└── LICENSE          # MIT License

🛠 Development & Contribution

🧹 Code Style

• Pure ES Modules (no CommonJS)
• Beginner-friendly, easy-to-read code
• Uses no external libraries
• Lightweight and clean utility functions

🤝 Contributing

1. Fork the repository
2. Create a new branch

   git checkout -b feature/your-feature

3. Commit your changes

   git commit -m "Add new feature"

4. Push and open a PR

📝 License

This project is licensed under the MIT License — free for personal and commercial use.

👨‍💻 Author

Rohit Pakhre
Creator of chronosFX