@northguild/gmt 1.19.0 → 1.20.0

package/dist/internal/earlierOccurrence.js

@@ -0,0 +1,57 @@
+import { Temporal } from "./temporal.js";
+import { plainToZoned } from "./zonedWallClockOperations.js";
+/**
+ * Classify a local wall time in a named zone and place its earlier reading.
+ *
+ * Temporal separates a repeated wall time from a skipped one the same way: two instants. Only the
+ * wall clock the earlier one lands on tells them apart: for an overlap both instants read back as
+ * the requested time, and for a gap neither does, because `"earlier"` and `"later"` resolve a gap
+ * by moving off the requested time entirely.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wall the local wall time
+ * @param timeZone a Temporal time zone identifier (a `ZoneFrame`'s `timeZone` with no stored offset)
+ * @returns the classification, the earlier reading (for a gap, the one `"earlier"` moves to) and the later one
+ *
+ * @example classifyWall(Temporal.PlainDateTime.from("2024-11-03T01:30:00"), "America/New_York").kind // "ambiguous"
+ * @example classifyWall(Temporal.PlainDateTime.from("2024-03-10T02:30:00"), "America/New_York").kind // "nonexistent"
+ */
+export function classifyWall(wall, timeZone) {
+    const earliest = plainToZoned(wall, timeZone, "earlier");
+    const latest = plainToZoned(wall, timeZone, "later");
+    if (earliest.epochNanoseconds === latest.epochNanoseconds) {
+        return { kind: "unique", earliest, latest };
+    }
+    return {
+        kind: earliest.toPlainDateTime().equals(wall) ? "ambiguous" : "nonexistent",
+        earliest,
+        latest,
+    };
+}
+/**
+ * The instant a local wall time names: the first occurrence of a repeated hour, as RFC 5545
+ * §3.3.5 reads a local time that "occurs more than once", and `null` for a skipped one, which is
+ * never shifted.
+ *
+ * @param wall the local wall time
+ * @param frame the zone, from `zoneFrame`; a frame with a stored offset (seconds) names no
+ * `ZonedDateTime`, so it answers `null`
+ * @returns the zoned date-time, or `null` for a skipped wall time, a wall time Temporal cannot
+ * place, or a frame with a stored offset
+ *
+ * @example earlierOccurrence(Temporal.PlainDateTime.from("2024-11-03T01:30:00"), { timeZone: "America/New_York", shiftNanoseconds: 0n })?.offset // "-04:00"
+ * @example earlierOccurrence(Temporal.PlainDateTime.from("2024-03-10T02:30:00"), { timeZone: "America/New_York", shiftNanoseconds: 0n }) // null
+ */
+export function earlierOccurrence(wall, frame) {
+    if (frame.shiftNanoseconds !== 0n) {
+        return null;
+    }
+    try {
+        const { kind, earliest } = classifyWall(wall, frame.timeZone);
+        return kind === "nonexistent" ? null : earliest;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/ediDateTimeFields.js

@@ -1,7 +1,7 @@
 // Not re-exported from `internal/index.ts`: `toOffsetInstant` reads that barrel at module top
 // level (`TIME_ZONE_ANNOTATION`), so a barrel entry for this module would close a cycle and leave
 // the constant undefined when `toOffsetInstant` evaluates. Import this file directly.
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { fromOffsetInstant } from "../instant/convert/fromOffsetInstant.js";
 import { toOffsetInstant } from "../instant/convert/toOffsetInstant.js";
 import { MILLISECONDS_PER_DECIMAL_SECOND, X12_TIME_ELEMENT_FORMS, X12_TIME_ELEMENT_GRAMMAR, X12_TIME_ELEMENT_LAYOUT, ediCodeOfKind, } from "./ediGrammar.js";

package/dist/internal/ediDateTimeWriter.js

@@ -1,7 +1,7 @@
 // Not re-exported from `internal/index.ts`, for the reason `ediDateTimeFields.ts` gives:
 // `toOffsetInstant` reads that barrel at module top level, and the `plain/validate` functions
 // import it too, so a barrel entry for this module would close a cycle. Import this file directly.
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { toOffsetInstant } from "../instant/convert/toOffsetInstant.js";
 import { isValidDate } from "../plain/validate/isValidDate.js";
 import { isValidDateTime } from "../plain/validate/isValidDateTime.js";

package/dist/internal/englishCalendarNames.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 export declare const ENGLISH_WEEKDAY_NAMES: readonly ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
 export declare const ENGLISH_MONTH_NAMES: readonly ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 /**

package/dist/internal/epochDay.d.ts

@@ -0,0 +1,41 @@
+import type { Temporal } from "./temporal.js";
+/** Days in an ISO week. */
+export declare const ISO_WEEKDAYS = 7;
+/**
+ * TC39 `ISODateWithinLimits`: -271821-04-19 and +275760-09-13, counted in days from 1970-01-01,
+ * are the first and last dates a PlainDate holds.
+ */
+export declare const MIN_EPOCH_DAY = -100000001;
+export declare const MAX_EPOCH_DAY = 100000000;
+/**
+ * Days from 1970-01-01 to an ISO date, in the proleptic Gregorian calendar of ECMA-262 §21.4.1
+ * that Temporal's ISO calendar extends. Years run from March so the leap day ends each one.
+ */
+export declare function epochDayOf(year: number, month: number, day: number): number;
+/** The ISO year, month and day `epochDay` days from 1970-01-01 — `epochDayOf` inverted. */
+export declare function isoFieldsOf(epochDay: number): [number, number, number];
+/** `Temporal.PlainDate#toString` for an ISO date: the format `mergeCalendars` returns its holidays in. */
+export declare function isoDateString(epochDay: number): string;
+/**
+ * Days from 1970-01-01 to `date`, an ISO-calendar date. Any other calendar throws a
+ * `RangeError`, which callers turn into their sentinel: its year, month and day are not ISO
+ * fields, so the arithmetic below would silently walk from the wrong day.
+ */
+export declare function epochDayOfDate(date: Temporal.PlainDate): number;
+/**
+ * ISO weekday of an epoch day, Monday 1 to Sunday 7. Follows ECMA-262 `WeekDay` (day 0, 1970-01-01,
+ * is a Thursday) renumbered as Temporal's `ISODayOfWeek` does, Sunday 7 rather than 0.
+ */
+export declare function isoWeekdayOf(epochDay: number): number;
+/** Index of the first element of `days` (sorted ascending) that is >= `epochDay`. */
+export declare function lowerBound(days: Int32Array, epochDay: number): number;
+/** Members of `days` (sorted ascending) within [from, to]; 0 when from > to. */
+export declare function countWithin(days: Int32Array, from: number, to: number): number;
+/** True when `epochDay` is a member of `days` (sorted ascending). */
+export declare function hasEpochDay(days: Int32Array, epochDay: number): boolean;
+/**
+ * `days` ascending with repeats removed. Returns `days` itself when it is already strictly
+ * ascending, so a list written in date order costs one pass and no copy; otherwise sorts a copy
+ * numerically.
+ */
+export declare function sortedUnique(days: Int32Array): Int32Array;

package/dist/internal/epochDay.js

@@ -0,0 +1,129 @@
+import { isoYearString } from "./isoYearString.js";
+/** Days in an ISO week. */
+export const ISO_WEEKDAYS = 7;
+/**
+ * TC39 `ISODateWithinLimits`: -271821-04-19 and +275760-09-13, counted in days from 1970-01-01,
+ * are the first and last dates a PlainDate holds.
+ */
+export const MIN_EPOCH_DAY = -100_000_001;
+export const MAX_EPOCH_DAY = 100_000_000;
+/** 1970-01-01 was a Thursday, ISO weekday 4. */
+const EPOCH_WEEKDAY_OFFSET = 3;
+/** Days in a 400-year cycle of the proleptic Gregorian calendar. */
+const DAYS_PER_400_YEARS = 146_097;
+/** Days from 0000-03-01, the start of a March-based year, to 1970-01-01. */
+const DAYS_FROM_MARCH_0000_TO_EPOCH = 719_468;
+/**
+ * Days from 1970-01-01 to an ISO date, in the proleptic Gregorian calendar of ECMA-262 §21.4.1
+ * that Temporal's ISO calendar extends. Years run from March so the leap day ends each one.
+ */
+export function epochDayOf(year, month, day) {
+    const marchYear = month <= 2 ? year - 1 : year;
+    const cycle = Math.floor(marchYear / 400);
+    const yearOfCycle = marchYear - cycle * 400;
+    const dayOfYear = Math.floor((153 * ((month + 9) % 12) + 2) / 5) + day - 1;
+    const dayOfCycle = yearOfCycle * 365 +
+        Math.floor(yearOfCycle / 4) -
+        Math.floor(yearOfCycle / 100) +
+        dayOfYear;
+    return (cycle * DAYS_PER_400_YEARS + dayOfCycle - DAYS_FROM_MARCH_0000_TO_EPOCH);
+}
+/** The ISO year, month and day `epochDay` days from 1970-01-01 — `epochDayOf` inverted. */
+export function isoFieldsOf(epochDay) {
+    const shifted = epochDay + DAYS_FROM_MARCH_0000_TO_EPOCH;
+    const cycle = Math.floor(shifted / DAYS_PER_400_YEARS);
+    const dayOfCycle = shifted - cycle * DAYS_PER_400_YEARS;
+    // Remove the leap days of every 4th, 100th and 400th year before dividing into 365-day years.
+    const yearOfCycle = Math.floor((dayOfCycle -
+        Math.floor(dayOfCycle / 1460) +
+        Math.floor(dayOfCycle / 36_524) -
+        Math.floor(dayOfCycle / (DAYS_PER_400_YEARS - 1))) /
+        365);
+    const dayOfYear = dayOfCycle -
+        (365 * yearOfCycle +
+            Math.floor(yearOfCycle / 4) -
+            Math.floor(yearOfCycle / 100));
+    const monthFromMarch = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthFromMarch + 2) / 5) + 1;
+    const month = monthFromMarch < 10 ? monthFromMarch + 3 : monthFromMarch - 9;
+    const year = yearOfCycle + cycle * 400 + (month <= 2 ? 1 : 0);
+    return [year, month, day];
+}
+/** `Temporal.PlainDate#toString` for an ISO date: the format `mergeCalendars` returns its holidays in. */
+export function isoDateString(epochDay) {
+    const [year, month, day] = isoFieldsOf(epochDay);
+    return `${isoYearString(year)}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+/**
+ * Days from 1970-01-01 to `date`, an ISO-calendar date. Any other calendar throws a
+ * `RangeError`, which callers turn into their sentinel: its year, month and day are not ISO
+ * fields, so the arithmetic below would silently walk from the wrong day.
+ */
+export function epochDayOfDate(date) {
+    if (date.calendarId !== "iso8601") {
+        throw new RangeError("business-day walks take an ISO-calendar date");
+    }
+    return epochDayOf(date.year, date.month, date.day);
+}
+/**
+ * ISO weekday of an epoch day, Monday 1 to Sunday 7. Follows ECMA-262 `WeekDay` (day 0, 1970-01-01,
+ * is a Thursday) renumbered as Temporal's `ISODayOfWeek` does, Sunday 7 rather than 0.
+ */
+export function isoWeekdayOf(epochDay) {
+    // `%` keeps the dividend's sign, so a date before 1970 needs the second `+ ISO_WEEKDAYS`.
+    return (((((epochDay + EPOCH_WEEKDAY_OFFSET) % ISO_WEEKDAYS) + ISO_WEEKDAYS) %
+        ISO_WEEKDAYS) +
+        1);
+}
+/** Index of the first element of `days` (sorted ascending) that is >= `epochDay`. */
+export function lowerBound(days, epochDay) {
+    let low = 0;
+    let high = days.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (days[middle] < epochDay) {
+            low = middle + 1;
+        }
+        else {
+            high = middle;
+        }
+    }
+    return low;
+}
+/** Members of `days` (sorted ascending) within [from, to]; 0 when from > to. */
+export function countWithin(days, from, to) {
+    if (from > to) {
+        return 0;
+    }
+    return lowerBound(days, to + 1) - lowerBound(days, from);
+}
+/** True when `epochDay` is a member of `days` (sorted ascending). */
+export function hasEpochDay(days, epochDay) {
+    const index = lowerBound(days, epochDay);
+    return index < days.length && days[index] === epochDay;
+}
+/**
+ * `days` ascending with repeats removed. Returns `days` itself when it is already strictly
+ * ascending, so a list written in date order costs one pass and no copy; otherwise sorts a copy
+ * numerically.
+ */
+export function sortedUnique(days) {
+    let ascending = true;
+    for (let index = 1; index < days.length; index++) {
+        if (days[index] <= days[index - 1]) {
+            ascending = false;
+            break;
+        }
+    }
+    if (ascending) {
+        return days;
+    }
+    const sorted = days.slice().sort();
+    let kept = 0;
+    for (let index = 0; index < sorted.length; index++) {
+        if (index === 0 || sorted[index] !== sorted[index - 1]) {
+            sorted[kept++] = sorted[index];
+        }
+    }
+    return sorted.slice(0, kept);
+}

package/dist/internal/exactDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { NANOSECONDS_PER_DAY, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, } from "./foreignEpochs.js";
 const NANOSECONDS_PER_HOUR = 3600000000000n;
 const NANOSECONDS_PER_MINUTE = 60000000000n;

package/dist/internal/exactMoment.d.ts

@@ -19,16 +19,16 @@ export type ExactMoment = {
 /**
  * Read an exact moment the way `transitTime` reads a departure, or `null`.
  *
- * - A zoned string (`…-04:00[America/New_York]`) is read through its bracket, which must name a
+ * - A zoned string (`…+09:00[Asia/Tokyo]`) is read through its bracket, which must name a
  *   real zone that agrees with the offset, as `isValidZonedDateTime` requires. An offset written
  *   to the minute agrees when it is the zone's sub-minute offset rounded (TC39
  *   `ToTemporalZonedDateTime`, match-minutes), which is how `writeExactMoment` writes one.
  * - A wall time with a bracket and no offset is read in that zone with the `"compatible"`
  *   disambiguation policy (`context/reference/LOCAL_TIME_RESOLUTION.md`): an **ambiguous** wall
  *   time, a fall-back hour the clock ran through twice, resolves to the **earlier** instant
- *   (`2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`), and a **nonexistent** one, a
+ *   (`2024-10-27T01:30:00[Europe/London]` is `01:30+01:00`), and a **nonexistent** one, a
  *   spring-forward hour the clock skipped, to the **later** instant
- *   (`2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`). A caller that must not guess
+ *   (`2024-03-31T01:30:00[Europe/London]` is `02:30+01:00`). A caller that must not guess
  *   refuses the offset-less form before calling, as `nextDeparture` does.
  * - A string that names a zone the zoned read rejects is `null`; it never falls back to its
  *   offset. That includes a zoned string whose local date is −271821-04-19, which
@@ -42,7 +42,7 @@ export type ExactMoment = {
  *
  * @example readExactMoment("2024-06-15T10:00:00+09:00") // { nanoseconds: 1718413200000000000n, notation: { kind: "offset", offset: "+09:00" } }
  * @example readExactMoment("2024-06-15T10:00:00Z[Not/AZone]") // null
- * @example readExactMoment("2024-03-10T02:30:00[America/New_York]") // { nanoseconds: 1710055800000000000n, notation: { kind: "zone", timeZone: "America/New_York" } } (nonexistent: the later instant, 03:30-04:00)
+ * @example readExactMoment("2024-03-31T01:30:00[Europe/London]") // { nanoseconds: 1711848600000000000n, notation: { kind: "zone", timeZone: "Europe/London" } } (nonexistent: the later instant, 02:30+01:00)
  */
 export declare function readExactMoment(value: unknown): ExactMoment | null;
 /**

package/dist/internal/exactMoment.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { isValidZonedDateTime } from "../zoned/validate/isValidZonedDateTime.js";
 import { parseInstantNanoseconds } from "./instantNanoseconds.js";
 import { EXTENDED_UTC_OFFSET, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
@@ -18,16 +18,16 @@ const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
 /**
  * Read an exact moment the way `transitTime` reads a departure, or `null`.
  *
- * - A zoned string (`…-04:00[America/New_York]`) is read through its bracket, which must name a
+ * - A zoned string (`…+09:00[Asia/Tokyo]`) is read through its bracket, which must name a
  *   real zone that agrees with the offset, as `isValidZonedDateTime` requires. An offset written
  *   to the minute agrees when it is the zone's sub-minute offset rounded (TC39
  *   `ToTemporalZonedDateTime`, match-minutes), which is how `writeExactMoment` writes one.
  * - A wall time with a bracket and no offset is read in that zone with the `"compatible"`
  *   disambiguation policy (`context/reference/LOCAL_TIME_RESOLUTION.md`): an **ambiguous** wall
  *   time, a fall-back hour the clock ran through twice, resolves to the **earlier** instant
- *   (`2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`), and a **nonexistent** one, a
+ *   (`2024-10-27T01:30:00[Europe/London]` is `01:30+01:00`), and a **nonexistent** one, a
  *   spring-forward hour the clock skipped, to the **later** instant
- *   (`2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`). A caller that must not guess
+ *   (`2024-03-31T01:30:00[Europe/London]` is `02:30+01:00`). A caller that must not guess
  *   refuses the offset-less form before calling, as `nextDeparture` does.
  * - A string that names a zone the zoned read rejects is `null`; it never falls back to its
  *   offset. That includes a zoned string whose local date is −271821-04-19, which
@@ -41,7 +41,7 @@ const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
  *
  * @example readExactMoment("2024-06-15T10:00:00+09:00") // { nanoseconds: 1718413200000000000n, notation: { kind: "offset", offset: "+09:00" } }
  * @example readExactMoment("2024-06-15T10:00:00Z[Not/AZone]") // null
- * @example readExactMoment("2024-03-10T02:30:00[America/New_York]") // { nanoseconds: 1710055800000000000n, notation: { kind: "zone", timeZone: "America/New_York" } } (nonexistent: the later instant, 03:30-04:00)
+ * @example readExactMoment("2024-03-31T01:30:00[Europe/London]") // { nanoseconds: 1711848600000000000n, notation: { kind: "zone", timeZone: "Europe/London" } } (nonexistent: the later instant, 02:30+01:00)
  */
 export function readExactMoment(value) {
     if (typeof value !== "string") {

package/dist/internal/fiscalCalendar.d.ts

@@ -1,5 +1,18 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { FiscalPattern } from "../types/index.js";
+import { Temporal } from "./temporal.js";
+import type { FiscalExtraWeek, FiscalPattern, FiscalYearLabel } from "../types/index.js";
+/**
+ * Return the multiple of 400 years that moves `year` into 2000 to 2399, where it keeps its
+ * place in the Gregorian cycle.
+ *
+ * Subtract the result to move a year into that cycle, and add it to move it back. Calendar
+ * arithmetic near Temporal's first or last date (-271821-04-19, +275760-09-13) can step past
+ * the range on the way to an answer that lies inside it; done in the safe cycle it cannot.
+ *
+ * @example gregorianCycleShift(2024) // 0
+ * @example gregorianCycleShift(-271820) // -274000 (-271820 sits where 2180 does)
+ * @example gregorianCycleShift(275760) // 273600 (275760 sits where 2160 does)
+ */
+export declare function gregorianCycleShift(year: number): number;
 /**
  * Return the fiscal year end falling in calendar year `year`, under the rule `anchor` states.
  *
@@ -21,8 +34,13 @@ export declare function fiscalYearEndIn(anchor: Temporal.PlainDate, year: number
  *
  * - The fiscal year is the one whose end is the first at or after `date`.
  * - `weeks` is derived from the gap between consecutive year ends — 52 or 53 — never assumed.
- * - Returns null when that gap is neither 364 nor 371 days, which no "nearest weekday" rule
- *   can produce and so only a corrupted anchor could reach.
+ * - The search reads the year ends in the calendar years either side of `date`, so it throws
+ *   RangeError when one of them lies outside Temporal's range. Near -271821-04-19 or
+ *   +275760-09-13 that happens even when the date is valid. Move `date` into 2000 to 2399 with
+ *   `gregorianCycleShift` first, then add the shift back to any year read off the result:
+ *   whole 400-year cycles keep every month, day, weekday and day count.
+ * - Returns null when the gap between year ends is neither 364 nor 371 days, which no
+ *   "nearest weekday" rule can produce and so only a corrupted anchor could reach.
  */
 export declare function fiscalYearOf(date: Temporal.PlainDate, anchor: Temporal.PlainDate): {
     start: Temporal.PlainDate;
@@ -31,7 +49,23 @@ export declare function fiscalYearOf(date: Temporal.PlainDate, anchor: Temporal.
 /**
  * Return the 1-based period holding `week` of a `weeks`-long fiscal year under `pattern`.
  *
- * The 53rd week, when the year has one, is appended to the final period — the NRF adds it
- * "to the end of the calendar", which turns a 4-5-4 year's last quarter into 4-5-5.
+ * - The 53rd week, when the year has one, lengthens period 1 (`"firstPeriod"`) or period 12
+ *   (`"lastPeriod"`), as `extraWeek` says. A 4-4-5 year then runs 5-4-5 … 4-4-5 or
+ *   4-4-5 … 4-4-6.
+ * - In a 52-week year `extraWeek` has no effect.
+ */
+export declare function fiscalPeriodOfWeek(week: number, weeks: number, pattern: FiscalPattern, extraWeek: FiscalExtraWeek): number;
+/**
+ * Return the calendar year that names the fiscal year running `start` to `end`, both inclusive.
+ *
+ * - `"startYear"` is `start`'s year and `"endYear"` is `end`'s year.
+ * - `"majorityYear"` is the calendar year holding the most of the fiscal year's days. Days are
+ *   the unit because the fiscal year and the calendar year share no other: months differ in
+ *   length, and a week can straddle 1 January.
+ * - Every calendar year in the span is counted, not only the two end years. A 371-day year can
+ *   touch three calendar years (2024-12-29 to 2026-01-03), and then the middle one wins.
+ * - GMT rule: when two years hold exactly half the days each (182 and 182), the later one, the
+ *   year holding the end date, wins, because IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a
+ *   reporting period be identified by the date it ends.
  */
-export declare function fiscalPeriodOfWeek(week: number, weeks: number, pattern: FiscalPattern): number;
+export declare function fiscalYearLabel(start: Temporal.PlainDate, end: Temporal.PlainDate, label: FiscalYearLabel): number;

package/dist/internal/fiscalCalendar.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /** Weeks per period within one quarter, by pattern. */
 const WEEKS_PER_PERIOD = {
     "4-5-4": [4, 5, 4],
@@ -22,6 +22,31 @@ const DAYS_IN_53_WEEK_YEAR = 371;
 const YEAR_END_SEARCH_OFFSETS = [-1, 0, 1, 2];
 /** Half the width of the 7-day window a "nearest weekday" year end can land in. */
 const NEAREST_WEEKDAY_RADIUS = 3;
+/**
+ * Years in one cycle of the Gregorian leap rule. Every 400-year span has 146,097 days, a whole
+ * number of weeks, and the same leap years in the same places, so moving a date by a multiple
+ * of 400 years keeps its month, day and weekday.
+ */
+const GREGORIAN_CYCLE_YEARS = 400;
+/** First year of the cycle that dates are moved into, well inside Temporal's range. */
+const SAFE_CYCLE_START = 2000;
+/**
+ * Return the multiple of 400 years that moves `year` into 2000 to 2399, where it keeps its
+ * place in the Gregorian cycle.
+ *
+ * Subtract the result to move a year into that cycle, and add it to move it back. Calendar
+ * arithmetic near Temporal's first or last date (-271821-04-19, +275760-09-13) can step past
+ * the range on the way to an answer that lies inside it; done in the safe cycle it cannot.
+ *
+ * @example gregorianCycleShift(2024) // 0
+ * @example gregorianCycleShift(-271820) // -274000 (-271820 sits where 2180 does)
+ * @example gregorianCycleShift(275760) // 273600 (275760 sits where 2160 does)
+ */
+export function gregorianCycleShift(year) {
+    const placeInCycle = ((year % GREGORIAN_CYCLE_YEARS) + GREGORIAN_CYCLE_YEARS) %
+        GREGORIAN_CYCLE_YEARS;
+    return year - SAFE_CYCLE_START - placeInCycle;
+}
 /**
  * Return the fiscal year end falling in calendar year `year`, under the rule `anchor` states.
  *
@@ -49,8 +74,13 @@ export function fiscalYearEndIn(anchor, year) {
  *
  * - The fiscal year is the one whose end is the first at or after `date`.
  * - `weeks` is derived from the gap between consecutive year ends — 52 or 53 — never assumed.
- * - Returns null when that gap is neither 364 nor 371 days, which no "nearest weekday" rule
- *   can produce and so only a corrupted anchor could reach.
+ * - The search reads the year ends in the calendar years either side of `date`, so it throws
+ *   RangeError when one of them lies outside Temporal's range. Near -271821-04-19 or
+ *   +275760-09-13 that happens even when the date is valid. Move `date` into 2000 to 2399 with
+ *   `gregorianCycleShift` first, then add the shift back to any year read off the result:
+ *   whole 400-year cycles keep every month, day, weekday and day count.
+ * - Returns null when the gap between year ends is neither 364 nor 371 days, which no
+ *   "nearest weekday" rule can produce and so only a corrupted anchor could reach.
  */
 export function fiscalYearOf(date, anchor) {
     for (const offset of YEAR_END_SEARCH_OFFSETS) {
@@ -70,18 +100,56 @@ export function fiscalYearOf(date, anchor) {
 /**
  * Return the 1-based period holding `week` of a `weeks`-long fiscal year under `pattern`.
  *
- * The 53rd week, when the year has one, is appended to the final period — the NRF adds it
- * "to the end of the calendar", which turns a 4-5-4 year's last quarter into 4-5-5.
+ * - The 53rd week, when the year has one, lengthens period 1 (`"firstPeriod"`) or period 12
+ *   (`"lastPeriod"`), as `extraWeek` says. A 4-4-5 year then runs 5-4-5 … 4-4-5 or
+ *   4-4-5 … 4-4-6.
+ * - In a 52-week year `extraWeek` has no effect.
  */
-export function fiscalPeriodOfWeek(week, weeks, pattern) {
+export function fiscalPeriodOfWeek(week, weeks, pattern, extraWeek) {
     const quarterShape = WEEKS_PER_PERIOD[pattern];
+    const longPeriod = extraWeek === "firstPeriod" ? 1 : PERIODS_PER_YEAR;
     let consumed = 0;
     for (let period = 1; period <= PERIODS_PER_YEAR; period++) {
-        const isFinalPeriod = period === PERIODS_PER_YEAR;
-        const extraWeek = isFinalPeriod && weeks === 53 ? 1 : 0;
-        consumed += quarterShape[(period - 1) % quarterShape.length] + extraWeek;
+        const added = weeks === 53 && period === longPeriod ? 1 : 0;
+        consumed += quarterShape[(period - 1) % quarterShape.length] + added;
         if (week <= consumed)
             return period;
     }
     return PERIODS_PER_YEAR;
 }
+/**
+ * Return the calendar year that names the fiscal year running `start` to `end`, both inclusive.
+ *
+ * - `"startYear"` is `start`'s year and `"endYear"` is `end`'s year.
+ * - `"majorityYear"` is the calendar year holding the most of the fiscal year's days. Days are
+ *   the unit because the fiscal year and the calendar year share no other: months differ in
+ *   length, and a week can straddle 1 January.
+ * - Every calendar year in the span is counted, not only the two end years. A 371-day year can
+ *   touch three calendar years (2024-12-29 to 2026-01-03), and then the middle one wins.
+ * - GMT rule: when two years hold exactly half the days each (182 and 182), the later one, the
+ *   year holding the end date, wins, because IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a
+ *   reporting period be identified by the date it ends.
+ */
+export function fiscalYearLabel(start, end, label) {
+    if (label === "startYear")
+        return start.year;
+    if (label === "endYear")
+        return end.year;
+    let best = end.year;
+    let bestDays = -1;
+    for (let year = start.year; year <= end.year; year++) {
+        const from = year === start.year
+            ? start
+            : Temporal.PlainDate.from({ year, month: 1, day: 1 });
+        const to = year === end.year
+            ? end
+            : Temporal.PlainDate.from({ year, month: 12, day: 31 });
+        const days = from.until(to, { largestUnit: "day" }).days + 1;
+        // ">=": a tie goes to the later year, which holds the end date.
+        if (days >= bestDays) {
+            best = year;
+            bestDays = days;
+        }
+    }
+    return best;
+}

package/dist/internal/foreignEpochs.d.ts

@@ -29,6 +29,11 @@ export declare const NANOSECONDS_PER_MICROSECOND = 1000n;
 export declare const NANOSECONDS_PER_TICK = 100n;
 /** Nanoseconds in one 24-hour day. */
 export declare const NANOSECONDS_PER_DAY = 86400000000000n;
+/**
+ * Nanoseconds in one week: 604 800 s, the week every satellite week counter counts (IS-GPS-200N
+ * §3.3.4: "The largest unit used in stating GPS time is one week defined as 604,800 seconds").
+ */
+export declare const NANOSECONDS_PER_WEEK = 604800000000000n;
 /** The same value as a `number` — an Excel serial is days in a `double`. */
 export declare const NANOSECONDS_PER_DAY_NUMBER = 86400000000000;
 /** Milliseconds in one 24-hour day. Excel serials round to this grid; see `fromExcelSerial`. */

package/dist/internal/foreignEpochs.js

@@ -29,6 +29,11 @@ export const NANOSECONDS_PER_MICROSECOND = 1000n;
 export const NANOSECONDS_PER_TICK = 100n;
 /** Nanoseconds in one 24-hour day. */
 export const NANOSECONDS_PER_DAY = 86400000000000n;
+/**
+ * Nanoseconds in one week: 604 800 s, the week every satellite week counter counts (IS-GPS-200N
+ * §3.3.4: "The largest unit used in stating GPS time is one week defined as 604,800 seconds").
+ */
+export const NANOSECONDS_PER_WEEK = 604800000000000n;
 /** The same value as a `number` — an Excel serial is days in a `double`. */
 export const NANOSECONDS_PER_DAY_NUMBER = 86_400_000_000_000;
 /** Milliseconds in one 24-hour day. Excel serials round to this grid; see `fromExcelSerial`. */

package/dist/internal/formatCalendarDays.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Render a calendar phrase for a moment `diffDays` calendar days from the reference: "tomorrow at
  * 2:30 PM" within six days, else the long date and time. Shared by the zoned, utc and unix
@@ -10,8 +10,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where `Intl` throws, for the caller's sentinel
- * @example formatCalendarDays(1, 1710685800000, "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
- * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-US", "short") // "March 17, 2024 at 2:30 PM"
+ * @example formatCalendarDays(1, 1710685800000, "UTC", "en-GB", "short") // "tomorrow at 14:30"
+ * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-GB", "short") // "17 March 2024 at 14:30"
  */
 export declare function formatCalendarDays(diffDays: number, epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;
 /**
@@ -23,6 +23,6 @@ export declare function formatCalendarDays(diffDays: number, epochMilliseconds:
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where Temporal or `Intl` throws
- * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
+ * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-GB", "short") // "tomorrow at 14:30"
  */
 export declare function formatCalendarInstants(target: Temporal.Instant, reference: Temporal.Instant, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;

package/dist/internal/formatCalendarDays.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "./formatterCache.js";
 import { joinDateTimeConnector } from "./joinDateTimeConnector.js";
 import { normalizeDateTime } from "./normalizeDateTime.js";
 // Beyond a week either direction the phrase falls back to an absolute date, as plain
@@ -14,18 +15,18 @@ const ABS_DAY_THRESHOLD = 6;
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where `Intl` throws, for the caller's sentinel
- * @example formatCalendarDays(1, 1710685800000, "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
- * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-US", "short") // "March 17, 2024 at 2:30 PM"
+ * @example formatCalendarDays(1, 1710685800000, "UTC", "en-GB", "short") // "tomorrow at 14:30"
+ * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-GB", "short") // "17 March 2024 at 14:30"
  */
 export function formatCalendarDays(diffDays, epochMilliseconds, timeZone, locale, timeStyle) {
     if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
-        return normalizeDateTime(new Intl.DateTimeFormat(locale, {
+        return normalizeDateTime(cachedFormatter("DateTimeFormat", locale, {
             dateStyle: "long",
             timeStyle,
             timeZone,
         }).format(epochMilliseconds));
     }
-    const dayLabel = new Intl.RelativeTimeFormat(locale, {
+    const dayLabel = cachedFormatter("RelativeTimeFormat", locale, {
         numeric: "auto",
     }).format(diffDays, "day");
     return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle));
@@ -39,7 +40,7 @@ export function formatCalendarDays(diffDays, epochMilliseconds, timeZone, locale
  * @param locale BCP 47 locale(s) passed through to `Intl`
  * @param timeStyle the `Intl.DateTimeFormat` time style
  * @returns the phrase; throws where Temporal or `Intl` throws
- * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
+ * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-GB", "short") // "tomorrow at 14:30"
  */
 export function formatCalendarInstants(target, reference, timeZone, locale, timeStyle) {
     const targetDate = target.toZonedDateTimeISO(timeZone).toPlainDate();

package/dist/internal/formatDateInCalendar.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 import type { CalendarSystem } from "../types/index.js";
 /**
  * Write a Temporal.PlainDate as a GMT PlainDate string in `calendar`: exactly