addUnix

Signature

addUnix(value: number, units: Partial<Record<DateTimeDurationUnit, number>>, options?: { epochUnit?: "seconds" | "milliseconds"; timeZone?: string; overflow?: Overflow; }): number

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

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.
• Returns null for invalid input. overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. adding 1 month to Jan 31: “constrain” clamps to Feb 29/28, “reject” throws (resulting in null).

Parameters

Parameter	Type	Description
value	number	Unix timestamp (number)
units	Partial&lt;Record&lt;DateTimeDurationUnit, number&gt;&gt;	Partial<Record<DateTimeDurationUnit, number>> object specifying units to add

Options

options

Option	Type	Default
epochUnit?	"seconds" | "milliseconds"	—
timeZone?	string	—
overflow?	Overflow	—

Returns

Unix epoch number after addition, or null on invalid input

Related types

• DurationUnit
• DateTimeDurationUnit
• Overflow
• TimeDurationUnit

Examples

addUnix(1706659200000, { days: 1 }) // 1706745600000
addUnix(1706659200, { days: 1 }, { epochUnit: "seconds" }) // 1706745600
addUnix(-86400000, { days: 1 }) // 0 (Dec 31 1969 + 1 day = Jan 1 1970)

Source

unix/calculate/addUnix.ts