@northguild/gmt 1.18.0 → 1.20.0

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,25 +387,35 @@ 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)
         return null;
     // No `locale` is required to parse a pattern containing only numeric
     // tokens, but a name-based token (MMM/MMMM/EEE/EEEE/a/GG/GGGG) needs
-    // *some* locale to resolve against — default to "en-US" rather than
+    // *some* locale to resolve against — default to "en" rather than
     // silently returning "" for every caller who didn't have another
-    // locale in mind. An empty preference list names no locale either, so
-    // it takes that same default: ECMA-402 ResolveLocale would answer `[]`
-    // with the *host* locale, which would make a decoder of a fixed
-    // producer format read differently on a French machine (house rule,
-    // ./resolveLocale.ts).
+    // locale in mind. CLDR's `en` holds the English month, weekday, era
+    // and day-period names; a regional tag such as `en-US` adds none of
+    // its own, so the default names the language and no one country
+    // (coding-standards § International authority first). An empty
+    // preference list names no locale either, so it takes that same
+    // default: ECMA-402 ResolveLocale would answer `[]` with the *host*
+    // locale, which would make a decoder of a fixed producer format read
+    // differently on a French machine (house rule, ./resolveLocale.ts).
     const omitted = locale === undefined || (Array.isArray(locale) && locale.length === 0);
-    const resolvedLocale = omitted ? "en-US" : resolveLocale(locale);
+    const resolvedLocale = omitted ? "en" : resolveLocale(locale);
     if (resolvedLocale === null)
         return null;
     const compiled = compilePattern(pattern, allowedFields, resolvedLocale);
@@ -402,5 +424,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/plainDateAdd.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /**
  * `date.add(duration, { overflow })` for a PlainDate in any calendar.
  *

package/dist/internal/plainDateAdd.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { calendarDateAdd } from "./temporalCompat/index.js";
 const NANOSECONDS_PER_HOUR = 3600000000000n;
 const NANOSECONDS_PER_MINUTE = 60000000000n;

package/dist/internal/plainDateUntil.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import type { RoundingOptions } from "../types/index.js";
 /**
  * `start.until(end, { largestUnit, ...rounding })` for two PlainDates in the same calendar.

package/dist/internal/plainDateUntil.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { calendarDateUntil, isCalendarArithmeticCompatNeeded, } from "./temporalCompat/index.js";
 import { plainDateUntilWithRounding } from "./zonedWallClockDifference.js";
 /** Plural date units to Temporal's singular spelling; anything else passes through unchanged. */

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;

package/dist/internal/readDurationUnits.js

@@ -0,0 +1,78 @@
+import { isObject } from "./isObject.js";
+import { isValidAmount } from "./isValidAmount.js";
+/**
+ * The ten fields TC39 Temporal reads from a duration-like object, in the order it reads them:
+ * ToTemporalPartialDurationRecord (7.5.18) gets them in alphabetical order.
+ */
+const DURATION_UNIT_NAMES = [
+    "days",
+    "hours",
+    "microseconds",
+    "milliseconds",
+    "minutes",
+    "months",
+    "nanoseconds",
+    "seconds",
+    "weeks",
+    "years",
+];
+/**
+ * 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 function readDurationUnits(units, isAllowed) {
+    if (!isObject(units)) {
+        return null;
+    }
+    if (!Object.keys(units).every((key) => isAllowed(key))) {
+        return null;
+    }
+    const record = units;
+    const read = {};
+    let present = false;
+    for (const name of DURATION_UNIT_NAMES) {
+        const amount = record[name];
+        if (amount === undefined) {
+            continue;
+        }
+        if (!isValidAmount(amount)) {
+            return null;
+        }
+        if (isAllowed(name)) {
+            read[name] = amount;
+            present = true;
+        }
+        else if (amount !== 0) {
+            return null;
+        }
+    }
+    return present ? read : null;
+}

package/dist/internal/readSetFields.d.ts

@@ -0,0 +1,50 @@
+/** The date fields `setDate` takes. */
+export declare const DATE_FIELDS: readonly ["year", "month", "monthCode", "day"];
+/** The time fields `setTime` takes. */
+export declare const TIME_FIELDS: readonly ["hour", "minute", "second", "millisecond", "microsecond", "nanosecond"];
+/** The fields `setDateTime`, `setUtc`, `setUnix` and `setZoned` take. */
+export declare const DATE_TIME_FIELDS: readonly ["year", "month", "monthCode", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond"];
+/** The one field whose value is a string; every other field a `set*` function takes is a number. */
+declare const STRING_FIELD = "monthCode";
+/** A field a `set*` function may take. */
+type SetField = (typeof DATE_TIME_FIELDS)[number];
+/** The checked values of the fields in `Field`: `monthCode` a string, every other an integer. */
+export type SetFields<Field extends SetField> = {
+    [Name in Field]?: Name extends typeof STRING_FIELD ? string : number;
+};
+/**
+ * Read the `fields` argument of a `set*` function the way Temporal's `with` reads it, and return
+ * the values as a fresh plain object that holds only the fields the function takes.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `fields` must be an Object (`isObject`), a function included, and not a Temporal object that
+ *   holds a date or a time (TC39 IsPartialTemporalObject).
+ * - An own enumerable string key outside `allowedFields` returns `null`, whatever its value: the guard
+ *   against a misspelt key. A symbol key is ignored.
+ * - Each property `with` reads is read once with an ordinary property get, in the order `with`
+ *   reads them, so an inherited, non-enumerable or getter field applies. `undefined` means absent.
+ *   A defined property outside `allowedFields` (another type's field, an era, an offset, a
+ *   `calendar` or a `timeZone`) returns `null`.
+ * - A value is not converted: `monthCode` must be a string, and every other field a number that is
+ *   an integer. `null`, a numeric string, a boolean and a fraction return `null`, where Temporal
+ *   would convert or truncate them. A bigint, `NaN` and an infinity return `null` too; Temporal
+ *   throws for them (ToIntegerWithTruncation).
+ *
+ * Range and overflow are left to Temporal. An empty result means nothing is set: the function
+ * returns its value unchanged, where Temporal's `with` would throw. A getter that throws is not
+ * caught here, nor is a Proxy's `getPrototypeOf` trap that throws; the calling function's own catch
+ * returns its sentinel.
+ *
+ * @param fields the caller's `fields` argument
+ * @param allowedFields the fields the calling function takes
+ * @returns a new plain object of the fields set, empty when none is, or null on invalid input
+ *
+ * @example readSetFields({ year: 2025 }, DATE_FIELDS) // { year: 2025 }
+ * @example readSetFields({}, DATE_FIELDS) // {} (nothing set)
+ * @example readSetFields({ year: "2025" }, DATE_FIELDS) // null (not converted)
+ * @example readSetFields({ year: 2025, yaer: 1 }, DATE_FIELDS) // null (misspelt key)
+ * @example readSetFields({ year: 2025, hour: 5 }, DATE_FIELDS) // null (a field setDate does not take)
+ */
+export declare function readSetFields<Field extends SetField>(fields: unknown, allowedFields: readonly Field[]): SetFields<Field> | null;
+export {};

package/dist/internal/readSetFields.js

@@ -0,0 +1,179 @@
+import { Temporal } from "./temporal.js";
+import { isObject } from "./isObject.js";
+/** The date fields `setDate` takes. */
+export const DATE_FIELDS = ["year", "month", "monthCode", "day"];
+/** The time fields `setTime` takes. */
+export const TIME_FIELDS = [
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/** The fields `setDateTime`, `setUtc`, `setUnix` and `setZoned` take. */
+export const DATE_TIME_FIELDS = [...DATE_FIELDS, ...TIME_FIELDS];
+/**
+ * Every property TC39 Temporal's `with` methods read from their argument, in the order they read
+ * them: `calendar` and `timeZone` first, which IsPartialTemporalObject (13.24) refuses, then the
+ * date and time fields and the `offset` that `ZonedDateTime.prototype.with` reads, in code-unit
+ * order. PrepareCalendarFields (12.3.3) sorts them so for every `with` that takes a date, and
+ * ToTemporalTimeRecord (4.5.12), which `PlainTime.prototype.with` uses, reads its six fields in
+ * the same order. The list adds the era fields,
+ * which `with` never reads for the ISO 8601 calendar (CalendarExtraFields returns none) and which
+ * GMT reads only to refuse them.
+ */
+const WITH_PROPERTY_NAMES = [
+    "calendar",
+    "timeZone",
+    "day",
+    "era",
+    "eraYear",
+    "hour",
+    "microsecond",
+    "millisecond",
+    "minute",
+    "month",
+    "monthCode",
+    "nanosecond",
+    "offset",
+    "second",
+    "year",
+];
+/** The one field whose value is a string; every other field a `set*` function takes is a number. */
+const STRING_FIELD = "monthCode";
+/**
+ * For each Temporal class whose objects hold a date or a time (the internal slots TC39
+ * IsPartialTemporalObject tests), a getter that throws for any receiver without that slot.
+ */
+const BRANDED_GETTERS = [
+    ["PlainDate", "calendarId"],
+    ["PlainDateTime", "calendarId"],
+    ["PlainMonthDay", "calendarId"],
+    ["PlainYearMonth", "calendarId"],
+    ["ZonedDateTime", "calendarId"],
+    ["PlainTime", "hour"],
+];
+/** Whether `value` holds the internal slot of one class of `namespace`. */
+function isObjectOf(namespace, value) {
+    return BRANDED_GETTERS.some(([name, key]) => {
+        const prototype = namespace[name]?.prototype;
+        const getter = isObject(prototype)
+            ? Object.getOwnPropertyDescriptor(prototype, key)?.get
+            : undefined;
+        if (typeof getter !== "function") {
+            return false;
+        }
+        try {
+            getter.call(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Whether `value` is an object of the Temporal the host provides on `globalThis`, if any. A
+ * malformed host Temporal recognises nothing, so it never changes the result for a field object.
+ */
+function isHostTemporalObject(value) {
+    try {
+        const host = globalThis.Temporal;
+        return (isObject(host) &&
+            host !== Temporal &&
+            isObjectOf(host, value));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `value` is a Temporal object that holds a date or a time, from the polyfill GMT uses or
+ * from a Temporal the host provides. The test is the one a class's own getter makes: it reads the
+ * internal slot, so neither the prototype chain nor any property of `value` decides it.
+ *
+ * The check calls up to six getters, twelve with a host Temporal, and a throwing getter is slow, so
+ * it is skipped when the prototype is `Object.prototype`, `null` or `Function.prototype`: a plain
+ * object, an `Object.create(null)` object or a function, which no Temporal class makes.
+ *
+ * Limits:
+ * - An object from a second copy of the polyfill that is not on `globalThis` is not detected and
+ *   is read as a field bag, which is also what TC39 IsPartialTemporalObject (13.24) does with an
+ *   object that lacks this polyfill's internal slots.
+ * - A Temporal object whose prototype was swapped to one of the three above is not detected
+ *   either. Its getters are then out of reach, so it reads as setting nothing and the function
+ *   returns its value unchanged (accepted by owner decision for the speed of the plain case).
+ */
+function isTemporalDateOrTimeObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype ||
+        prototype === null ||
+        prototype === Function.prototype) {
+        return false;
+    }
+    return (isObjectOf(Temporal, value) ||
+        isHostTemporalObject(value));
+}
+/** Whether `value` is one Temporal reads for `name` without converting it. */
+function isFieldValue(name, value) {
+    return name === STRING_FIELD
+        ? typeof value === "string"
+        : typeof value === "number" && Number.isInteger(value);
+}
+/**
+ * Read the `fields` argument of a `set*` function the way Temporal's `with` reads it, and return
+ * the values as a fresh plain object that holds only the fields the function takes.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `fields` must be an Object (`isObject`), a function included, and not a Temporal object that
+ *   holds a date or a time (TC39 IsPartialTemporalObject).
+ * - An own enumerable string key outside `allowedFields` returns `null`, whatever its value: the guard
+ *   against a misspelt key. A symbol key is ignored.
+ * - Each property `with` reads is read once with an ordinary property get, in the order `with`
+ *   reads them, so an inherited, non-enumerable or getter field applies. `undefined` means absent.
+ *   A defined property outside `allowedFields` (another type's field, an era, an offset, a
+ *   `calendar` or a `timeZone`) returns `null`.
+ * - A value is not converted: `monthCode` must be a string, and every other field a number that is
+ *   an integer. `null`, a numeric string, a boolean and a fraction return `null`, where Temporal
+ *   would convert or truncate them. A bigint, `NaN` and an infinity return `null` too; Temporal
+ *   throws for them (ToIntegerWithTruncation).
+ *
+ * Range and overflow are left to Temporal. An empty result means nothing is set: the function
+ * returns its value unchanged, where Temporal's `with` would throw. A getter that throws is not
+ * caught here, nor is a Proxy's `getPrototypeOf` trap that throws; the calling function's own catch
+ * returns its sentinel.
+ *
+ * @param fields the caller's `fields` argument
+ * @param allowedFields the fields the calling function takes
+ * @returns a new plain object of the fields set, empty when none is, or null on invalid input
+ *
+ * @example readSetFields({ year: 2025 }, DATE_FIELDS) // { year: 2025 }
+ * @example readSetFields({}, DATE_FIELDS) // {} (nothing set)
+ * @example readSetFields({ year: "2025" }, DATE_FIELDS) // null (not converted)
+ * @example readSetFields({ year: 2025, yaer: 1 }, DATE_FIELDS) // null (misspelt key)
+ * @example readSetFields({ year: 2025, hour: 5 }, DATE_FIELDS) // null (a field setDate does not take)
+ */
+export function readSetFields(fields, allowedFields) {
+    const allowed = allowedFields;
+    if (!isObject(fields) || isTemporalDateOrTimeObject(fields)) {
+        return null;
+    }
+    if (!Object.keys(fields).every((key) => allowed.includes(key))) {
+        return null;
+    }
+    const record = fields;
+    const read = {};
+    for (const name of WITH_PROPERTY_NAMES) {
+        const value = record[name];
+        if (value === undefined) {
+            continue;
+        }
+        if (!allowed.includes(name) || !isFieldValue(name, value)) {
+            return null;
+        }
+        read[name] = value;
+    }
+    return read;
+}

package/dist/internal/resolveDurationRelativeTo.d.ts

@@ -10,7 +10,7 @@ import type { DurationRelativeTo } from "../types/index.js";
  *   and a zoned date without a time throw, although Temporal's `ParseTemporalRelativeToString`
  *   reads them.
  * - A string with a `u-ca` annotation is read as Temporal's `ParseTemporalRelativeToString` reads
- *   it: with a time zone annotation it is a ZonedDateTime (`"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`,
+ *   it: with a time zone annotation it is a ZonedDateTime (`"2024-02-24T00:00:00+02:00[Asia/Jerusalem][u-ca=hebrew]"`,
  *   `parseCalendarZonedValue`), otherwise a PlainDate (`"2024-02-24[u-ca=hebrew]"`, or a date-time
  *   whose time Temporal drops, `parseCalendarDateValue`). Annotations follow Temporal's
  *   grammar: elective unknown ones are ignored, the first `u-ca` wins, and an unknown critical

package/dist/internal/resolveDurationRelativeTo.js

@@ -38,7 +38,7 @@ function hasRelativeToShape(value) {
  *   and a zoned date without a time throw, although Temporal's `ParseTemporalRelativeToString`
  *   reads them.
  * - A string with a `u-ca` annotation is read as Temporal's `ParseTemporalRelativeToString` reads
- *   it: with a time zone annotation it is a ZonedDateTime (`"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`,
+ *   it: with a time zone annotation it is a ZonedDateTime (`"2024-02-24T00:00:00+02:00[Asia/Jerusalem][u-ca=hebrew]"`,
  *   `parseCalendarZonedValue`), otherwise a PlainDate (`"2024-02-24[u-ca=hebrew]"`, or a date-time
  *   whose time Temporal drops, `parseCalendarDateValue`). Annotations follow Temporal's
  *   grammar: elective unknown ones are ignored, the first `u-ca` wins, and an unknown critical

package/dist/internal/resolveLocale.d.ts

@@ -6,7 +6,7 @@ export type LocalesArgument = string | string[];
  * Resolve a `locale` argument to the single BCP 47 tag a locale-aware function reads.
  *
  * - Follows ECMA-402 CanonicalizeLocaleList: a string is a one-tag list, every tag is
- *   canonicalized (`"EN-us"` → `"en-US"`) and duplicates are dropped.
+ *   canonicalized (`"EN-gb"` → `"en-GB"`) and duplicates are dropped.
  * - The first tag with available locale data wins (`Intl.DateTimeFormat.supportedLocalesOf`), as
  *   ECMA-402's locale negotiation picks; a list with no available tag keeps its first tag, exactly
  *   as that tag passed alone would be read.
@@ -30,7 +30,7 @@ export declare function resolveLocale(locales: unknown): string | null;
  * @param locales raw locale argument from caller input
  * @returns the resolved BCP 47 tag, or `null` when the argument is omitted, empty or invalid
  *
- * @example resolveRequiredLocale("EN-us") // "en-US"
+ * @example resolveRequiredLocale("EN-gb") // "en-GB"
  * @example resolveRequiredLocale(undefined) // null
  * @example resolveRequiredLocale([]) // null
  */

package/dist/internal/resolveLocale.js

@@ -2,7 +2,7 @@
  * Resolve a `locale` argument to the single BCP 47 tag a locale-aware function reads.
  *
  * - Follows ECMA-402 CanonicalizeLocaleList: a string is a one-tag list, every tag is
- *   canonicalized (`"EN-us"` → `"en-US"`) and duplicates are dropped.
+ *   canonicalized (`"EN-gb"` → `"en-GB"`) and duplicates are dropped.
  * - The first tag with available locale data wins (`Intl.DateTimeFormat.supportedLocalesOf`), as
  *   ECMA-402's locale negotiation picks; a list with no available tag keeps its first tag, exactly
  *   as that tag passed alone would be read.
@@ -46,7 +46,7 @@ export function resolveLocale(locales) {
  * @param locales raw locale argument from caller input
  * @returns the resolved BCP 47 tag, or `null` when the argument is omitted, empty or invalid
  *
- * @example resolveRequiredLocale("EN-us") // "en-US"
+ * @example resolveRequiredLocale("EN-gb") // "en-GB"
  * @example resolveRequiredLocale(undefined) // null
  * @example resolveRequiredLocale([]) // null
  */

package/dist/internal/resolveManualRoundingOptions.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Read `roundingIncrement` and `roundingMode` the way Temporal does, for a rounding GMT computes
  * itself (a date unit that Temporal's own `round()` does not accept).

package/dist/internal/resolveRelativeUnit.d.ts

@@ -14,7 +14,7 @@ import type { RelativeUnit } from "../types/index.js";
  *   stricter than Temporal: GetOption converts any value with ToString, so Temporal accepts
  *   `["day"]` and an object whose `toString` returns `"day"` (test262
  *   `largestunit-wrong-type.js`). GMT takes string inputs, and its other unit readers
- *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `durationAs`,
+ *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `totalDuration`,
  *   `areDatesEqualBy`) reject a non-string the same way, so this one does not convert either.
  *
  * @param largestUnit the option as read from the caller's object, `undefined` when absent

package/dist/internal/resolveRelativeUnit.js

@@ -13,7 +13,7 @@
  *   stricter than Temporal: GetOption converts any value with ToString, so Temporal accepts
  *   `["day"]` and an object whose `toString` returns `"day"` (test262
  *   `largestunit-wrong-type.js`). GMT takes string inputs, and its other unit readers
- *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `durationAs`,
+ *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `totalDuration`,
  *   `areDatesEqualBy`) reject a non-string the same way, so this one does not convert either.
  *
  * @param largestUnit the option as read from the caller's object, `undefined` when absent

package/dist/internal/resolveUnixIntervalPair.d.ts

@@ -1,10 +1,13 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 import { type UnixEpochUnit } from "./unixEpochValue.js";
+import { type ZoneFrame } from "./zoneFrame.js";
 export interface ResolvedUnixInterval {
     startVal: Temporal.ZonedDateTime;
     endVal: Temporal.ZonedDateTime;
     resolvedUnit: Temporal.DateTimeUnit;
     epochUnit: UnixEpochUnit;
+    /** The frame both ends were placed on; `frameInstant` turns a result back into an instant. */
+    frame: ZoneFrame;
 }
 /**
  * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
@@ -13,13 +16,16 @@ export interface ResolvedUnixInterval {
  *
  * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
  * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
- *   system zone, an unknown zone is invalid).
+ *   system zone; a time zone identifier or a stored UTC offset `±HH:MM[:SS]` is read as written;
+ *   anything else is invalid).
+ * - The ends are placed with `frameZoned`: for a seconds offset they sit in the offset's
+ *   whole-minute zone, moved by its seconds, to compute with and never to write.
  *
  * @param start interval start epoch
  * @param end interval end epoch
  * @param unit unit name, singular or plural
  * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ * @returns the zoned ends, singular unit, epoch unit and frame, or null on invalid input
  *
  * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
  * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)