intervalFromDurationUtc

Signature

intervalFromDurationUtc(value: string, duration: string, anchor: "start" | "end", options?: { overflow?: "reject" | "constrain" | undefined; }): { start: string; end: string; } | null

Construct a UTC 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("UTC"), adds/subtracts the duration there, then converts back to an Instant — 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 (mirrors addUtc).
• A negative duration (e.g. "-P1D") can invert the computed span; returns null when that happens, mirroring intervalIntersectionUtc’s start > end rejection.
• Returns null on invalid input (unparseable value, invalid duration, or an anchor other than "start"/"end").

Parameters

Parameter	Type	Description
value	string	ISO UTC datetime string (e.g. “2024-03-10T12:00:00Z”)
duration	string	ISO 8601 duration string
anchor	"start" | "end"	“start” | “end” — which endpoint value represents

Options

options

How an out-of-range result is handled

Option	Type	Default	Description
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	What to do when the result is not a real date. "constrain" clamps it to the last valid day, so Jan 31 + 1 month is Feb 29/28 (TC39 Temporal); "reject" returns null.

Returns

{ start, end } with the constructed span (UTC Instant strings), or null on invalid input

Members

Member	Type	Description
start	string	The instant the interval begins at, as an ISO 8601 UTC string ending in Z.
end	string	The first instant after the interval, in the same format as start. 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

• Overflow

Examples

import { intervalFromDurationUtc } from "@northguild/gmt/utc/interval";

intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }

valueduration

output

 

Source

utc/interval/intervalFromDurationUtc.ts