Skip to content
@northguild/gmt

startOfZoned

Playground

call
result 

Signature

Section titled “Signature”
startOfZoned(value: string, unit: DateTimeUnit, optionsArg?: { weekStartsOn?: "monday" | "sunday"; fractionalSecondDigits?: FractionalDigit; disambiguation?: Disambiguation; offset?: Offset; }): string
import { startOfZoned } from "@northguild/gmt/zoned/calculate";

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

  • Converts to ZonedDateTime, sets to start 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

Section titled “Parameters”
Parameter Type Description
value string zoned ISO 8601 datetime string
unit DateTimeUnit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the start

Options

Section titled “Options”

options

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

Returns

Section titled “Returns”

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

Section titled “Related types”

Examples

Section titled “Examples”
startOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-01T00:00:00+00:00[UTC]"
startOfZoned("invalid", "month") // ""
startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "earlier" }) // "2024-11-03T01:00:00-04:00[America/New_York]" (source sits in the second, repeated 1am of the fall-back overlap; "earlier" resolves start-of-hour to the first (EDT) pass)
startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "reject" }) // "" (same overlap; "reject" throws because start-of-hour is ambiguous between the two 1am instants)
startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-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

Section titled “Source”

zoned/calculate/startOfZoned.ts