@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/freeTimeLedger.d.ts

@@ -0,0 +1,93 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { type ResolvedBusinessCalendar } from "./businessCalendar.js";
+/**
+ * Local days a free-time walk may visit before giving up: the same cap as `bucketRange`. A
+ * valid business calendar leaves at least one working day a week, so a working-day count needs
+ * at most about seven local days per free or chargeable day. A walk that runs out answers with
+ * the sentinel, never a partial ledger.
+ */
+export declare const MAX_WALKED_DAYS = 10000;
+/**
+ * The tariff terms reduced to what the walk reads. `calendar` is the working-day calendar free
+ * days are counted against, `null` on the calendar basis; `chargeCalendar` is the one charged days
+ * are counted against, `null` when every local day after expiry is charged.
+ */
+export type FreeTimeTerms = {
+    timeZone: string;
+    firstDay: "eventDay" | "nextDay";
+    calendar: ResolvedBusinessCalendar | null;
+    chargeCalendar: ResolvedBusinessCalendar | null;
+};
+/**
+ * Read a `FreeTimeOptions` bag, or `null` when it is not one: a non-object, an unknown `basis`
+ * or `firstDay`, a missing `firstDay` (no default: the two conventions differ by a day of
+ * charges), an invalid `timeZone`, or a `"working"` basis without a valid `BusinessCalendar`.
+ * The `calendar` is read only when a basis that needs it is `"working"`.
+ *
+ * With `readChargeBasis`, `chargeBasis` is required too, and has no default for the same reason:
+ * where free time is in working days, tariffs mostly charge every calendar day after it, but some
+ * tariffs charge working days only, and the two differ by every closed day after expiry.
+ */
+export declare function parseFreeTimeTerms(options: unknown, readChargeBasis?: boolean): FreeTimeTerms | null;
+/** A whole number of free days no smaller than `minimum`, or `null`. */
+export declare function parseFreeDays(freeDays: unknown, minimum: 0 | 1): number | null;
+/**
+ * Read a `tiers` option: omitted means no bands, otherwise a strictly ascending list of positive
+ * safe whole chargeable-day ordinals, each the last day of its band, with no holes. Anything
+ * else is `null`.
+ */
+export declare function parseTiers(tiers: unknown): number[] | null;
+/**
+ * Split `chargeable` days into the bands `tiers` describes: `[5, 10]` is days 1–5, 6–10 and 11
+ * onward. Every band is listed, an empty one with `days: 0`, so a caller's rate table lines up
+ * by index; the last band is always open (`to: null`).
+ */
+export declare function bandsByTier(tiers: number[], chargeable: number): {
+    from: number;
+    to: number | null;
+    days: number;
+}[];
+/** One local date of the terminal: its first instant, and its ISO label. */
+export interface LedgerDay {
+    start: Temporal.ZonedDateTime;
+    date: string;
+    /**
+     * True when the date began before the first instant Temporal represents, so `start` is the
+     * clock start standing in for it. Such a start is never output: it can only anchor the walk.
+     */
+    clamped?: boolean;
+}
+/** What `walkFreeTime` returns: the free days, the expiry, and what the dwell used and owes. */
+export interface FreeTimeLedger {
+    /** The free days in order, exactly `freeDays` of them. */
+    free: LedgerDay[];
+    /** The first instant of the local day after the last free day; with no free days, of day one. */
+    expiresAt: Temporal.ZonedDateTime;
+    /** Free days the half-open dwell `[clockStart, clockEnd)` touched; `0` with no `clockEnd`. */
+    used: number;
+    /** Counted days from `expiresAt` that the dwell touched, in order; empty with no `clockEnd`. */
+    charged: LedgerDay[];
+}
+/**
+ * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ *
+ * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
+ * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
+ * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
+ * charged days are counted against their own terms: on a working basis a weekend day or holiday is
+ * visited but not counted; on a calendar basis every day counts. The day of the event is neither
+ * free nor charged under `"nextDay"`.
+ *
+ * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
+ *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
+ *   start of the first counted day.
+ * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
+ *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
+ *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
+ *   on `chargeCalendar`.
+ * - An event day that began before the first representable instant is still walked from the
+ *   clock start; only an expiry that would be that unrepresentable start is refused.
+ * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
+ *   boundary cannot be found, or when the expiry lies outside the representable range.
+ */
+export declare function walkFreeTime(clockStart: Temporal.ZonedDateTime, freeDays: number, terms: FreeTimeTerms, clockEnd?: Temporal.ZonedDateTime): FreeTimeLedger | null;

package/dist/internal/freeTimeLedger.js

@@ -0,0 +1,262 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+import { isBusinessDate, parseBusinessCalendar, } from "./businessCalendar.js";
+import { isObject } from "./isObject.js";
+import { nextZonedBucketStart, zonedUnitStart } from "./zonedBucket.js";
+/**
+ * Local days a free-time walk may visit before giving up: the same cap as `bucketRange`. A
+ * valid business calendar leaves at least one working day a week, so a working-day count needs
+ * at most about seven local days per free or chargeable day. A walk that runs out answers with
+ * the sentinel, never a partial ledger.
+ */
+export const MAX_WALKED_DAYS = 10_000;
+/**
+ * Buckets stepped over while looking for a later date. A fall-back that re-enters the previous
+ * date (`America/Goose_Bay`, 2010-11-07 00:01 back into the 6th) opens a one-minute 7 November
+ * bucket, then a 6 November one, then 7 November again: two buckets in a row whose date is not
+ * later than the day being left. One transition can do no more than that, so eight is a
+ * generous bound.
+ */
+const MAX_REVISITED_BUCKETS = 8;
+/** `parseFreeTimeTerms` without the guard; every read of `options` happens here. */
+function readFreeTimeTerms(options, readChargeBasis = false) {
+    if (!isObject(options)) {
+        return null;
+    }
+    const { basis, chargeBasis, firstDay, timeZone, calendar } = options;
+    const isBasis = (value) => value === "calendar" || value === "working";
+    if (!isBasis(basis)) {
+        return null;
+    }
+    if (readChargeBasis && !isBasis(chargeBasis)) {
+        return null;
+    }
+    if (firstDay !== "eventDay" && firstDay !== "nextDay") {
+        return null;
+    }
+    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    const needsCalendar = basis === "working" || (readChargeBasis && chargeBasis === "working");
+    const resolved = needsCalendar ? parseBusinessCalendar(calendar) : null;
+    if (needsCalendar && resolved === null) {
+        return null;
+    }
+    return {
+        timeZone,
+        firstDay,
+        calendar: basis === "working" ? resolved : null,
+        chargeCalendar: readChargeBasis && chargeBasis === "working" ? resolved : null,
+    };
+}
+/**
+ * Read a `FreeTimeOptions` bag, or `null` when it is not one: a non-object, an unknown `basis`
+ * or `firstDay`, a missing `firstDay` (no default: the two conventions differ by a day of
+ * charges), an invalid `timeZone`, or a `"working"` basis without a valid `BusinessCalendar`.
+ * The `calendar` is read only when a basis that needs it is `"working"`.
+ *
+ * With `readChargeBasis`, `chargeBasis` is required too, and has no default for the same reason:
+ * where free time is in working days, tariffs mostly charge every calendar day after it, but some
+ * tariffs charge working days only, and the two differ by every closed day after expiry.
+ */
+export function parseFreeTimeTerms(options, readChargeBasis = false) {
+    try {
+        return readFreeTimeTerms(options, readChargeBasis);
+    }
+    catch {
+        // Never throws (Core Rule 3): a Proxy or getter that throws on access is invalid input.
+        return null;
+    }
+}
+/** A whole number of free days no smaller than `minimum`, or `null`. */
+export function parseFreeDays(freeDays, minimum) {
+    return typeof freeDays === "number" &&
+        Number.isSafeInteger(freeDays) &&
+        freeDays >= minimum
+        ? freeDays
+        : null;
+}
+/**
+ * Read a `tiers` option: omitted means no bands, otherwise a strictly ascending list of positive
+ * safe whole chargeable-day ordinals, each the last day of its band, with no holes. Anything
+ * else is `null`.
+ */
+export function parseTiers(tiers) {
+    if (tiers === undefined) {
+        return [];
+    }
+    if (!Array.isArray(tiers)) {
+        return null;
+    }
+    // `Array.from` fills holes with `undefined`, which the check below rejects; `every` alone
+    // would skip them and let `[5, , ]` through to a `NaN` band.
+    const items = Array.from(tiers);
+    const ascending = items.every((tier, index) => typeof tier === "number" &&
+        Number.isSafeInteger(tier) &&
+        tier >= 1 &&
+        (index === 0 || tier > items[index - 1]));
+    return ascending ? items : null;
+}
+/**
+ * Split `chargeable` days into the bands `tiers` describes: `[5, 10]` is days 1–5, 6–10 and 11
+ * onward. Every band is listed, an empty one with `days: 0`, so a caller's rate table lines up
+ * by index; the last band is always open (`to: null`).
+ */
+export function bandsByTier(tiers, chargeable) {
+    const bands = [];
+    let from = 1;
+    for (const to of tiers) {
+        bands.push({
+            from,
+            to,
+            days: Math.max(0, Math.min(chargeable, to) - from + 1),
+        });
+        from = to + 1;
+    }
+    bands.push({ from, to: null, days: Math.max(0, chargeable - from + 1) });
+    return bands;
+}
+/** The local day holding `zoned`, or `null` when its start cannot be found. */
+function localDayOf(zoned) {
+    let start;
+    try {
+        start = zonedUnitStart(zoned, "day");
+    }
+    catch (error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        // The event day began before Temporal's first instant (-271821-04-20T00:00Z in a zone west
+        // of UTC). Its date is still known, and every later day boundary is representable, so the
+        // clock start anchors the walk in its place.
+        return {
+            start: zoned,
+            date: zoned.toPlainDate().toString(),
+            clamped: true,
+        };
+    }
+    return start === null
+        ? null
+        : { start, date: start.toPlainDate().toString() };
+}
+/**
+ * The first local day after `day` whose date is later than `day`'s. A bucket that re-enters an
+ * earlier or equal date is folded into the day already laid out: a clock that starts in the
+ * one-minute first pass of Goose Bay's 7 November must not free or charge the 6th, and
+ * `countZonedLocalDates` counts a re-entered date once. `undefined` when the next day starts
+ * past the last representable instant, `null` when the walk gives up.
+ */
+function nextLocalDay(day) {
+    const current = day.start.toPlainDate();
+    let cursor = day.start;
+    for (let i = 0; i < MAX_REVISITED_BUCKETS; i++) {
+        let next;
+        try {
+            next = nextZonedBucketStart(cursor, "day");
+        }
+        catch (error) {
+            if (error instanceof RangeError)
+                return undefined;
+            throw error;
+        }
+        if (next === null) {
+            return null;
+        }
+        const date = next.toPlainDate();
+        if (Temporal.PlainDate.compare(date, current) > 0) {
+            return { start: next, date: date.toString() };
+        }
+        cursor = next;
+    }
+    return null;
+}
+/**
+ * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ *
+ * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
+ * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
+ * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
+ * charged days are counted against their own terms: on a working basis a weekend day or holiday is
+ * visited but not counted; on a calendar basis every day counts. The day of the event is neither
+ * free nor charged under `"nextDay"`.
+ *
+ * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
+ *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
+ *   start of the first counted day.
+ * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
+ *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
+ *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
+ *   on `chargeCalendar`.
+ * - An event day that began before the first representable instant is still walked from the
+ *   clock start; only an expiry that would be that unrepresentable start is refused.
+ * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
+ *   boundary cannot be found, or when the expiry lies outside the representable range.
+ */
+export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
+    // The dwell's last instant, one nanosecond before the exit; a zero-length dwell is its own point.
+    const last = clockEnd === undefined
+        ? undefined
+        : Temporal.ZonedDateTime.compare(clockStart, clockEnd) < 0
+            ? clockEnd.subtract({ nanoseconds: 1 })
+            : clockEnd;
+    const touched = (day) => last !== undefined && Temporal.ZonedDateTime.compare(day.start, last) <= 0;
+    const counts = (day) => terms.calendar === null ||
+        isBusinessDate(day.start.toPlainDate(), terms.calendar);
+    const charges = (day) => terms.chargeCalendar === null ||
+        isBusinessDate(day.start.toPlainDate(), terms.chargeCalendar);
+    const free = [];
+    const charged = [];
+    let used = 0;
+    let expiresAt = null;
+    let expiryPending = false;
+    let skipEventDay = terms.firstDay === "nextDay";
+    let day = localDayOf(clockStart);
+    if (day === null) {
+        return null;
+    }
+    // One more visit than the cap: the day after the last touched one is what ends the walk.
+    for (let i = 0; i <= MAX_WALKED_DAYS; i++) {
+        const eventDaySkipped = skipEventDay;
+        const counted = !skipEventDay && counts(day);
+        skipEventDay = false;
+        if (expiryPending) {
+            expiresAt = day.start;
+            expiryPending = false;
+        }
+        else if (expiresAt === null && counted) {
+            if (freeDays === 0) {
+                // With no free time the expiry is day one's start, which must be a real instant.
+                if (day.clamped)
+                    return null;
+                expiresAt = day.start;
+            }
+            else {
+                free.push(day);
+                if (touched(day))
+                    used++;
+                expiryPending = free.length === freeDays;
+            }
+        }
+        if (expiresAt !== null) {
+            // Free time has ended; with no clock end there is nothing more to lay out.
+            if (last === undefined) {
+                return { free, expiresAt, used, charged };
+            }
+            if (Temporal.ZonedDateTime.compare(day.start, last) > 0) {
+                return { free, expiresAt, used, charged };
+            }
+            // The day of the event under `nextDay` is never charged: free time has not started on it.
+            if (!eventDaySkipped && charges(day))
+                charged.push(day);
+        }
+        const next = nextLocalDay(day);
+        if (next === undefined) {
+            // No representable day follows: free time can still be laid out only if it has ended.
+            return expiresAt === null ? null : { free, expiresAt, used, charged };
+        }
+        if (next === null) {
+            return null;
+        }
+        day = next;
+    }
+    return null;
+}

package/dist/internal/getLocaleFirstDayOfWeek.d.ts

@@ -1,11 +1,14 @@
+import type { LocalesArgument } from "./resolveLocale.js";
 /**
  * Resolve the ISO day-of-week number (1 = Monday .. 7 = Sunday) that a
- * locale considers the first day of the week, via
- * `Intl.Locale.prototype.weekInfo`.
+ * locale considers the first day of the week, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
  * - Falls back to `1` (Monday, matching GMT's existing ISO default in
- *   `startOfDate`/`startOfZoned`) if `weekInfo` is unavailable on the
- *   runtime (older engines) or unresolvable for the given locale.
+ *   `startOfDate`/`startOfZoned`) if the runtime exposes no week data or
+ *   none for the given locale.
  */
-export declare function getLocaleFirstDayOfWeek(locale: string): number | null;
+export declare function getLocaleFirstDayOfWeek(locale: LocalesArgument): number | null;

package/dist/internal/getLocaleFirstDayOfWeek.js

@@ -1,20 +1,19 @@
-// `Intl.Locale.prototype.weekInfo`'s ambient type augmentation lives in
-// `getLocaleWeekendDays.ts` (TS's lib.d.ts doesn't declare it as of TS 5.9).
-// Declared once there; this file relies on that global augmentation rather
-// than redeclaring it.
+import { localeWeekInfo } from "./localeWeekInfo.js";
 /**
  * Resolve the ISO day-of-week number (1 = Monday .. 7 = Sunday) that a
- * locale considers the first day of the week, via
- * `Intl.Locale.prototype.weekInfo`.
+ * locale considers the first day of the week, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
  * - Falls back to `1` (Monday, matching GMT's existing ISO default in
- *   `startOfDate`/`startOfZoned`) if `weekInfo` is unavailable on the
- *   runtime (older engines) or unresolvable for the given locale.
+ *   `startOfDate`/`startOfZoned`) if the runtime exposes no week data or
+ *   none for the given locale.
  */
 export function getLocaleFirstDayOfWeek(locale) {
     try {
-        const weekInfo = new Intl.Locale(locale).weekInfo;
+        const weekInfo = localeWeekInfo(locale);
         if (!weekInfo || typeof weekInfo.firstDay !== "number") {
             return 1;
         }

package/dist/internal/getLocaleWeekYearBounds.d.ts

@@ -1,19 +1,27 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 export interface LocaleWeekYearBounds {
     weekYear: number;
-    /** First day of `weekYear`'s week 1. */
-    start: Temporal.PlainDate;
-    /** First day of `weekYear + 1`'s week 1 — an exclusive upper bound. */
-    end: Temporal.PlainDate;
+    /** Days from the source date to the first day of `weekYear`'s week 1 (0 or negative). */
+    startOffsetDays: number;
+    /** Days from the source date to the first day of `weekYear + 1`'s week 1 — exclusive (positive). */
+    endOffsetDays: number;
 }
 /**
  * Resolve the locale week-numbering year `date` belongs to, and the
- * `[start, end)` bounds (in calendar days) of that week-year, given a
+ * `[start, end)` bounds of that week-year as day offsets from `date`, given a
  * locale's `firstDay` (1 = Monday .. 7 = Sunday) and `minimalDays` (the
  * minimum January days a week must have to count as week 1) — both from
  * `Intl.Locale.prototype.weekInfo`.
  *
- * Shared by `getLocaleWeekYear` (the year itself) and
- * `getWeeksInLocaleWeekYear` (the week count, derived from `start`/`end`).
+ * Pure day arithmetic on `date`'s ISO fields: no neighbouring year's week 1 is
+ * built as a date, because it can lie outside the representable range (week 1
+ * of -271821 starts before `-271821-04-19`, week 1 of +275761 after
+ * `+275760-09-13`) while `date` itself and its week-year are valid.
+ *
+ * Shared by `getLocaleWeekYear` (the year itself),
+ * `getWeeksInLocaleWeekYear` and `getWeeksInYear` (the week count, derived
+ * from the offsets).
+ *
+ * @example getLocaleWeekYearBounds(Temporal.PlainDate.from("2024-12-30"), 1, 4) // { weekYear: 2025, startOffsetDays: 0, endOffsetDays: 364 }
  */
-export declare function getLocaleWeekYearBounds(date: Temporal.PlainDate, firstDay: number, minimalDays: number): LocaleWeekYearBounds;
+export declare function getLocaleWeekYearBounds(date: Pick<Temporal.PlainDate, "year" | "dayOfYear" | "dayOfWeek">, firstDay: number, minimalDays: number): LocaleWeekYearBounds;

package/dist/internal/getLocaleWeekYearBounds.js

@@ -1,44 +1,63 @@
-import { Temporal } from "@js-temporal/polyfill";
+/** Proleptic Gregorian leap year (ISO 8601-1:2019 §3.1.1.4 and §4.3.4). */
+function daysInIsoYear(year) {
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return leap ? 366 : 365;
+}
+/** Weekday (1 = Monday .. 7 = Sunday) `days` after a day whose weekday is `dayOfWeek`. */
+function shiftWeekday(dayOfWeek, days) {
+    return ((((dayOfWeek - 1 + days) % 7) + 7) % 7) + 1;
+}
 // Week 1 of a locale week-year always contains January's `minimalDays`-th
 // day: the week starting on/before Jan 1 has k days in January, where k
 // ranges from `minimalDays` (the threshold to still count as week 1) up
 // to 7 (a full week starting exactly on Jan 1) — so day `minimalDays` of
 // January falls within that range no matter which end it lands on. This
 // generalizes ISO 8601's own rule (minimalDays = 4, so week 1 always
-// contains Jan 4).
-function startOfWeek1(year, firstDay, minimalDays) {
-    const anchor = Temporal.PlainDate.from({
-        year,
-        month: 1,
-        day: minimalDays,
-    });
-    const daysSinceFirstDay = (anchor.dayOfWeek - firstDay + 7) % 7;
-    return anchor.subtract({ days: daysSinceFirstDay });
+// contains Jan 4). Returned as days from January 1, given its weekday.
+function week1StartFromJanuary1(january1DayOfWeek, firstDay, minimalDays) {
+    const anchorDayOfWeek = shiftWeekday(january1DayOfWeek, minimalDays - 1);
+    return minimalDays - 1 - ((anchorDayOfWeek - firstDay + 7) % 7);
 }
 /**
  * Resolve the locale week-numbering year `date` belongs to, and the
- * `[start, end)` bounds (in calendar days) of that week-year, given a
+ * `[start, end)` bounds of that week-year as day offsets from `date`, given a
  * locale's `firstDay` (1 = Monday .. 7 = Sunday) and `minimalDays` (the
  * minimum January days a week must have to count as week 1) — both from
  * `Intl.Locale.prototype.weekInfo`.
  *
- * Shared by `getLocaleWeekYear` (the year itself) and
- * `getWeeksInLocaleWeekYear` (the week count, derived from `start`/`end`).
+ * Pure day arithmetic on `date`'s ISO fields: no neighbouring year's week 1 is
+ * built as a date, because it can lie outside the representable range (week 1
+ * of -271821 starts before `-271821-04-19`, week 1 of +275761 after
+ * `+275760-09-13`) while `date` itself and its week-year are valid.
+ *
+ * Shared by `getLocaleWeekYear` (the year itself),
+ * `getWeeksInLocaleWeekYear` and `getWeeksInYear` (the week count, derived
+ * from the offsets).
+ *
+ * @example getLocaleWeekYearBounds(Temporal.PlainDate.from("2024-12-30"), 1, 4) // { weekYear: 2025, startOffsetDays: 0, endOffsetDays: 364 }
  */
 export function getLocaleWeekYearBounds(date, firstDay, minimalDays) {
-    let weekYear = date.year;
-    let start = startOfWeek1(weekYear, firstDay, minimalDays);
-    if (Temporal.PlainDate.compare(date, start) < 0) {
-        weekYear -= 1;
-        start = startOfWeek1(weekYear, firstDay, minimalDays);
+    const year = date.year;
+    const january1 = 1 - date.dayOfYear;
+    const january1DayOfWeek = shiftWeekday(date.dayOfWeek, january1);
+    const weekYearStart = (yearJanuary1) => yearJanuary1 +
+        week1StartFromJanuary1(shiftWeekday(january1DayOfWeek, yearJanuary1 - january1), firstDay, minimalDays);
+    const nextJanuary1 = january1 + daysInIsoYear(year);
+    const start = weekYearStart(january1);
+    const nextStart = weekYearStart(nextJanuary1);
+    if (start > 0) {
+        return {
+            weekYear: year - 1,
+            startOffsetDays: weekYearStart(january1 - daysInIsoYear(year - 1)),
+            endOffsetDays: start,
+        };
     }
-    else {
-        const nextStart = startOfWeek1(weekYear + 1, firstDay, minimalDays);
-        if (Temporal.PlainDate.compare(date, nextStart) >= 0) {
-            weekYear += 1;
-            start = nextStart;
-        }
+    if (nextStart <= 0) {
+        return {
+            weekYear: year + 1,
+            startOffsetDays: nextStart,
+            endOffsetDays: weekYearStart(nextJanuary1 + daysInIsoYear(year + 1)),
+        };
     }
-    const end = startOfWeek1(weekYear + 1, firstDay, minimalDays);
-    return { weekYear, start, end };
+    return { weekYear: year, startOffsetDays: start, endOffsetDays: nextStart };
 }

package/dist/internal/getLocaleWeekendDays.d.ts

@@ -1,22 +1,13 @@
-interface LocaleWeekInfo {
-    firstDay: number;
-    weekend: number[];
-    minimalDays: number;
-}
-declare global {
-    namespace Intl {
-        interface Locale {
-            readonly weekInfo: LocaleWeekInfo;
-        }
-    }
-}
+import type { LocalesArgument } from "./resolveLocale.js";
 /**
  * Resolve the set of ISO day-of-week numbers (1 = Monday .. 7 = Sunday)
- * that count as "weekend" for a locale, via `Intl.Locale.prototype.weekInfo`.
+ * that count as "weekend" for a locale, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to Saturday/Sunday (`[6, 7]`) if `weekInfo` is unavailable
- *   on the runtime (older engines) or unresolvable for the given locale.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
+ * - Falls back to Saturday/Sunday (`[6, 7]`) if the runtime exposes no week
+ *   data or none for the given locale.
  */
-export declare function getLocaleWeekendDays(locale: string): Set<number> | null;
-export {};
+export declare function getLocaleWeekendDays(locale: LocalesArgument): Set<number> | null;

package/dist/internal/getLocaleWeekendDays.js

@@ -1,14 +1,18 @@
+import { localeWeekInfo } from "./localeWeekInfo.js";
 /**
  * Resolve the set of ISO day-of-week numbers (1 = Monday .. 7 = Sunday)
- * that count as "weekend" for a locale, via `Intl.Locale.prototype.weekInfo`.
+ * that count as "weekend" for a locale, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to Saturday/Sunday (`[6, 7]`) if `weekInfo` is unavailable
- *   on the runtime (older engines) or unresolvable for the given locale.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
+ * - Falls back to Saturday/Sunday (`[6, 7]`) if the runtime exposes no week
+ *   data or none for the given locale.
  */
 export function getLocaleWeekendDays(locale) {
     try {
-        const weekInfo = new Intl.Locale(locale).weekInfo;
+        const weekInfo = localeWeekInfo(locale);
         if (!weekInfo || !Array.isArray(weekInfo.weekend)) {
             return new Set([6, 7]);
         }