# getDateAgo

:::caution[Unreleased]
Not in `@northguild/gmt` 1.20.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
getDateAgo(units: Partial<Record<"years" | "months" | "weeks" | "days", number>>): string
```

Return the PlainDate before today, as an ISO string, counted from the current time.

- Reads the clock once, after `units` is checked.
- `units` is an object of unit amounts (years, months, weeks, days), such as `{ days: 90 }`. A duration string returns "". A time unit returns "", even at zero, as `subtractDate` does; use `getDateTimeAgo` or `getZonedAgo` for hours. A fractional amount returns "": use whole days.
- Lengths are unsigned: a negative amount returns "". `getDateIn` counts forward.
- `{ days: 0 }` is a valid length and gives today, so `getDateAgo({ days: 0 })` equals `getToday()`.
- Counts from today in the system time zone, so a server's result changes with its zone; `getZonedAgo` names one.
- A missing day clamps to the end of the month: 31 March minus a month is 28 February, or 29 in a leap year.
- Each call reads the clock. To pin the start, use `subtractDate(getToday(), units)`.
- Examples read the clock at 2027-06-15T12:00:00Z, with the system time zone UTC.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `units` | `Partial<Record<"years" \| "months" \| "weeks" \| "days", number>>` | unit amounts, such as `{ days: 90 }`; never negative |

## Returns

ISO PlainDate string, or "" for invalid `units`, a negative amount, a time unit, an unavailable system zone or a result outside Temporal's range

## Related types

- [`DateDurationUnit`](/gmt/reference/types/DateDurationUnit)

## Examples

```ts
import { getDateAgo } from "@northguild/gmt/plain/get";

getDateAgo({ days: 90 }) // "2027-03-17"
```

## Source

[plain/get/getDateAgo.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/plain/get/getDateAgo.ts)