Skip to main content
timeAgo accepts a Jalali date-time string (e.g. "1402/06/15 13:05:20") and returns a Persian relative-time phrase. For Gregorian countdowns to a future date, use Remaining Time.

​
Function

​
Input requirements

The datetime is a string, in Jalali calendar, in "yyyy/mm/dd hh:mm:ss" format. The library normalizes by zero-padding via standardizeFaDateTime, so "1402/6/5 1:5:0" is also accepted.
  • Passing a Date (or number) as the first argument throws TypeError("PersianTools: timeAgo - The input must be a string").
  • A format that can’t be normalized throws TypeError("PersianTools: timeAgo - The input format must be yyyy/mm/dd hh:mm:ss").

​
Output vocabulary

Persian phrases using قبل / بعد (not پیش): Future dates produce "... بعد" phrases — the function is bidirectional.

​
Re-exported helpers

These are the same helpers used internally; use them when implementing custom flows on top of Jalali date strings.

​
Pitfalls

  • Input is a Jalali STRING, not a JS Date or number. Pass new Date(...) and it throws.
  • Output uses قبل/بعد, not پیش.
  • No Gregorian → Jalali conversion is built in. If you have a Gregorian Date, convert with date-fns-jalali or moment-jalaali first.

​
Source

src/modules/timeAgo/index.ts, helpers.ts, timestamp.ts, constants.ts · Tests: test/timeAgo.spec.ts