subtractZoned

Signature

subtractZoned(value: string, units: Partial<Record<keyof DurationLike, number>>, optionsArg?: { disambiguation?: "compatible" | "earlier" | "later" | "reject" | undefined; overflow?: "reject" | "constrain" | undefined; }): string

Subtract a temporal amount from a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.

• Uses Temporal.ZonedDateTime.subtract to subtract duration.
• Validates duration units and values.
• Accepts an RFC 9557 calendar-annotated zoned string (as convertZonedToCalendar writes it, e.g. "2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]"), not just a bare ISO string (E7, issue #152). Calendar-unit arithmetic (“subtract 1 month”) resolves against that calendar and the DST rules of the zone, in one operation; the result carries the same calendar annotation. A bare ISO string is the "iso8601" calendar and returns a bare ISO string.
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the [u-ca=<id>] annotation after the zone, canonical calendar ids); see isValidCalendarZonedDateTime.
• Follows Temporal’s AddZonedDateTime: the date portion of the duration (years, months, weeks, days) moves the wall-clock date, then the time portion (hours and smaller) is subtracted in exact time. disambiguation applies ONLY to the intermediate wall-clock date-time after the date portion, exactly as Temporal’s GetEpochNanosecondsFor resolves it. It never re-resolves the exact-time result.
• Compatibility: before 1.16.0 a date portion landing in a spring-forward gap was always moved forward, whatever disambiguation said, so “earlier” matched “compatible” and “reject” did not fail. Pass “compatible” (or omit it) to keep the forward result.
• Compatibility: before 1.16.0 a non-”compatible” disambiguation re-resolved the final wall clock (so - { minutes: 10 } from 2024-11-03T01:30:00-05:00[America/New_York] with “earlier” returned 01:20:00-04:00, 70 minutes before the input in exact time, instead of 01:20:00-05:00). To get that value, re-resolve the result’s wall clock: setZoned(result, { hour, minute, second }, { disambiguation, offset: "ignore" }).
• There is no offset option (removed in 1.16.0): the intermediate wall clock is resolved from a plain date-time, which has no UTC offset for it to act on (Temporal PlainDateTime#toZonedDateTime reads only disambiguation).
• Returns "" for invalid input.

Parameters

Parameter	Type	Description
value	string	ISO 8601 zoned datetime string, optionally calendar-annotated
units	Partial<Record<keyof DurationLike, number>>	Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract

Options

optionsArg

optional settings for resolving a DST gap or overlap and an out-of-range date

Option	Type	Default	Description
disambiguation?	"compatible" | "earlier" | "later" | "reject" (Disambiguation)	"compatible", Temporal’s default.	How the intermediate wall-clock date-time, reached after the date portion of the duration is applied, resolves when it falls in a DST gap or overlap. In a fall-back overlap "compatible" and "earlier" take the earlier instant and "later" the later one; in a spring-forward gap "compatible" and "later" move the wall clock forward by the gap length and "earlier" back by it. "reject" returns "" for both, and a time-only duration ignores the option.
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	What happens when the result names a day its month does not have, such as subtracting 1 month from 31 March. "constrain" clamps to the last valid day; "reject" returns "".

Returns

zoned ISO 8601 string on success, or "" on invalid input

Related types

• DateTimeDurationUnit
• Disambiguation
• Overflow

Examples

import { subtractZoned } from "@northguild/gmt/zoned/calculate";

subtractZoned("2024-03-10T12:00:00-04:00[America/New_York]", { days: 5 }) // "2024-03-05T12:00:00-05:00[America/New_York]"

value

output

 

Source

zoned/calculate/subtractZoned.ts