endOfZoned

Signature

endOfZoned(value: string, unit: any, optionsArg?: { weekStartsOn?: "monday" | "sunday"; fractionalSecondDigits?: FractionalDigit; disambiguation?: Disambiguation; offset?: Offset; }): string

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

Return the end of the specified date-time unit for a given zoned ISO 8601 datetime string.

• Converts to ZonedDateTime, sets to end of unit, converts back to string.
• Supports: “year”, “month”, “week”, “day”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”.
• disambiguation controls DST gap/overlap resolution when the boundary jump lands on an ambiguous local time: “compatible” (default, matches Temporal’s default), “earlier”, “later”, or “reject” (throws, resulting in “”).
• offset controls whether the source’s existing UTC offset is kept when computing the new boundary: “prefer” (Temporal’s own default — keeps the source offset whenever still valid, which makes disambiguation inert for almost every case here since the source offset is nearly always still valid after a same-day field reset), “use”, “ignore” (this function’s default — always recomputes from time zone + local time, discarding the stale offset; this is what makes disambiguation actually take effect), or “reject” (throws if the source offset is invalid for the new fields, independent of disambiguation). Leave offset at its default unless you specifically need Temporal’s raw .with() semantics.
• Returns “” for invalid input.

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
unit	any	Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the end

Options

options

Option	Type	Default
weekStartsOn?	"monday" | "sunday"	—
fractionalSecondDigits?	FractionalDigit	—
disambiguation?	Disambiguation	—
offset?	Offset	—

Returns

zoned ISO 8601 string representing the end of the specified unit, or “” on invalid input

Related types

• Disambiguation
• FractionalDigit
• Offset

Examples

endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"
endOfZoned("invalid", "month") // ""
endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "earlier" }) // "2024-11-03T01:59:59-04:00[America/New_York]" (source sits in the second, repeated 1am of the fall-back overlap; "earlier" resolves end-of-hour to the first (EDT) pass)
endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "reject" }) // "" (same overlap; "reject" throws because end-of-hour is ambiguous between the two 1am instants)
endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:59:59-05:00[America/New_York]" (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)

Source

zoned/calculate/endOfZoned.ts