intervalFromDurationDateTime

Signature

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

import { intervalFromDurationDateTime } from "@northguild/gmt/plain/interval";

Construct a datetime 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.
• Uses Temporal.PlainDateTime.prototype.add/.subtract, so calendar units (years/months/weeks) resolve against value itself — no separate relativeTo is needed, unlike addDuration.
• A negative duration (e.g. "-P1D") can invert the computed span; returns null when that happens, mirroring intervalIntersectionDateTime’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 PlainDateTime string
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, or null on invalid input

Related types

• Overflow

Examples

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

Source

plain/interval/intervalFromDurationDateTime.ts