totalUnitsFromNow

Signature

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

DateTimeDurationUnit

Examples

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

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

units amount

units unit

unit

output

Source

duration/calculate/totalUnitsFromNow.ts