> ## Documentation Index
> Fetch the complete documentation index at: https://persian-tools.usestrict.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Remaining Time

> Calculate the structured (years/months/days/hours/minutes/seconds) breakdown of time remaining until a target Gregorian date.

`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

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

```ts theme={null}
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

```ts theme={null}
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 `و`:

```ts theme={null}
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`