secondsUntilUnix

Signature

secondsUntilUnix(value: string | number, options?: { epochUnit?: UnixUnit; }): number | null

Return the whole seconds from now until a stored Unix epoch, such as a JWT exp.

Rounded up to a whole second, so a wait of that length never falls short. result <= 0 means the target has been reached: it is RFC 7519 section 4.1.4’s test that the current time must be before exp.
A past target gives a negative number, and null is invalid input only. Check null first, then wait Math.max(0, n): Math.max(0, null) is 0, so an unchecked null reads as “no wait”.
value is a safe integer or a digit string ("1813060920"); anything else returns null. A fractional epoch returns null, though RFC 7519 section 2 allows one: every unix/ function shares one integer grammar. Call Math.floor(exp) first, which can only end a token early, never late.
No timeZone: an instant has none.

No leeway: RFC 7519 section 4.1.4 allows “some small leeway”, so add it where you test the result:

const left = secondsUntilUnix(exp, { epochUnit: "seconds" });
const expired = left === null || left + leeway <= 0;

Reads the clock once, after value and options are checked.

For “expires in 3 days”, once left is not null and above 0:

formatHumanDuration(
  normalizeDuration(durationFromUnits({ seconds: left }), { largestUnit: "day" }),
); // "3d" for 259200

Without normalizeDuration the text is "259200s".

Parameters

Parameter	Type	Description
`value`	`string` \| `number`	Unix epoch: a safe integer, or a string of optionally negative ASCII digits

Options

options

optional: the unit value is counted in

Option	Type	Default	Description
`epochUnit?`	`"seconds"` \| `"milliseconds"` \| `"second"` \| `"millisecond"` (`UnixUnit`)	`"milliseconds"`	The unit `value` is counted in: `"seconds"` or `"milliseconds"`, singular or plural; any other value returns `null`. The result is always in seconds. A seconds value read as the default milliseconds lands in 1970 and looks long past, so pass `"seconds"` for a JWT `exp`.

Returns

whole seconds until value, negative when it is past, or null for an invalid value or options or an epoch outside Temporal’s range

UnixUnit

Examples

import { secondsUntilUnix } from "@northguild/gmt/unix/calculate";

secondsUntilUnix(1813060920, { epochUnit: "seconds" }) // 120 (two minutes after a clock at 1813060800)

value

output

Source

unix/calculate/secondsUntilUnix.ts