Shaileshkale17 / utc-To-TimeAgo

A TypeScript library to convert UTC timestamps (ISO 8601 format) into human-readable "time ago" strings. Perfect for displaying relative time in applications.

utc-To-TimeAgo

A lightweight TypeScript library to convert MongoDB ISODate timestamps into human-readable "time ago" strings.

---

Features

• Converts MongoDB ISODate or standard timestamps to "time ago" format.
• Fully written in TypeScript for type safety.
• Supports CommonJS and ES Modules.
• Lightweight and easy to integrate.

---

Installation

Install the package using NPM:

npm install utc-To-TimeAgo

Or using Yarn:

yarn add utc-To-TimeAgo

---

Usage

Importing the Library

Using ES Modules:

import { utcToTimeAgo } from "utc-To-TimeAgo";

Using CommonJS:

const { utcToTimeAgo } = require("utc-To-TimeAgo");

Example

import { utcToTimeAgo } from "utc-To-TimeAgo";

const timestamp = "2024-11-20T18:30:00Z"; // MongoDB ISODate format
const result = utcToTimeAgo(timestamp);

console.log(result); // Example Output: "2 months ago"

Handling Date Objects

You can also pass a JavaScript Date object:

const date = new Date("2024-11-20T18:30:00Z");
console.log(utcToTimeAgo(date)); // Example Output: "2 months ago"

---

How It Works

The library calculates the difference between the current time and the provided timestamp. It then returns a human-readable string, such as:

• just now
• 5 seconds ago
• 2 days ago
• 1 year ago

---

API Reference

utcToTimeAgo(timestamp: string | Date): string

Parameters

• timestamp (required): A string in ISO 8601 format (e.g., "2024-11-20T18:30:00Z") or a JavaScript Date object.

Returns

• A string representing the "time ago" format, such as "2 hours ago" or "1 year ago".

Examples

utcToTimeAgo("2024-11-20T18:30:00Z"); // "2 months ago"
utcToTimeAgo(new Date("2024-11-20T18:30:00Z")); // "2 months ago"

---

Development

Prerequisites

Make sure you have Node.js and NPM installed.

Clone the Repository

git clone https://github.com/Shaileshkale17/utc-To-TimeAgo.git
cd utc-To-TimeAgo

Install Dependencies

npm install

Build the Package

To compile the TypeScript code into JavaScript, run:

npm run build

The compiled files will be available in the dist directory.

Testing Locally

You can test the library locally by linking it to another project:

npm link

Then, in the other project:

npm link utc-To-TimeAgo

---

Contributing

Contributions are welcome! If you'd like to contribute:

1. Fork the repository.
2. Create a new branch: git checkout -b feature-name.
3. Commit your changes: git commit -m 'Add feature'.
4. Push to the branch: git push origin feature-name.
5. Submit a pull request.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Feedback

If you encounter issues or have suggestions, feel free to open an issue on GitHub.

---

Acknowledgments

• Inspired by real-world requirements for MongoDB timestamps.
• Built with ❤️ by Shailesh kale.

---