intervalFromDurationUnix

Signature

intervalFromDurationUnix(value: string | number, duration: string, anchor: "start" | "end", options?: { epochUnit?: UnixUnit; timeZone?: string; overflow?: "reject" | "constrain" | undefined; }): { start: number; end: number; } | null

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 in timeZone, 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.
• The computed boundary is floored to a whole epochUnit, so a duration shorter than one unit does not survive: with anchor: "start" the interval is empty ("PT0.5S" in seconds gives the same { start, end } as "PT0S"), and with anchor: "end" the start falls back to the previous whole unit, making the interval one unit long.
• A negative duration (e.g. "-P1D") can invert the computed span; returns null when that happens, mirroring intervalIntersectionUnix’s start > end rejection.
• Returns null on invalid input (a value that is not a safe integer or numeric string of one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — invalid duration, an anchor other than "start"/"end", or an invalid/unavailable timeZone).
• 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 value (seconds or milliseconds): a safe integer or a digit string
duration	string	ISO 8601 duration string
anchor	"start" | "end"	“start” | “end” — which endpoint value represents

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

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

Members

Member	Type	Description
start	number	The instant the interval begins at, as a Unix epoch number counted in epochUnit. A boundary that falls between two whole units is rounded down to the earlier one.
end	number	The first instant after the interval, counted in epochUnit and rounded as start is. It is exclusive: the interval holds everything from start up to but not including this value. It can equal start, which makes the interval empty.

Related types

• UnixUnit
• Overflow

Examples

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

intervalFromDurationUnix(1704067200000, "P1D", "start", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }

valueduration

output

 

Source

unix/interval/intervalFromDurationUnix.ts