Skip to content
@northguild/gmt

addZoned

Playground

call
result 

Signature

Section titled “Signature”
addZoned(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, optionsArg?: { disambiguation?: Disambiguation; offset?: Offset; overflow?: Overflow; }): string
import { addZoned } from "@northguild/gmt/zoned/calculate";

Add a temporal amount to a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.

  • Uses Temporal.ZonedDateTime.add to add duration.
  • Validates duration units and values.
  • Accepts a GMT calendar-annotated zoned string (as produced by convertZonedToCalendar, e.g. "5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"), not just a bare ISO string — E7 (issue #152). Calendar-unit arithmetic (“add 1 month”) resolves against that calendar (a Hebrew leap month, an Ethiopic Pagumen, a Japanese era change) and the DST rules of the zone, in one operation. The calendar tag, the era, the wall time and the UTC offset are all re-derived from the result, never copied from the input — Hebrew Adar I 15 in America/New_York +1 month moves both the month (Adar I -> Adar) and the offset (-05:00 -> -04:00). A bare ISO string is unaffected — always treated as, and always returns, "gregorian".
  • disambiguation controls DST resolution ONLY when the arithmetic result lands on an ambiguous local time from a fall-back (DST-end) overlap: “compatible” (default), “earlier”, “later”, or “reject” (throws, resulting in “”). Has no effect when the result lands in a spring-forward (DST-start) gap — Temporal’s arithmetic always resolves gap landings unambiguously (by advancing past the gap) before disambiguation is ever evaluated.
  • offset (“prefer” | “use” | “ignore” (default) | “reject”) is accepted for API consistency with sibling zoned-construction functions (see startOfZoned, endOfZoned, etc.) but has no effect here: the internal rebuild step reconstructs from a plain datetime string with no UTC offset embedded, so there is never a stored offset for offset to prefer/use/ignore/reject against. disambiguation is the only option that affects this function’s output.
  • overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. adding 1 month to Jan 31: “constrain” clamps to Feb 29/28, “reject” throws (resulting in “”).
  • Returns “” for invalid input.

Parameters

Section titled “Parameters”
Parameter Type Description
value string ISO 8601 zoned datetime string, optionally calendar-annotated
units Partial&lt;Record&lt;DateTimeDurationUnit, number&gt;&gt; Partial<Record<DateTimeDurationUnit, number>> object specifying units to add

Options

Section titled “Options”

options

Option Type Default
disambiguation? Disambiguation —
offset? Offset —
overflow? Overflow —

Returns

Section titled “Returns”

zoned ISO 8601 string on success, or “” on invalid input

Section titled “Related types”

Examples

Section titled “Examples”
addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
addZoned("invalid", { days: 1 }) // ""
addZoned("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", { months: 1 }) // "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]" (Adar I -> Adar, EST -> EDT in one call)
addZoned("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]", { days: 1 }) // "0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]" (era re-derived, not copied)
addZoned("7517-12-30T00:30:00-04:00[u-ca=ethiopic-amete-alem][America/Santiago]", { months: 1 }, { overflow: "reject" }) // "" (day 30 does not exist in the 5-day Pagumen)
addZoned("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", { days: 1 }) // "" (Temporal's segment ordering is not GMT's grammar)
addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "later" }) // "2024-11-03T01:30:00-05:00[America/New_York]" (fall-back overlap resolved; default "compatible" would return the -04:00 instant instead)
addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (fall-back overlap rejected)
addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "2024-03-10T03:30:00-04:00[America/New_York]" (spring-forward gap — disambiguation has no effect, arithmetic already advanced past it, so "reject" does not throw here)
addZoned("2024-01-31T12:00:00-05:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""

Source

Section titled “Source”

zoned/calculate/addZoned.ts