# totalUnitsFromNow

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

## Signature

```ts
totalUnitsFromNow(units: Partial<Record<keyof DurationLike, number>>, unit: keyof DurationLike | DateTimeUnit, options?: { timeZone?: string; }): number | null
```

Express a length of time from now as one fractional total in one unit.

- Counts from the current time in UTC, so the result does not change with the server's zone. Pass `timeZone` to count calendar units on another zone's wall clock; a day in Paris can be 23 hours. A result in a gap moves later and a repeated time takes the earlier (`"compatible"`, see LOCAL_TIME_RESOLUTION).
- `units` is an object of unit amounts, such as `{ months: 1 }`. A duration string returns null. A fractional amount returns null: write `{ hours: 36 }` for a day and a half. With `timeZone`, write `{ days: 1, hours: 12 }` instead, because the day then counts on the wall clock: across a spring-forward in Paris it totals 35 hours, not 36.
- Lengths are unsigned: a negative amount returns null.
- The result is fractional and unrounded, as `totalDuration` is. A cookie `Max-Age` must be whole digits (RFC 6265 section 5.2.2 ignores a value with a fraction), so a caller whose length holds sub-second units rounds first.
- A timer delay is `totalUnitsFromNow(units, "milliseconds")`. Writing `getUnixIn(units) - getUnixNow()` reads the clock twice and can subtract from null.
- Each call reads the clock. To pin the start, use `totalDuration(durationFromUnits(units), "seconds", { relativeTo })`, where `relativeTo` is a zoned string such as `getZonedNow("UTC")`. A `Z` string, such as `getUtcNow()`, returns null (Temporal section 13.19).
- `unit` accepts the plural or singular name, as `totalDuration` does.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `units` | `Partial<Record<keyof DurationLike, number>>` | unit amounts, such as `{ years: 1 }`; never negative |
| `unit` | `keyof DurationLike` \| `DateTimeUnit` | the unit to total into, plural or singular |

## Options

**options**

optional: the time zone calendar units count in

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `timeZone?` | `string` | `"UTC"` | The time zone calendar units count in: an IANA name, a UTC offset, or `"local"` for the system time zone. An unknown zone returns `null`. |

## Returns

the fractional total in `unit`, or null for invalid `units`, a negative amount, an invalid `unit` or `options`, or a length Temporal cannot total

## Related types

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

## Examples

```ts
import { totalUnitsFromNow } from "@northguild/gmt/duration/calculate";

totalUnitsFromNow({ days: 90 }, "seconds") // 7776000 (a cookie Max-Age or HSTS max-age for 90 days)
```

## Source

[duration/calculate/totalUnitsFromNow.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/duration/calculate/totalUnitsFromNow.ts)