@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/calculate/endOfZoned.js

@@ -1,130 +1,44 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidDateTimeUnit } from "../../plain/index.js";
-import { isValidZonedDateTime } from "../validate/index.js";
+import { startOrEndOfZoned } from "../../internal/startOrEndOfZoned.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * 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.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
+ * - Returns the last instant of the real local `unit` containing `value` in its own zone — one nanosecond before the next bucket `floorToZone` would return — so the result is never before `value`. The second pass of New York's repeated fall-back hour ends at 01:59:59.999999999 −05:00, and `Australia/Lord_Howe`'s 90-minute fall-back hour ends in its new offset.
+ * - A transition that reopens the previous local date makes that stretch its own bucket: `America/Goose_Bay`'s 00:01 fall-back on 7 November 2010 re-entered 6 November for 59 minutes, so the day holding `2010-11-06T23:30:00-04:00` ends at 23:59:59.999999999 −04:00.
+ * - A midnight repeated on the same date stays one day: `America/Havana`'s 25-hour 2024-11-03 ends at 23:59:59.999999999 −05:00 from either pass of its repeated first hour.
+ * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
+ *   takes neither. Those ignored options were removed in 1.16.0.
+ * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - Returns "" for invalid input.
+ * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
+ *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
+ *   than the end. Pass that `fractionalSecondDigits` to keep the previous string.
  *
  * @param value zoned ISO 8601 datetime string
- * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param unit date or time unit, singular or plural, to specify the unit for the end
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @returns zoned ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"
+ * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month", { fractionalSecondDigits: 0 }) // "2024-02-29T23:59:59+00:00[UTC]" — the pre-1.16.0 string
+ * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month", { fractionalSecondDigits: 3 }) // "2024-02-29T23:59:59.999+00:00[UTC]"
+ * @example endOfZoned("2024-02-29T12:34:56+01:00[Europe/Berlin]", "hours") // "2024-02-29T12:59:59.999999999+01:00[Europe/Berlin]"
  * @example endOfZoned("invalid", "month") // ""
- * @example 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)
- * @example 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)
- * @example 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)
+ * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour") // "2024-11-03T01:59:59.999999999-05:00[America/New_York]" (the second, repeated 1am is its own hour)
+ * @example endOfZoned("2024-11-03T00:30:00-04:00[America/Havana]", "day") // "2024-11-03T23:59:59.999999999-05:00[America/Havana]" (midnight repeated on the same date: one 25-hour day)
  */
 export function endOfZoned(value, unit, optionsArg) {
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    if (!isValidZonedDateTime(value) || !isValidDateTimeUnit(unit))
-        return "";
     try {
-        const source = Temporal.ZonedDateTime.from(value);
-        let result;
-        switch (unit) {
-            case "year":
-                result = source.with({
-                    month: 12,
-                    day: 31,
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                }, { disambiguation, offset });
-                break;
-            case "month": {
-                const lastDay = Temporal.PlainDate.from({
-                    year: source.year,
-                    month: source.month,
-                    day: 1,
-                }).daysInMonth;
-                result = source.with({
-                    day: lastDay,
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                }, { disambiguation, offset });
-                break;
-            }
-            case "week": {
-                const daysToSubtract = weekStartsOn === "monday"
-                    ? source.dayOfWeek - 1
-                    : source.dayOfWeek % 7;
-                const endOfWeekDate = source
-                    .subtract({ days: daysToSubtract })
-                    .add({ days: 6 });
-                result = endOfWeekDate.with({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                }, { disambiguation, offset });
-                break;
-            }
-            case "day":
-                result = source.with({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                }, { disambiguation, offset });
-                break;
-            case "hour":
-                result = source.with({
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                }, { disambiguation, offset });
-                break;
-            case "minute":
-                result = source.with({ second: 59, millisecond: 999, microsecond: 999, nanosecond: 999 }, { disambiguation, offset });
-                break;
-            case "second":
-                result = source.with({ millisecond: 999, microsecond: 999, nanosecond: 999 }, { disambiguation, offset });
-                break;
-            case "millisecond":
-                result = source.with({ microsecond: 999, nanosecond: 999 }, { disambiguation, offset });
-                break;
-            case "microsecond":
-                result = source.with({ nanosecond: 999 }, { disambiguation, offset });
-                break;
-            case "nanosecond":
-                result = source; // Smallest unit, nothing to set
-                break;
-            default:
-                return "";
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
         }
-        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[unit] || 0);
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
+        return startOrEndOfZoned(value, unit, optionsArg ?? {}, true);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/calculate/getHoursInZonedDay.d.ts

@@ -6,7 +6,13 @@
  *   a whole hour (e.g. `Australia/Lord_Howe`'s 30-minute shift) return a
  *   fractional value instead, such as 23.5 or 24.5.
  * - The calculation is based on the local calendar day of the input, not the
- *   UTC instant.
+ *   UTC instant, and uses Temporal's `hoursInDay`: the span from that day's
+ *   `startOfDay()` to the next day's. A day whose local midnight is skipped
+ *   (e.g. `America/Santiago` on 2024-09-08, which starts at 01:00) is 23 hours.
+ * - The day is the input's calendar date, so it can differ from the bucket
+ *   `startOfZoned(…, "day")` returns where a fall-back re-enters the previous
+ *   date: `America/Goose_Bay` at `2010-11-06T23:30:00-04:00` is in 6 November's
+ *   24 hours here, and in a reopened 59-minute day for `startOfZoned`.
  * - Returns null for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
@@ -17,6 +23,7 @@
  * @example getHoursInZonedDay("2024-11-03T12:00:00-05:00[America/New_York]") // 25
  * @example getHoursInZonedDay("2024-02-29T12:00:00+00:00[UTC]")              // 24
  * @example getHoursInZonedDay("2024-10-06T12:00:00+11:00[Australia/Lord_Howe]") // 23.5
+ * @example getHoursInZonedDay("2024-09-08T12:00:00-03:00[America/Santiago]") // 23 (midnight skipped)
  * @example getHoursInZonedDay("invalid")                                      // null
  */
 export declare function getHoursInZonedDay(value: string): number | null;

package/dist/zoned/calculate/getHoursInZonedDay.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom, zonedHoursInDay } from "../../internal/index.js";
 /**
  * Return the number of hours in the calendar day a zoned datetime falls on.
  *
@@ -8,7 +8,13 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   a whole hour (e.g. `Australia/Lord_Howe`'s 30-minute shift) return a
  *   fractional value instead, such as 23.5 or 24.5.
  * - The calculation is based on the local calendar day of the input, not the
- *   UTC instant.
+ *   UTC instant, and uses Temporal's `hoursInDay`: the span from that day's
+ *   `startOfDay()` to the next day's. A day whose local midnight is skipped
+ *   (e.g. `America/Santiago` on 2024-09-08, which starts at 01:00) is 23 hours.
+ * - The day is the input's calendar date, so it can differ from the bucket
+ *   `startOfZoned(…, "day")` returns where a fall-back re-enters the previous
+ *   date: `America/Goose_Bay` at `2010-11-06T23:30:00-04:00` is in 6 November's
+ *   24 hours here, and in a reopened 59-minute day for `startOfZoned`.
  * - Returns null for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
@@ -19,6 +25,7 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @example getHoursInZonedDay("2024-11-03T12:00:00-05:00[America/New_York]") // 25
  * @example getHoursInZonedDay("2024-02-29T12:00:00+00:00[UTC]")              // 24
  * @example getHoursInZonedDay("2024-10-06T12:00:00+11:00[Australia/Lord_Howe]") // 23.5
+ * @example getHoursInZonedDay("2024-09-08T12:00:00-03:00[America/Santiago]") // 23 (midnight skipped)
  * @example getHoursInZonedDay("invalid")                                      // null
  */
 export function getHoursInZonedDay(value) {
@@ -26,18 +33,7 @@ export function getHoursInZonedDay(value) {
         return null;
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
-        const startOfDay = zonedDateTime.with({
-            hour: 0,
-            minute: 0,
-            second: 0,
-            millisecond: 0,
-            microsecond: 0,
-            nanosecond: 0,
-        });
-        const nextDay = startOfDay.add({ days: 1 });
-        const duration = startOfDay.until(nextDay);
-        return duration.total({ unit: "hours" });
+        return zonedHoursInDay(zonedDateTimeFrom(value));
     }
     catch {
         return null;

package/dist/zoned/calculate/getLocaleZonedDayOfWeek.d.ts

@@ -5,16 +5,20 @@
  * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
  *   a first day for the locale.
- * - Returns `null` if `value` is not a valid zoned ISO datetime or `locale` is unresolvable.
+ * - Returns `null` if `value` is not a valid zoned ISO datetime or `locale` is not a well-formed
+ *   BCP 47 tag (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
  * @returns locale-relative day-of-week index (0–6) or null on invalid input
  *
  * @example getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US") // 0 (Sunday)
  * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "en-US") // 1 (Monday)
  * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "fr-FR") // 0 (Monday)
  * @example getLocaleZonedDayOfWeek("invalid-zoned", "en-US") // null
- * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "not-a-locale") // null
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "not-a-locale-!!") // null
+ * @example getLocaleZonedDayOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["fr-FR", "en-US"]) // 2
  */
-export declare function getLocaleZonedDayOfWeek(value: string, locale: string): number | null;
+export declare function getLocaleZonedDayOfWeek(value: string, locale: string | string[]): number | null;

package/dist/zoned/calculate/getLocaleZonedDayOfWeek.js

@@ -1,5 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { getLocaleFirstDayOfWeek, zonedDateTimeFrom } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 /**
  * Return the locale-relative day-of-week index for a zoned `value`.
@@ -8,17 +7,21 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
  *   a first day for the locale.
- * - Returns `null` if `value` is not a valid zoned ISO datetime or `locale` is unresolvable.
+ * - Returns `null` if `value` is not a valid zoned ISO datetime or `locale` is not a well-formed
+ *   BCP 47 tag (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
  * @returns locale-relative day-of-week index (0–6) or null on invalid input
  *
  * @example getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US") // 0 (Sunday)
  * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "en-US") // 1 (Monday)
  * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "fr-FR") // 0 (Monday)
  * @example getLocaleZonedDayOfWeek("invalid-zoned", "en-US") // null
- * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "not-a-locale") // null
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "not-a-locale-!!") // null
+ * @example getLocaleZonedDayOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["fr-FR", "en-US"]) // 2
  */
 export function getLocaleZonedDayOfWeek(value, locale) {
     if (!isValidZonedDateTime(value))
@@ -27,7 +30,7 @@ export function getLocaleZonedDayOfWeek(value, locale) {
     if (firstDay === null)
         return null;
     try {
-        const zoned = Temporal.ZonedDateTime.from(value);
+        const zoned = zonedDateTimeFrom(value);
         return (zoned.dayOfWeek - firstDay + 7) % 7;
     }
     catch {

package/dist/zoned/calculate/getLocaleZonedEndOfWeek.d.ts

@@ -1,44 +1,38 @@
-import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the week containing `value`, using `locale`'s first
  * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
  *
  * - Resolves the locale's first day of week via
- *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
- *   the last instant of the day.
+ *   `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday-start (so the week ends Sunday) if the runtime's
  *   `weekInfo` data doesn't resolve a first day for the locale.
- * - `disambiguation` controls DST gap/overlap resolution when the
- *   end-of-day 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 end-of-day: "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.
+ * - Returns the last instant of the real local week containing `value` in
+ *   its own zone — one nanosecond before the next week bucket starts — so
+ *   the result is never before `value`.
+ * - The end is written at nanosecond precision by default (`.999999999`), like `endOfZoned`, so the
+ *   string names the end itself. An explicit `fractionalSecondDigits` truncates it, as Temporal's
+ *   `toString` does; pass `{ fractionalSecondDigits: 0 }` to keep the previous whole-second string.
  * - Distinct from `endOfZoned(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.
+ * - Returns "" if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
- * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
+ * @param options optional: fractionalSecondDigits (number, default 9)
  * @returns zoned ISO 8601 string for the end of `value`'s locale-relative week, or "" on invalid input
  *
- * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59+00:00[UTC]" (Saturday)
- * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-03-03T23:59:59+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59.999999999+00:00[UTC]" (Saturday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-03-03T23:59:59.999999999+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US", { fractionalSecondDigits: 0 }) // "2024-03-02T23:59:59+00:00[UTC]" (the pre-1.16.0 string)
  * @example getLocaleZonedEndOfWeek("invalid", "en-US") // ""
- * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale-!!") // ""
+ * @example getLocaleZonedEndOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["fr-FR", "en-US"]) // "2024-05-19T23:59:59.999999999+02:00[Europe/Berlin]"
  */
-export declare function getLocaleZonedEndOfWeek(value: string, locale: string, optionsArg?: {
+export declare function getLocaleZonedEndOfWeek(value: string, locale: string | string[], optionsArg?: {
     fractionalSecondDigits?: FractionalDigit;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): string;

package/dist/zoned/calculate/getLocaleZonedEndOfWeek.js

@@ -1,68 +1,64 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { getLocaleFirstDayOfWeek, zonedDateTimeFrom, zonedUnitEnd, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the end of the week containing `value`, using `locale`'s first
  * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
  *
  * - Resolves the locale's first day of week via
- *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
- *   the last instant of the day.
+ *   `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday-start (so the week ends Sunday) if the runtime's
  *   `weekInfo` data doesn't resolve a first day for the locale.
- * - `disambiguation` controls DST gap/overlap resolution when the
- *   end-of-day 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 end-of-day: "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.
+ * - Returns the last instant of the real local week containing `value` in
+ *   its own zone — one nanosecond before the next week bucket starts — so
+ *   the result is never before `value`.
+ * - The end is written at nanosecond precision by default (`.999999999`), like `endOfZoned`, so the
+ *   string names the end itself. An explicit `fractionalSecondDigits` truncates it, as Temporal's
+ *   `toString` does; pass `{ fractionalSecondDigits: 0 }` to keep the previous whole-second string.
  * - Distinct from `endOfZoned(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.
+ * - Returns "" if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
- * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
+ * @param options optional: fractionalSecondDigits (number, default 9)
  * @returns zoned ISO 8601 string for the end of `value`'s locale-relative week, or "" on invalid input
  *
- * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59+00:00[UTC]" (Saturday)
- * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-03-03T23:59:59+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59.999999999+00:00[UTC]" (Saturday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-03-03T23:59:59.999999999+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US", { fractionalSecondDigits: 0 }) // "2024-03-02T23:59:59+00:00[UTC]" (the pre-1.16.0 string)
  * @example getLocaleZonedEndOfWeek("invalid", "en-US") // ""
- * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale-!!") // ""
+ * @example getLocaleZonedEndOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["fr-FR", "en-US"]) // "2024-05-19T23:59:59.999999999+02:00[Europe/Berlin]"
  */
 export function getLocaleZonedEndOfWeek(value, locale, optionsArg) {
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits ?? 0;
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    if (!isValidZonedDateTime(value))
-        return "";
-    const firstDay = getLocaleFirstDayOfWeek(locale);
-    if (firstDay === null)
-        return "";
     try {
-        const source = Temporal.ZonedDateTime.from(value);
-        const daysToSubtract = (source.dayOfWeek - firstDay + 7) % 7;
-        const endOfWeekDate = source.add({ days: 6 - daysToSubtract });
-        const result = endOfWeekDate.with({
-            hour: 23,
-            minute: 59,
-            second: 59,
-            millisecond: 999,
-            microsecond: 999,
-            nanosecond: 999,
-        }, { disambiguation, offset });
-        return result.toString({ fractionalSecondDigits });
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
+            ? 9
+            : optionsArg.fractionalSecondDigits;
+        if (!isValidZonedDateTime(value))
+            return "";
+        const firstDay = getLocaleFirstDayOfWeek(locale);
+        if (firstDay === null)
+            return "";
+        try {
+            const end = zonedUnitEnd(zonedDateTimeFrom(value), "week", firstDay);
+            return end ? end.toString({ fractionalSecondDigits }) : "";
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/calculate/getLocaleZonedStartOfWeek.d.ts

@@ -1,44 +1,36 @@
-import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+import type { FractionalDigit } from "../../types/index.js";
 /**
  * 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.
+ *   `Intl.Locale.prototype.weekInfo`.
  * - 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.
+ * - Returns the real start of the local week containing `value` in its own
+ *   zone — the same kind of bucket `floorToZone` uses — so the result is
+ *   never after `value`. A week whose first midnight was skipped starts at
+ *   its first real instant.
  * - 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.
+ * - Returns "" if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
- * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
+ * @param options optional: fractionalSecondDigits (number)
  * @returns zoned ISO 8601 string for the start of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
  * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-02-26T00:00:00+00:00[UTC]" (Monday)
+ * @example getLocaleZonedStartOfWeek("2024-09-11T12:00:00-03:00[America/Santiago]", "en-US") // "2024-09-08T01:00:00-03:00[America/Santiago]" (that Sunday's midnight was skipped)
  * @example getLocaleZonedStartOfWeek("invalid", "en-US") // ""
- * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale-!!") // ""
+ * @example getLocaleZonedStartOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["en-US", "fr-FR"]) // "2024-05-12T00:00:00+02:00[Europe/Berlin]"
  */
-export declare function getLocaleZonedStartOfWeek(value: string, locale: string, optionsArg?: {
+export declare function getLocaleZonedStartOfWeek(value: string, locale: string | string[], optionsArg?: {
     fractionalSecondDigits?: FractionalDigit;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): string;