intervalFromDurationUtc

Signature

intervalFromDurationUtc(value: string, duration: string, anchor: "start" | "end", options?: { overflow?: Overflow; }): { start: string; end: string; }

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

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.
• 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 (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

Option	Type	Default
overflow?	Overflow	—

Returns

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

Related types

• Overflow

Examples

intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
intervalFromDurationUtc("2024-01-02T00:00:00Z", "P1D", "end") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
intervalFromDurationUtc("2024-01-31T00:00:00Z", "P1M", "start", { overflow: "reject" }) // null
intervalFromDurationUtc("2024-01-05T00:00:00Z", "-P10D", "start") // null (inverted span)
intervalFromDurationUtc("invalid", "P1D", "start") // null

Source

utc/interval/intervalFromDurationUtc.ts