addUnix

Signature

addUnix(value: string | number, units: Partial<Record<keyof DurationLike, number>>, options?: { epochUnit?: UnixUnit; timeZone?: string; overflow?: "reject" | "constrain" | undefined; }): number | null

Add a temporal amount to a Unix epoch value and return the resulting epoch.

• Converts to ZonedDateTime, adds the duration, then converts back to epoch.
• Validates duration units and values.
• value is a safe integer or a digit string ("1706659200000"); anything else returns null.
• Returns null for invalid input.
• Limit at an offset with seconds. The instant is placed in the offset’s whole-minute zone, moved by its seconds, and the moved instant must be inside Temporal’s range. So within the offset’s seconds (under a minute) of the last instant Temporal supports (+275760-09-13T00:00:00Z) for an offset east of UTC, or of the first (-271821-04-20T00:00:00Z) for one west, this returns null. An offset to the minute has no such limit.

Parameters

Parameter	Type	Description
value	string | number	Unix epoch: a safe integer, or a string of optionally negative ASCII digits
units	Partial<Record<keyof DurationLike, number>>	Partial<Record<DateTimeDurationUnit, number>> object specifying units to add

Options

options

optional: how value is read and how an out-of-range result day is handled

Option	Type	Default	Description
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit the epoch values are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns null. The result is in the same unit.
timeZone?	string	"UTC"	The time zone the calendar arithmetic runs in: an IANA name, a UTC offset (a time zone identifier such as +05:30, +0530 or -08, or a stored offset ±HH:MM[:SS], what getTimeZoneOffset returns), or "local" for the system time zone. An unknown zone returns null.
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	How a result day that does not exist in its month is handled, such as January 31 plus one month. "constrain" clamps to the last valid day, and "reject" returns null.

Returns

Unix epoch number after addition, or null on invalid input

Related types

• DateTimeDurationUnit
• UnixUnit
• Overflow

Examples

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

addUnix(1706659200000, { days: 1 }) // 1706745600000

value

output

 

Source

unix/calculate/addUnix.ts