Skip to main content

​
Time Ago

Convert timestamps to human-readable Persian relative time strings (e.g., “5 دقیقه پیش”).

​
Basic Usage

import { timeAgo } from "@persian-tools/persian-tools";

const date = new Date("2024-10-14T10:00:00");
console.log(timeAgo(date));
// Output: "5 ساعت پیش" (example output)

​
API Reference

​
date
Date | number
required
Date object or timestamp to convert
​
result
string
Relative time string in Persian

​
Examples

​
Social Media Posts

import { timeAgo, digitsEnToFa } from "@persian-tools/persian-tools";

const formatPostTime = (postDate: Date): string => {
	const relative = timeAgo(postDate);
	return digitsEnToFa(relative);
};

const post = { createdAt: new Date("2024-10-14T09:00:00") };
console.log(formatPostTime(post.createdAt));
// "۱ ساعت پیش"

​
Comment Timestamps

import { timeAgo } from "@persian-tools/persian-tools";

interface Comment {
	text: string;
	timestamp: Date;
}

const displayComment = (comment: Comment) => ({
	text: comment.text,
	time: timeAgo(comment.timestamp),
});

​
Time Ranges

The function returns appropriate Persian phrases for:
  • Seconds: “چند لحظه پیش”
  • Minutes: “X دقیقه پیش”
  • Hours: “X ساعت پیش”
  • Days: “X روز پیش”
  • Weeks: “X هفته پیش”
  • Months: “X ماه پیش”
  • Years: “X سال پیش”

​
Type Definition

function timeAgo(date: Date | number): string;