@northguild/gmt 1.18.0 → 1.19.0

package/dist/internal/isoYearString.js

@@ -0,0 +1,27 @@
+/** TC39 Temporal `PadISOYear ( y )`, §3.5.10: a year from 0 to 9999 is written with four digits. */
+const MAX_FOUR_DIGIT_YEAR = 9999;
+/**
+ * Write an ISO year as Temporal writes it at the head of a date string (TC39 Temporal
+ * `PadISOYear ( y )`, §3.5.10): four digits from 0000 to 9999, otherwise a sign and six digits.
+ *
+ * A year written any other way does not read back. `"10000-01-01"` and `"00-5-01-01"` are not ISO
+ * 8601 or Temporal strings, and `isValidDate` rejects both; `"+010000-01-01"` and
+ * `"-000005-01-01"` are what `Temporal.PlainDate#toString` writes.
+ *
+ * - Every function that returns a year on its own writes it this way.
+ * - Where a Temporal value is at hand, let its own `toString` write the whole date. This is for a
+ *   year on its own, or a date assembled from fields with no Temporal value behind them.
+ *
+ * @param year an ISO year, an integer
+ * @returns the year as `YYYY` or `±YYYYYY`
+ *
+ * @example isoYearString(2024) // "2024"
+ * @example isoYearString(5) // "0005"
+ * @example isoYearString(10000) // "+010000"
+ * @example isoYearString(-5) // "-000005"
+ */
+export function isoYearString(year) {
+    return year < 0 || year > MAX_FOUR_DIGIT_YEAR
+        ? `${year < 0 ? "-" : "+"}${String(Math.abs(year)).padStart(6, "0")}`
+        : String(year).padStart(4, "0");
+}

package/dist/internal/maxPieces.js

@@ -1,3 +1,4 @@
+import { isObject } from "./isObject.js";
 /**
  * Default `maxPieces` for functions that return one array element per generated piece
  * (`splitIntervalByUnit*`, `intervalDivideEqually*`, `mapDatesInRange`, `mapZonedDatesInRange`).
@@ -27,7 +28,7 @@ export function resolveMaxPieces(options) {
     if (options === undefined) {
         return DEFAULT_MAX_PIECES;
     }
-    if (typeof options !== "object" || options === null) {
+    if (!isObject(options)) {
         return null;
     }
     const { maxPieces } = options;

package/dist/internal/normalizeTimeZone.d.ts

@@ -1,5 +1,8 @@
 /**
- * Resolve the `timeZone` option of every `unix/` and `utc/` function that takes one.
+ * Resolve the `timeZone` option of the `unix/` and `utc/` functions that hand the zone to
+ * `Intl.DateTimeFormat`, which takes a time zone identifier only. A function whose result names no
+ * zone reads its option with `normalizeZoneFrame` instead, which also accepts a stored UTC offset
+ * with seconds.
  *
  * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
  *   zone is read unless asked for.

package/dist/internal/normalizeTimeZone.js

@@ -1,7 +1,10 @@
 import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
 import { isValidTimeZone } from "../zoned/validate/index.js";
 /**
- * Resolve the `timeZone` option of every `unix/` and `utc/` function that takes one.
+ * Resolve the `timeZone` option of the `unix/` and `utc/` functions that hand the zone to
+ * `Intl.DateTimeFormat`, which takes a time zone identifier only. A function whose result names no
+ * zone reads its option with `normalizeZoneFrame` instead, which also accepts a stored UTC offset
+ * with seconds.
  *
  * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
  *   zone is read unless asked for.

package/dist/internal/operatingSchedule.d.ts

@@ -1,5 +1,6 @@
 import type { Disambiguation } from "../types/index.js";
 import { type IntervalNanoseconds } from "./intervalNanoseconds.js";
+import { type ZoneFrame } from "./zoneFrame.js";
 /** A `LocalWindow` validated once: canonical PlainTime strings, and whether it wraps midnight. */
 export type ResolvedWindow = {
     from: string;
@@ -8,7 +9,10 @@ export type ResolvedWindow = {
 };
 /** An `OperatingSchedule` reduced to the lookups the day walk needs. */
 export type ResolvedSchedule = {
+    /** The zone as the caller wrote it: a time zone identifier or a stored UTC offset. */
     timeZone: string;
+    /** How local time is read in that zone (`zoneFrame`). */
+    frame: ZoneFrame;
     /** Windows by ISO weekday; index 0 is unused. */
     weekly: readonly (readonly ResolvedWindow[])[];
     holidays: ReadonlySet<string>;
@@ -26,9 +30,12 @@ export declare const MAX_SCHEDULE_DAYS = 10000;
  */
 export declare const DEFAULT_OPERATING_HORIZON = "P1Y";
 /**
- * Parse `OperatingSchedule['weekly']`: an object whose own keys are ISO weekdays `"1"`–`"7"`,
- * each holding an array of `LocalWindow`s (or `undefined`, meaning closed). Any other key, or a
- * malformed window, returns `null`.
+ * Parse `OperatingSchedule['weekly']`: an object keyed by ISO weekday `"1"`–`"7"`, each holding an
+ * array of `LocalWindow`s (or `undefined`, meaning closed). Each weekday is read with an ordinary
+ * property get, as Temporal's `Get` reads a field list, so a non-enumerable or inherited weekday
+ * applies. Any other own enumerable key, string or symbol, or a malformed window, returns `null`;
+ * a non-enumerable one is not an entry, as `Object.assign` and spread do not copy it, so a
+ * function carrying the weekdays is read without its built-in `length` and `name`.
  */
 export declare function parseWeeklyPattern(value: unknown): ResolvedWindow[][] | null;
 /** Validate an `OperatingSchedule`, or `null` when any part of it is malformed. */
@@ -47,7 +54,7 @@ export declare function parseScheduleDisambiguation(options: unknown): Disambigu
  * that instant, since nothing after it can be answered. `null` when `within` is not a
  * non-negative ISO duration.
  */
-export declare function parseSearchHorizon(fromNs: bigint, within: unknown, timeZone: string): bigint | null;
+export declare function parseSearchHorizon(fromNs: bigint, within: unknown, frame: ZoneFrame): bigint | null;
 /**
  * What the walk tells its caller.
  *
@@ -82,6 +89,8 @@ export type ScheduleWalk = {
  * - A window can start as early as the previous date's first instant (see `resolveDateWindows`),
  *   so the walk settles one date behind: once a date is resolved, the first instant of the date
  *   resolved before it is the `bound` no later window starts before.
+ * - A walk from the start of Temporal's range also resolves the date before its first, whose
+ *   wrapping windows are still open when the range begins (`resolveWindowsBefore`).
  * - When the visitor stops the walk from `day`, or the last representable day is reached, the
  *   runs still pending are handed over too.
  * - Returns `null` when a day bucket could not be found, or the walk would resolve a date

package/dist/internal/operatingSchedule.js

@@ -2,11 +2,11 @@ import { Temporal } from "@js-temporal/polyfill";
 import { resolveLocal } from "../instant/convert/resolveLocal.js";
 import { isValidDate } from "../plain/validate/isValidDate.js";
 import { isValidTime } from "../plain/validate/isValidTime.js";
-import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
 import { parseBusinessCalendar, parseHolidays } from "./businessCalendar.js";
 import { coalesceIntervalNanoseconds, } from "./intervalNanoseconds.js";
 import { isObject, isOptionsArgument } from "./isObject.js";
 import { nextZonedBucketStart, zonedUnitStart } from "./zonedBucket.js";
+import { frameEpochNanoseconds, frameWallClock, frameZoned, zoneFrame, } from "./zoneFrame.js";
 const DISAMBIGUATIONS = [
     "compatible",
     "earlier",
@@ -81,9 +81,12 @@ function parseWindows(value) {
     return windows;
 }
 /**
- * Parse `OperatingSchedule['weekly']`: an object whose own keys are ISO weekdays `"1"`–`"7"`,
- * each holding an array of `LocalWindow`s (or `undefined`, meaning closed). Any other key, or a
- * malformed window, returns `null`.
+ * Parse `OperatingSchedule['weekly']`: an object keyed by ISO weekday `"1"`–`"7"`, each holding an
+ * array of `LocalWindow`s (or `undefined`, meaning closed). Each weekday is read with an ordinary
+ * property get, as Temporal's `Get` reads a field list, so a non-enumerable or inherited weekday
+ * applies. Any other own enumerable key, string or symbol, or a malformed window, returns `null`;
+ * a non-enumerable one is not an entry, as `Object.assign` and spread do not copy it, so a
+ * function carrying the weekdays is read without its built-in `length` and `name`.
  */
 export function parseWeeklyPattern(value) {
     if (!isObject(value) || Array.isArray(value)) {
@@ -92,13 +95,17 @@ export function parseWeeklyPattern(value) {
     const weekly = Array.from({ length: 8 }, () => []);
     const record = value;
     for (const key of Reflect.ownKeys(record)) {
-        if (typeof key !== "string" || !WEEKDAY_KEYS.includes(key)) {
+        if ((typeof key !== "string" || !WEEKDAY_KEYS.includes(key)) &&
+            Object.prototype.propertyIsEnumerable.call(record, key)) {
             return null;
         }
-        if (record[key] === undefined) {
+    }
+    for (const key of WEEKDAY_KEYS) {
+        const day = record[key];
+        if (day === undefined) {
             continue;
         }
-        const windows = parseWindows(record[key]);
+        const windows = parseWindows(day);
         if (windows === null) {
             return null;
         }
@@ -148,7 +155,8 @@ export function parseOperatingSchedule(value) {
         return null;
     }
     const { timeZone, weekly, holidays, overrides } = value;
-    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+    const frame = zoneFrame(timeZone);
+    if (typeof timeZone !== "string" || frame === null) {
         return null;
     }
     const weeklyWindows = parseWeeklyPattern(weekly);
@@ -161,6 +169,7 @@ export function parseOperatingSchedule(value) {
     }
     return {
         timeZone,
+        frame,
         weekly: weeklyWindows,
         holidays: holidayDates,
         overrides: overrideWindows,
@@ -192,7 +201,7 @@ export function parseScheduleDisambiguation(options) {
  * that instant, since nothing after it can be answered. `null` when `within` is not a
  * non-negative ISO duration.
  */
-export function parseSearchHorizon(fromNs, within, timeZone) {
+export function parseSearchHorizon(fromNs, within, frame) {
     const text = within === undefined ? DEFAULT_OPERATING_HORIZON : within;
     if (typeof text !== "string") {
         return null;
@@ -207,18 +216,23 @@ export function parseSearchHorizon(fromNs, within, timeZone) {
     if (duration.sign < 0) {
         return null;
     }
-    const from = Temporal.Instant.fromEpochNanoseconds(fromNs).toZonedDateTimeISO(timeZone);
-    const horizon = clampedToRange(() => from.add(duration).epochNanoseconds);
-    const cap = clampedToRange(() => from
+    const from = frameZoned(Temporal.Instant.fromEpochNanoseconds(fromNs), frame);
+    const horizon = clampedToRange(() => frameEpochNanoseconds(from.add(duration), frame));
+    const cap = clampedToRange(() => frameEpochNanoseconds(from
         .toPlainDate()
         .add({ days: MAX_SCHEDULE_DAYS + 1 })
-        .toZonedDateTime(timeZone).epochNanoseconds - 1n);
+        .toZonedDateTime(frame.timeZone), frame) - 1n);
     return horizon < cap ? horizon : cap;
 }
 /** An instant computed by `instant`, or Temporal's last instant when it lies past the range. */
 function clampedToRange(instant) {
     try {
-        return instant();
+        const nanoseconds = instant();
+        // At a seconds offset west of UTC the instant is later than the stand-in it was computed
+        // on (`frameZoned`), so it can pass the last instant without Temporal throwing.
+        return nanoseconds > MAX_INSTANT_NANOSECONDS
+            ? MAX_INSTANT_NANOSECONDS
+            : nanoseconds;
     }
     catch (error) {
         if (error instanceof RangeError) {
@@ -229,9 +243,7 @@ function clampedToRange(instant) {
 }
 /** The local date of an instant in the schedule's zone. */
 function localDateOf(schedule, ns) {
-    return Temporal.Instant.fromEpochNanoseconds(ns)
-        .toZonedDateTimeISO(schedule.timeZone)
-        .toPlainDate();
+    return frameWallClock(Temporal.Instant.fromEpochNanoseconds(ns), schedule.frame).toPlainDate();
 }
 /**
  * The local date `days` after the one `fromNs` falls on, or `null` when that is past Temporal's
@@ -250,20 +262,34 @@ function dateLimit(schedule, fromNs, days) {
 }
 /**
  * The day bucket the walk starts in: the one holding the instant 72 hours before `fromNs`, or
- * Temporal's first instant when that is earlier. When the bucket's own start is not
- * representable, the walk starts at that instant instead, the earliest of its date there is.
+ * the earliest instant the schedule's frame can place when that is earlier. When the bucket's own
+ * start is not representable, the walk starts at that instant instead, the earliest of its date
+ * there is.
+ *
+ * The earliest instant is Temporal's first, except at an offset with seconds west of UTC: its
+ * stand-in sits the offset's seconds before the instant (`frameZoned`), so the first instant it
+ * can place is that many seconds after Temporal's first. A walk from before it throws
+ * `RangeError`, the caller's sentinel, rather than start after its own instant.
+ *
+ * `atRangeStart` is true when the walk starts at that earliest instant. No day bucket lies
+ * before it, so the windows of the local date before the bucket's own are not reached by walking
+ * back: the walk carries them in (`resolveWindowsBefore`).
  */
 function firstWalkBucket(schedule, fromNs) {
-    const startNs = fromNs - LOOKBACK_NANOSECONDS < MIN_INSTANT_NANOSECONDS
-        ? MIN_INSTANT_NANOSECONDS
-        : fromNs - LOOKBACK_NANOSECONDS;
-    const zoned = Temporal.Instant.fromEpochNanoseconds(startNs).toZonedDateTimeISO(schedule.timeZone);
+    const shift = schedule.frame.shiftNanoseconds;
+    const earliestNs = shift < 0n ? MIN_INSTANT_NANOSECONDS - shift : MIN_INSTANT_NANOSECONDS;
+    if (fromNs < earliestNs) {
+        throw new RangeError("the instant is before the first the frame can place");
+    }
+    const atRangeStart = fromNs - LOOKBACK_NANOSECONDS <= earliestNs;
+    const startNs = atRangeStart ? earliestNs : fromNs - LOOKBACK_NANOSECONDS;
+    const zoned = frameZoned(Temporal.Instant.fromEpochNanoseconds(startNs), schedule.frame);
     try {
-        return zonedUnitStart(zoned, "day");
+        return { bucket: zonedUnitStart(zoned, "day"), atRangeStart };
     }
     catch (error) {
         if (error instanceof RangeError) {
-            return zoned;
+            return { bucket: zoned, atRangeStart };
         }
         throw error;
     }
@@ -278,14 +304,16 @@ function windowsOn(schedule, date) {
     return schedule.holidays.has(key) ? [] : schedule.weekly[date.dayOfWeek];
 }
 /**
- * Resolve one window edge with `resolveLocal`. `local` is `null` for a wrap past Temporal's last
- * date. A wall time outside Temporal's range fails under every policy, so it resolves just
- * outside the range, on the side its date lies. `undefined` means `"reject"` refused it.
+ * Resolve one window edge with `resolveLocal`. An edge on a date Temporal cannot hold is already
+ * outside the range. A wall time outside Temporal's range fails under every policy, so it
+ * resolves just outside the range, on the side its date lies. `undefined` means `"reject"`
+ * refused it.
  */
-function resolveEdge(local, date, timeZone, disambiguation) {
-    if (local === null) {
-        return { ns: PAST_LAST_INSTANT, text: "" };
+function resolveEdge(edge, timeZone, disambiguation) {
+    if (typeof edge === "bigint") {
+        return { ns: edge, text: "" };
     }
+    const local = `${edge.date.toString()}T${edge.time}`;
     const text = resolveLocal(local, timeZone, { disambiguation });
     if (text !== "") {
         return { ns: Temporal.Instant.from(text).epochNanoseconds, text };
@@ -294,14 +322,43 @@ function resolveEdge(local, date, timeZone, disambiguation) {
         return undefined;
     }
     return {
-        ns: date.year > 0 ? PAST_LAST_INSTANT : BEFORE_FIRST_INSTANT,
+        ns: edge.date.year > 0 ? PAST_LAST_INSTANT : BEFORE_FIRST_INSTANT,
         text: "",
     };
 }
+/** The local date after `date`, or `null` past Temporal's last date. */
+function dateAfter(date) {
+    try {
+        return date.add({ days: 1 });
+    }
+    catch (error) {
+        if (error instanceof RangeError) {
+            return null;
+        }
+        throw error;
+    }
+}
+/** The local date before `date`, or `null` before Temporal's first date. */
+function dateBefore(date) {
+    try {
+        return date.subtract({ days: 1 });
+    }
+    catch (error) {
+        if (error instanceof RangeError) {
+            return null;
+        }
+        throw error;
+    }
+}
 /**
- * Resolve one date's windows to instants with `resolveLocal`. Each edge is resolved on its own
- * under `disambiguation`; a wrapping window's `to` is read on the next date. An edge pair that
- * resolves to an empty or inverted span (a window shorter than the gap it straddles) is dropped.
+ * Resolve the windows of one local date to instants with `resolveLocal`. Each edge is resolved on
+ * its own under `disambiguation`; a wrapping window's `to` is read on the next date. An edge pair
+ * that resolves to an empty or inverted span (a window shorter than the gap it straddles) is
+ * dropped.
+ *
+ * `date` is `null` for the date before Temporal's first, and `next` is `null` for the date after
+ * its last. A window is a rule about the local clock, so it still holds on the side of it that
+ * Temporal can reach: an edge on a date Temporal cannot hold lies just outside the range.
  *
  * Under `"earlier"`, an edge in a gap moves back by the gap's length (TC39
  * DisambiguatePossibleEpochNanoseconds), so a date whose midnight is skipped can open before its
@@ -312,31 +369,24 @@ function resolveEdge(local, date, timeZone, disambiguation) {
  * in `unresolved` as the widest span it could cover (its start read `"earlier"`, its end
  * `"later"`), so the caller can refuse an answer it might change and ignore it elsewhere.
  */
-function resolveDateWindows(schedule, date, disambiguation) {
+function resolveDateWindows(schedule, windows, date, next, disambiguation) {
     const records = [];
     const unresolved = [];
     const { timeZone } = schedule;
-    for (const window of windowsOn(schedule, date)) {
-        let endDate = date;
-        if (window.wraps) {
-            try {
-                endDate = date.add({ days: 1 });
-            }
-            catch (error) {
-                if (!(error instanceof RangeError)) {
-                    throw error;
-                }
-                endDate = null;
-            }
-        }
-        const startLocal = `${date.toString()}T${window.from}`;
-        const endLocal = endDate === null ? null : `${endDate.toString()}T${window.to}`;
-        const start = resolveEdge(startLocal, date, timeZone, disambiguation);
-        const end = resolveEdge(endLocal, endDate ?? date, timeZone, disambiguation);
+    for (const window of windows) {
+        const startEdge = date === null ? BEFORE_FIRST_INSTANT : { date, time: window.from };
+        const endDate = window.wraps ? next : date;
+        const endEdge = endDate === null
+            ? window.wraps
+                ? PAST_LAST_INSTANT
+                : BEFORE_FIRST_INSTANT
+            : { date: endDate, time: window.to };
+        const start = resolveEdge(startEdge, timeZone, disambiguation);
+        const end = resolveEdge(endEdge, timeZone, disambiguation);
         if (start === undefined || end === undefined) {
             // "earlier" and "later" always resolve, so the widest span is always known.
-            const earliest = resolveEdge(startLocal, date, timeZone, "earlier");
-            const latest = resolveEdge(endLocal, endDate ?? date, timeZone, "later");
+            const earliest = resolveEdge(startEdge, timeZone, "earlier");
+            const latest = resolveEdge(endEdge, timeZone, "later");
             unresolved.push({
                 start: earliest?.ns ?? BEFORE_FIRST_INSTANT,
                 end: latest?.ns ?? PAST_LAST_INSTANT,
@@ -354,6 +404,38 @@ function resolveDateWindows(schedule, date, disambiguation) {
     }
     return { records, unresolved };
 }
+/**
+ * Resolve the windows of the local date before `date`, the first date of a walk that starts at
+ * the earliest instant its frame can place.
+ *
+ * A window that opened on that date and wraps past midnight is still open on `date`, although
+ * the instant it opened at is before the range. The previous date follows its own override or
+ * holiday like any other. West of UTC the first date is Temporal's first, `-271821-04-19`, and
+ * the date before it cannot be held or named: no override or holiday can be written for it, so
+ * the weekly pattern applies, by the weekday before `date`'s.
+ */
+function resolveWindowsBefore(schedule, date, disambiguation) {
+    const previous = dateBefore(date);
+    const windows = previous === null
+        ? schedule.weekly[date.dayOfWeek === 1 ? 7 : date.dayOfWeek - 1]
+        : windowsOn(schedule, previous);
+    return resolveDateWindows(schedule, windows, previous, date, disambiguation);
+}
+/**
+ * Resolve the windows a walk gains on reaching `date`: the date's own and, for the first date of
+ * a walk from the start of the range (`carryIn`), those of the date before it.
+ */
+function resolveVisit(schedule, date, carryIn, disambiguation) {
+    const own = resolveDateWindows(schedule, windowsOn(schedule, date), date, dateAfter(date), disambiguation);
+    if (!carryIn) {
+        return own;
+    }
+    const before = resolveWindowsBefore(schedule, date, disambiguation);
+    return {
+        records: [...before.records, ...own.records],
+        unresolved: [...before.unresolved, ...own.unresolved],
+    };
+}
 /**
  * Walk the schedule's local dates from a little before `fromNs`, handing the visitor each open
  * run as soon as no later window can extend it.
@@ -364,6 +446,8 @@ function resolveDateWindows(schedule, date, disambiguation) {
  * - A window can start as early as the previous date's first instant (see `resolveDateWindows`),
  *   so the walk settles one date behind: once a date is resolved, the first instant of the date
  *   resolved before it is the `bound` no later window starts before.
+ * - A walk from the start of Temporal's range also resolves the date before its first, whose
+ *   wrapping windows are still open when the range begins (`resolveWindowsBefore`).
  * - When the visitor stops the walk from `day`, or the last representable day is reached, the
  *   runs still pending are handed over too.
  * - Returns `null` when a day bucket could not be found, or the walk would resolve a date
@@ -386,7 +470,10 @@ export function walkSchedule(schedule, fromNs, disambiguation, visitor) {
     // The span a range or search may cover, plus the date after its last, which is resolved to
     // settle it because its windows can start before its own first instant.
     const limitDate = dateLimit(schedule, fromNs, MAX_SCHEDULE_DAYS + 2);
-    let current = firstWalkBucket(schedule, fromNs);
+    const first = firstWalkBucket(schedule, fromNs);
+    let current = first.bucket;
+    // True until the first date is resolved, for a walk from the start of the range.
+    let carryIn = first.atRangeStart;
     let lastDate = null;
     let bound;
     for (let bucket = 0; bucket < MAX_SCHEDULE_BUCKETS; bucket++) {
@@ -416,7 +503,8 @@ export function walkSchedule(schedule, fromNs, disambiguation, visitor) {
                 Temporal.PlainDate.compare(date, limitDate) >= 0) {
                 return null;
             }
-            const resolved = resolveDateWindows(schedule, date, disambiguation);
+            const resolved = resolveVisit(schedule, date, carryIn, disambiguation);
+            carryIn = false;
             for (const window of resolved.unresolved) {
                 if (window.end > fromNs &&
                     (unresolvedStart === undefined || window.start < unresolvedStart)) {
@@ -425,7 +513,7 @@ export function walkSchedule(schedule, fromNs, disambiguation, visitor) {
             }
             pending = coalesceIntervalNanoseconds([...pending, ...resolved.records]);
             lastDate = date;
-            bound = current.epochNanoseconds;
+            bound = frameEpochNanoseconds(current, schedule.frame);
         }
         try {
             current = nextZonedBucketStart(current, "day");

package/dist/internal/patternToken.d.ts

@@ -40,7 +40,14 @@ export interface ParsedPatternFields {
  * fields, or `null` on malformed pattern / no match / invalid input.
  *
  * `null` here always means "return the sentinel" to the caller — it
- * never distinguishes malformed-pattern from no-match from invalid-input,
- * matching the shared never-throw / sentinel-return contract.
+ * never distinguishes malformed-pattern from no-match from invalid-input
+ * from a `yy` token with no window, matching the shared never-throw /
+ * sentinel-return contract.
+ *
+ * `options` is the caller's `TwoDigitYearOptions` bag, already accepted
+ * by `isOptionsArgument`. It is read lazily: only a matched `yy` token
+ * reads `yearWindow`, once, so a pattern without `yy` reads neither the
+ * option nor the clock. A bag that throws when read makes this function
+ * throw; every caller runs it inside `try`.
  */
-export declare function parseValueWithPattern(value: string, pattern: string, locale: LocalesArgument | undefined, allowedFields: ReadonlySet<PatternField>): ParsedPatternFields | null;
+export declare function parseValueWithPattern(value: string, pattern: string, locale: LocalesArgument | undefined, allowedFields: ReadonlySet<PatternField>, options?: unknown): ParsedPatternFields | null;

package/dist/internal/patternToken.js

@@ -1,4 +1,6 @@
 import { resolveLocale } from "./resolveLocale.js";
+import { twoDigitYear } from "./twoDigitYear.js";
+import { readYearWindowStart } from "./yearWindowStart.js";
 import { getLocaleEraNames } from "../plain/locale/getLocaleEraNames.js";
 import { getLocaleMeridiems } from "../plain/locale/getLocaleMeridiems.js";
 import { getLocaleMonthNames } from "../plain/locale/getLocaleMonthNames.js";
@@ -273,15 +275,24 @@ function compilePattern(pattern, allowedFields, locale) {
 }
 /**
  * Resolve a successful regex match's captures back into date/time field
- * values, applying the two-digit-year pivot, 12-hour-to-24-hour
- * conversion (via a matched meridiem), and BCE/CE year adjustment.
+ * values, resolving a two-digit year in the caller's window, converting
+ * 12-hour to 24-hour (via a matched meridiem), and adjusting a BCE year.
  *
  * This step only ever produces a *candidate* fields object — it does not
  * itself prove the fields form a real date/time. The caller is
  * responsible for handing the result to `Temporal.*.from(fields, {
  * overflow: "reject" })`, which is what actually validates it.
+ *
+ * `options` is the caller's `TwoDigitYearOptions` bag, unread. It is read
+ * only when a `yy` token matched, once (`readYearWindowStart`): a pattern
+ * with no `yy` never reads `yearWindow`, and so never reads the clock a
+ * `"rolling"` window needs. Returns `null` when a `yy` token matched and
+ * the bag names no valid window: no standard says which century a
+ * two-digit year belongs to, so without the caller's window the value
+ * cannot be read. Reading a hostile bag throws; the public function's
+ * `try` turns that into its sentinel.
  */
-function resolvePatternFields(match, tokens) {
+function resolvePatternFields(match, tokens, options) {
     const groups = (match.groups ?? {});
     const fields = {};
     let hourIsTwelveHour = false;
@@ -296,11 +307,12 @@ function resolvePatternFields(match, tokens) {
                 fields.year = Number.parseInt(raw, 10);
                 break;
             case "yearShort": {
-                // Two-digit year pivot: 00-68 -> 2000-2068, 69-99 -> 1969-1999.
-                // Fixed rule (mirrors common strptime %y behavior) — not a
-                // configurable/global setting.
-                const numeric = Number.parseInt(raw, 10);
-                fields.year = numeric <= 68 ? 2000 + numeric : 1900 + numeric;
+                // A pattern holds one year token at most (`compilePattern` rejects
+                // a repeated field), so this is the call's only read of the option.
+                const yearWindowStart = readYearWindowStart(options);
+                if (yearWindowStart === null)
+                    return null;
+                fields.year = twoDigitYear(Number.parseInt(raw, 10), yearWindowStart);
                 break;
             }
             case "monthNumber":
@@ -375,10 +387,17 @@ function resolvePatternFields(match, tokens) {
  * fields, or `null` on malformed pattern / no match / invalid input.
  *
  * `null` here always means "return the sentinel" to the caller — it
- * never distinguishes malformed-pattern from no-match from invalid-input,
- * matching the shared never-throw / sentinel-return contract.
+ * never distinguishes malformed-pattern from no-match from invalid-input
+ * from a `yy` token with no window, matching the shared never-throw /
+ * sentinel-return contract.
+ *
+ * `options` is the caller's `TwoDigitYearOptions` bag, already accepted
+ * by `isOptionsArgument`. It is read lazily: only a matched `yy` token
+ * reads `yearWindow`, once, so a pattern without `yy` reads neither the
+ * option nor the clock. A bag that throws when read makes this function
+ * throw; every caller runs it inside `try`.
  */
-export function parseValueWithPattern(value, pattern, locale, allowedFields) {
+export function parseValueWithPattern(value, pattern, locale, allowedFields, options) {
     if (typeof value !== "string" || value.length === 0)
         return null;
     if (typeof pattern !== "string" || pattern.length === 0)
@@ -402,5 +421,5 @@ export function parseValueWithPattern(value, pattern, locale, allowedFields) {
     const match = value.match(compiled.regex);
     if (match === null)
         return null;
-    return resolvePatternFields(match, compiled.tokens);
+    return resolvePatternFields(match, compiled.tokens, options);
 }

package/dist/internal/readDurationUnits.d.ts

@@ -0,0 +1,34 @@
+import type { DateTimeDurationUnit } from "../types/index.js";
+/**
+ * Read a `units` argument, such as `{ minutes: 15 }`, the way Temporal reads a duration-like
+ * object, and return the amounts as a fresh plain object that holds only the caller's units.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `units` must be an Object (`isObject`), a function included.
+ * - An own enumerable string key that `isAllowed` refuses returns `null`, whatever its value.
+ *   This is the guard against a misspelt key, which Temporal on its own ignores. A symbol key and
+ *   a non-enumerable key that is no unit name are not entries and are ignored.
+ * - Each of the ten unit names is read once with an ordinary property get, in the order Temporal's
+ *   ToTemporalPartialDurationRecord reads them, so an inherited or non-enumerable unit applies.
+ *   `undefined` means the unit is absent. Any other value must be a finite number; nothing is
+ *   converted to one.
+ * - A unit `isAllowed` refuses returns `null` when its amount is not zero. Zero is no amount:
+ *   Temporal too tells a calendar duration from an exact one by its nonzero fields.
+ * - No allowed unit present returns `null`.
+ *
+ * Whole numbers, one sign and the range are left to Temporal, which throws for each. A getter
+ * that throws is not caught here; the calling function's own catch returns its sentinel.
+ *
+ * @param units the caller's `units` argument
+ * @param isAllowed type guard for the units the calling function takes
+ * @returns a new plain object of the allowed units that were present, or null on invalid input
+ *
+ * @example readDurationUnits({ minutes: 15 }, isValidTimeDurationUnit) // { minutes: 15 }
+ * @example readDurationUnits({ minutes: 15, hours: undefined }, isValidTimeDurationUnit) // { minutes: 15 }
+ * @example readDurationUnits({ minutes: 15, hour: 1 }, isValidTimeDurationUnit) // null (unknown key)
+ * @example readDurationUnits(Object.create({ minutes: "15" }), isValidTimeDurationUnit) // null (not a number)
+ * @example readDurationUnits(Object.create({ days: 1 }), isValidTimeDurationUnit) // null (a unit outside the set)
+ * @example readDurationUnits({}, isValidTimeDurationUnit) // null
+ */
+export declare function readDurationUnits<Unit extends DateTimeDurationUnit>(units: unknown, isAllowed: (unit: string) => unit is Unit): Partial<Record<Unit, number>> | null;