# ttlFromNow

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

## Signature

```ts
ttlFromNow(units: Partial<Record<keyof DurationLike, number>>): Ttl | null
```

Express one length of time from now in every form a receiver wants: seconds, milliseconds, a Unix epoch, an HTTP date and a UTC string.

- Use it when one length goes to several receivers, such as a cookie's `Max-Age` and `Expires` beside a token's `exp`. Every field comes from one clock read; separate calls can straddle a second.
- `seconds` and `milliseconds` round up, so a wait never falls short. `epochSeconds`, `httpDate` and `iso` floor to the same second.
- Counts in UTC, so the result does not change with the server's zone. A missing day clamps to the end of the month, as `addUtc` does. No 400-day cap is applied.
- `units` is an object of unit amounts, such as `{ days: 90 }`. A duration string returns null. A fractional amount returns null: write `{ hours: 36 }` for a day and a half.
- Lengths are unsigned: a negative amount returns null.
- `{ days: 0 }` gives `seconds: 0`. RFC 6265 section 4.1.1's server grammar has no zero `Max-Age` (`non-zero-digit *DIGIT`), though receivers accept one (section 5.2.2).
- A year past 9999 returns null, because `httpDate` has no four-digit form (RFC 9110 section 5.6.7). The whole result is null so a non-null result is usable in full. `getUtcIn` and `getUnixIn` reach those years.
- Examples read the clock at 2027-06-15T12:00:00Z.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `units` | `Partial<Record<keyof DurationLike, number>>` | unit amounts, such as `{ days: 90 }`; never negative |

## Returns

the length in each form, or null for invalid `units`, a negative amount, a result outside Temporal's range or a year past 9999

## Types

### Ttl

One length from now, in each form a receiver wants. All five come from one clock read, so `epochSeconds`, `httpDate` and `iso` name the same second. `seconds` and `milliseconds` round up, so they can exceed the floored forms: for `{ milliseconds: 1500 }`, `seconds` is 2. From a clock on a whole second `epochSeconds` is now plus 1; from a clock at .800 it is the floored now plus 2.

```ts
import type { Ttl } from "@northguild/gmt";
```

| Member | Type | Description |
| --- | --- | --- |
| `seconds` | `number` | Whole seconds, rounded up: a cookie `Max-Age` or a cache `max-age`. |
| `milliseconds` | `number` | Whole milliseconds, rounded up: a timer delay. |
| `epochSeconds` | `number` | The end as whole Unix seconds, floored: a JWT `exp`. |
| `httpDate` | `string` | The end as an IMF-fixdate (RFC 9110 section 5.6.7): a cookie `Expires`. |
| `iso` | `string` | The end as UTC text in whole seconds, floored. |

## Related types

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

## Examples

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

ttlFromNow({ days: 1 })?.seconds // 86400 (a cookie Max-Age for one day)
```

## Source

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