intervalFromDurationUnix

Signature

intervalFromDurationUnix(value: string | number, duration: string, anchor: "start" | "end", options?: { epochUnit?: "seconds" | "milliseconds"; timeZone?: string; overflow?: Overflow; }): { start: number; end: number; }

import { intervalFromDurationUnix } from "@northguild/gmt/unix/interval";

Construct a Unix epoch interval from a single point plus an ISO 8601 duration, anchored at either end.

• anchor: "start" treats value as the interval start and adds duration to get the end.
• anchor: "end" treats value as the interval end and subtracts duration to get the start.
• Converts to ZonedDateTime (system timeZone by default, consistent with addUnix), adds/subtracts the duration there, then converts back to epoch — this is what lets calendar units (years/months/ weeks/days) resolve without a relativeTo: unlike a bare Temporal.Instant, the ZonedDateTime supplies its own implicit reference point.
• A negative duration (e.g. "-P1D") can invert the computed span; returns null when that happens, mirroring intervalIntersectionUnix’s start > end rejection.
• overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. adding 1 month to Jan 31: “constrain” clamps to Feb 29/28, “reject” returns null.
• Returns null on invalid input (non-finite/non-integer value, invalid duration, an anchor other than "start"/"end", or an invalid/unavailable timeZone).

Parameters

Parameter	Type	Description
value	string | number	Unix epoch value (seconds or milliseconds)
duration	string	ISO 8601 duration string
anchor	"start" | "end"	“start” | “end” — which endpoint value represents

Options

options

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

Returns

{ start, end } with the constructed span (epoch numbers), or null on invalid input

Related types

• Overflow

Examples

intervalFromDurationUnix(1704067200000, "P1D", "start", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
intervalFromDurationUnix(1704153600000, "P1D", "end", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
intervalFromDurationUnix(1706659200000, "P1M", "start", { timeZone: "UTC", overflow: "reject" }) // null (Jan 31 + 1 month overflows)
intervalFromDurationUnix(1704067200000, "-P10D", "start", { timeZone: "UTC" }) // null (inverted span)
intervalFromDurationUnix(NaN, "P1D", "start") // null

Source

unix/interval/intervalFromDurationUnix.ts