getLocaleZonedStartOfWeek

Signature

getLocaleZonedStartOfWeek(value: string, locale: string, optionsArg?: { fractionalSecondDigits?: FractionalDigit; disambiguation?: Disambiguation; offset?: Offset; }): string

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

Return the start of the week containing value, using locale’s

• first day of week (e.g. en-US: Sunday, fr-FR: Monday).
• Resolves the locale’s first day of week via Intl.Locale.prototype.weekInfo, then resets the local time-of-day to midnight.
• Falls back to Monday if the runtime’s weekInfo data doesn’t resolve a first day for the locale.
• disambiguation controls DST gap/overlap resolution when the midnight reset 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 resetting to midnight: “prefer” (Temporal’s own default — keeps the source offset whenever still valid, which makes disambiguation inert for almost every case here), “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.
• Distinct from startOfZoned(value, "week", { weekStartsOn }), which takes an explicit ISO-biased weekStartsOn option instead of deriving it from a locale.
• Returns “” if value or locale is invalid.

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
locale	string	BCP 47 locale tag (e.g. “en-US”, “fr-FR”)

Options

options

Option	Type	Default
fractionalSecondDigits?	FractionalDigit	—
disambiguation?	Disambiguation	—
offset?	Offset	—

Returns

zoned ISO 8601 string for the start of value’s locale-relative week, or “” on invalid input

Related types

• Disambiguation
• FractionalDigit
• Offset

Examples

getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-02-26T00:00:00+00:00[UTC]" (Monday)
getLocaleZonedStartOfWeek("invalid", "en-US") // ""
getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""

Source

zoned/calculate/getLocaleZonedStartOfWeek.ts