Skip to main content
remainingTime accepts a Gregorian target date (string, number, or Date) and returns a structured countdown plus a Persian-digit toString() and an isFinished flag.

​
Function

remainingTime(date: string | number | Date): {
  years: number;
  months: number;
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  toString(): string;
  isFinished: boolean;
}

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

const r = remainingTime("2025-12-31T23:59:59Z");
r.years; // e.g. 0
r.months; // e.g. 7
r.days; // ...
r.isFinished; // false
r.toString(); // "۱ سال و ۲ ماه و ۱۵ روز" (Persian digits; only non-zero parts)

​
When the target has passed

const past = remainingTime(new Date("2000-01-01"));
past.isFinished; // true
past.toString(); // ""
past.years; // 0
// (all numeric fields are 0)

​
Calendar-naive math

Months are 30 days, years are 365 days. This is an approximation — leap years and varying month lengths are ignored. For legal/financial deadlines requiring calendar precision, use a calendar-aware library.

​
Input handling

  • Accepts anything new Date(date) accepts.
  • Invalid dates ("not-a-date") throw TypeError("PersianTools: remainingTime - The input must be a valid date").

​
toString() — Persian digit output

The string method converts component values to Persian digits via digitsEnToFa, then joins non-zero parts with و: 
r.toString(); // "۱ سال و ۲ ماه و ۱۵ روز و ۳ ساعت و ۲۰ دقیقه و ۵ ثانیه"
If you need English digits, build the string yourself from the numeric fields.

​
Pitfalls

  • toString() returns "" when finished — check isFinished to render a “Finished” label.
  • Calendar-naive. Not suitable for “exactly N months from today”.
  • No Jalali support here. Convert Jalali targets to Gregorian first if you have one.

​
Source

src/modules/remainingTime/index.ts, getCurrentDateTime.ts · Tests: test/remainingTime.spec.ts