@northguild/gmt 1.17.0 → 1.19.0

package/dist/internal/optionOrDefault.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The value of an option that was read once, or its default when the option is absent.
+ *
+ * - ECMA-402 `GetOption` (the Temporal specification defines the same operation) reads the
+ *   property with one `Get` and returns the default only when that value is `undefined`. Pass
+ *   the property read as the argument, so the option is read exactly once: a getter cannot
+ *   answer one value to the check and another to the use.
+ * - `null` is a value, not an omission, so it is returned as it is for the caller to validate.
+ *
+ * @param value the option as read from the caller's object, `undefined` when absent
+ * @param fallback the documented default
+ * @returns `fallback` when `value` is `undefined`, otherwise `value`
+ *
+ * @example optionOrDefault(undefined, "compatible") // "compatible"
+ * @example optionOrDefault("later", "compatible") // "later"
+ * @example optionOrDefault(null, true) // null (a value for the caller to validate)
+ */
+export declare function optionOrDefault<T>(value: T | undefined, fallback: T): T;

package/dist/internal/optionOrDefault.js

@@ -0,0 +1,20 @@
+/**
+ * The value of an option that was read once, or its default when the option is absent.
+ *
+ * - ECMA-402 `GetOption` (the Temporal specification defines the same operation) reads the
+ *   property with one `Get` and returns the default only when that value is `undefined`. Pass
+ *   the property read as the argument, so the option is read exactly once: a getter cannot
+ *   answer one value to the check and another to the use.
+ * - `null` is a value, not an omission, so it is returned as it is for the caller to validate.
+ *
+ * @param value the option as read from the caller's object, `undefined` when absent
+ * @param fallback the documented default
+ * @returns `fallback` when `value` is `undefined`, otherwise `value`
+ *
+ * @example optionOrDefault(undefined, "compatible") // "compatible"
+ * @example optionOrDefault("later", "compatible") // "later"
+ * @example optionOrDefault(null, true) // null (a value for the caller to validate)
+ */
+export function optionOrDefault(value, fallback) {
+    return value === undefined ? fallback : value;
+}

package/dist/internal/patternToken.d.ts

@@ -3,8 +3,8 @@ import { type LocalesArgument } from "./resolveLocale.js";
  * Shared token-pattern engine for J11's `parse*WithPattern` family.
  *
  * This is GMT's one named exception to `context/coding-standards.md`'s
- * "manual string parsing" prohibition (Decision 4 in
- * `context/roadmap/issues/J.md`). The exception is scoped to this module
+ * "manual string parsing" prohibition (its section "Scoped exception:
+ * manual string parsing"). The exception is scoped to this module
  * and the three `parse*WithPattern` public functions, and is bound by
  * three rules, enforced throughout this file:
  *   1. The regex is always built *from the pattern string itself* at call
@@ -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";
@@ -24,9 +26,10 @@ export const DATE_TIME_PATTERN_FIELDS = new Set([
     ...DATE_PATTERN_FIELDS,
     ...TIME_PATTERN_FIELDS,
 ]);
-// Recognized vocabulary letters (Decision 1's Luxon-derived token set,
-// restricted to what's unambiguous to parse — no offset/zone-name tokens
-// since this story is plain-only). Any other unquoted letter in a pattern
+// Recognized vocabulary letters: a subset of the UTS #35 Date Field Symbol
+// Table, with its field lengths (`MMM` abbreviated, `MMMM` wide), restricted
+// to what's unambiguous to parse — no offset/zone-name tokens since this
+// story is plain-only (Decision 1). Any other unquoted letter in a pattern
 // is malformed. Numeric ranges are baked into each regex so a shape
 // mismatch (e.g. "13" for a 12-hour token) fails at the regex stage,
 // before ever reaching Temporal.
@@ -78,13 +81,21 @@ const VOCABULARY_LETTERS = "yMdHhmsSEaG";
 /**
  * Split a pattern string into literal and letter-run parts.
  *
- * Quoted segments (`'...'`) are literals matched verbatim; a doubled `''`
- * *inside* an open quote is the escape for one literal `'` character
- * (mirrors Luxon's own escaping exactly — Decision 1 already establishes
- * Luxon's vocabulary as this story's starting point). Any character that
- * isn't part of a letter run and isn't inside a quote (separators,
- * literal digits, punctuation) is automatically a one-character literal —
- * no explicit quoting required for those.
+ * Literal text follows UTS #35 Part 4, Date Format Patterns
+ * (https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns):
+ *   - "Any characters other than A..Z and a..z, including spaces and
+ *     punctuation" are literals with no quoting.
+ *   - "Any text between single vertical quotes ('xxxx'), which may include
+ *     A..Z and a..z as literal text."
+ *   - "Two adjacent single vertical quotes (''), which represent a literal
+ *     single quote, either inside or outside quoted text."
+ *
+ * The pattern is read left to right, so a `''` pair is taken before a
+ * lone `'` is read as opening or closing quoted text: `''''` is two
+ * literal quotes, and `'''T'` is a literal quote followed by the quoted
+ * text `T`. UTS #35 defines quoted text only as text *between* two
+ * quotes, so a quote that never closes has no defined meaning and the
+ * pattern is malformed (`null`).
  */
 function tokenizePattern(pattern) {
     const parts = [];
@@ -92,6 +103,12 @@ function tokenizePattern(pattern) {
     while (i < pattern.length) {
         const ch = pattern[i];
         if (ch === "'") {
+            // `''` outside quoted text: one literal quote, no quoted text opened.
+            if (pattern[i + 1] === "'") {
+                parts.push({ type: "literal", text: "'" });
+                i += 2;
+                continue;
+            }
             let j = i + 1;
             let text = "";
             let closed = false;
@@ -109,9 +126,9 @@ function tokenizePattern(pattern) {
                 text += pattern[j];
                 j += 1;
             }
-            // An unterminated quote has no unambiguous literal meaning — treat
-            // it as a malformed pattern rather than guessing where it "should"
-            // have closed.
+            // UTS #35 gives quoted text a meaning only between two quotes, so
+            // an unterminated quote is a malformed pattern, not a guess at
+            // where it should have closed.
             if (!closed)
                 return null;
             parts.push({ type: "literal", text });
@@ -258,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;
@@ -281,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":
@@ -360,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)
@@ -387,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/plainDateUntil.js

@@ -24,16 +24,20 @@ function singularDateUnit(unit) {
  * @example plainDateUntil(Temporal.PlainDate.from("2024-01-31"), Temporal.PlainDate.from("2024-03-01"), "months").toString() // "P1M1D"
  */
 export function plainDateUntil(start, end, largestUnit, options) {
-    if (options?.smallestUnit === undefined &&
-        options?.roundingIncrement === undefined &&
-        options?.roundingMode === undefined) {
+    // Each option is read once (GetOption).
+    const smallestUnit = options?.smallestUnit;
+    const roundingIncrement = options?.roundingIncrement;
+    const roundingMode = options?.roundingMode;
+    if (smallestUnit === undefined &&
+        roundingIncrement === undefined &&
+        roundingMode === undefined) {
         return Temporal.Duration.from(calendarDateUntil(start, end, singularDateUnit(largestUnit)));
     }
     const untilOptions = {
         largestUnit: largestUnit,
-        smallestUnit: options.smallestUnit,
-        roundingIncrement: options.roundingIncrement,
-        roundingMode: options.roundingMode,
+        smallestUnit,
+        roundingIncrement,
+        roundingMode,
     };
     // No D11 term here. The nudge window can only miss its target when the target sits strictly
     // between the window bounds by a sub-day amount, which is why every D11 case carries a time

package/dist/internal/punctuality.d.ts

@@ -0,0 +1,38 @@
+import type { Punctuality } from "../types/index.js";
+/** A `PunctualityTolerance` as non-negative exact nanoseconds; `early` is `null` when absent. */
+export type ToleranceNanoseconds = {
+    late: bigint;
+    early: bigint | null;
+};
+/**
+ * Read a `PunctualityTolerance` once into exact nanoseconds, or `null` when it is invalid.
+ *
+ * - `late` and `early` are each read exactly once, so a caller that classifies many pairs under
+ *   one tolerance really uses one tolerance, whatever a getter returns on a later read.
+ * - Each bound is an exact duration (a day is 24 hours; years, months and weeks refused) and not
+ *   negative (`-PT0S` is zero). `late` is required; `early: undefined` is absent and
+ *   `early: null` is invalid.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param tolerance candidate `{ late, early? }`
+ * @returns the bounds in nanoseconds, or null on invalid input
+ *
+ * @example parsePunctualityTolerance({ late: "PT15M" }) // { late: 900000000000n, early: null }
+ * @example parsePunctualityTolerance({ late: "-PT15M" }) // null
+ */
+export declare function parsePunctualityTolerance(tolerance: unknown): ToleranceNanoseconds | null;
+/**
+ * Classify a deviation (actual − planned, exact nanoseconds) against a tolerance.
+ *
+ * Late when the deviation is `late` or more; early when `early` is set and the deviation is
+ * `-early` or less; on time strictly between. Late is checked first, so with both bounds zero the
+ * plan itself is late.
+ *
+ * @param deviation actual minus planned, in nanoseconds
+ * @param tolerance the bounds from `parsePunctualityTolerance`
+ * @returns "early", "onTime" or "late"
+ *
+ * @example punctualityOf(900000000000n, { late: 900000000000n, early: null }) // "late"
+ * @example punctualityOf(0n, { late: 900000000000n, early: 0n }) // "early"
+ */
+export declare function punctualityOf(deviation: bigint, tolerance: ToleranceNanoseconds): Punctuality;

package/dist/internal/punctuality.js

@@ -0,0 +1,59 @@
+import { nonNegativeExactDurationNanoseconds } from "./exactDuration.js";
+import { isObject } from "./isObject.js";
+/**
+ * Read a `PunctualityTolerance` once into exact nanoseconds, or `null` when it is invalid.
+ *
+ * - `late` and `early` are each read exactly once, so a caller that classifies many pairs under
+ *   one tolerance really uses one tolerance, whatever a getter returns on a later read.
+ * - Each bound is an exact duration (a day is 24 hours; years, months and weeks refused) and not
+ *   negative (`-PT0S` is zero). `late` is required; `early: undefined` is absent and
+ *   `early: null` is invalid.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param tolerance candidate `{ late, early? }`
+ * @returns the bounds in nanoseconds, or null on invalid input
+ *
+ * @example parsePunctualityTolerance({ late: "PT15M" }) // { late: 900000000000n, early: null }
+ * @example parsePunctualityTolerance({ late: "-PT15M" }) // null
+ */
+export function parsePunctualityTolerance(tolerance) {
+    try {
+        if (!isObject(tolerance)) {
+            return null;
+        }
+        const { late, early } = tolerance;
+        const lateNanoseconds = nonNegativeExactDurationNanoseconds(late);
+        const earlyNanoseconds = early === undefined ? null : nonNegativeExactDurationNanoseconds(early);
+        if (lateNanoseconds === null ||
+            (early !== undefined && earlyNanoseconds === null)) {
+            return null;
+        }
+        return { late: lateNanoseconds, early: earlyNanoseconds };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Classify a deviation (actual − planned, exact nanoseconds) against a tolerance.
+ *
+ * Late when the deviation is `late` or more; early when `early` is set and the deviation is
+ * `-early` or less; on time strictly between. Late is checked first, so with both bounds zero the
+ * plan itself is late.
+ *
+ * @param deviation actual minus planned, in nanoseconds
+ * @param tolerance the bounds from `parsePunctualityTolerance`
+ * @returns "early", "onTime" or "late"
+ *
+ * @example punctualityOf(900000000000n, { late: 900000000000n, early: null }) // "late"
+ * @example punctualityOf(0n, { late: 900000000000n, early: 0n }) // "early"
+ */
+export function punctualityOf(deviation, tolerance) {
+    if (deviation >= tolerance.late) {
+        return "late";
+    }
+    if (tolerance.early !== null && deviation <= -tolerance.early) {
+        return "early";
+    }
+    return "onTime";
+}

package/dist/internal/readDateTimeFormatOptions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Read a caller's `Intl.DateTimeFormat` options once, into a plain object of primitives.
+ *
+ * - A formatter that inspects the options before it hands them to `Intl.DateTimeFormat` would
+ *   otherwise read each one several times, and a getter could answer one value to the check and
+ *   another to the formatter. ECMA-402 CreateDateTimeFormat reads each option with one `Get`
+ *   (GetOption); this does the same, in the same order, and everything after works on the copy.
+ * - Each value is converted once as well, right after its `Get`, as GetOption converts it:
+ *   ToString for a string option, ToNumber for `fractionalSecondDigits`, ToBoolean for `hour12`.
+ *   An option given as an object would otherwise be asked for its value by every
+ *   `Intl.DateTimeFormat` built from the copy, and could answer each one differently. The range
+ *   and the allowed values are still checked by `Intl.DateTimeFormat`. `timeZone` alone is copied
+ *   unconverted, for the caller's own zone rule.
+ * - The object is coerced as ECMA-402 CoerceOptionsToObject coerces it: `undefined` is no options,
+ *   `null` throws TypeError, and a string or a number has none of these properties. Inherited
+ *   properties are read, as `Get` reads them.
+ * - Only the options `Intl.DateTimeFormat` reads are copied, and only those that are not
+ *   `undefined`. Any other key was never read by the formatter, so dropping it changes nothing.
+ *
+ * @param options the caller's options argument
+ * @returns a plain object holding each option that was set, converted to its primitive; throws
+ *   TypeError for `null`, or for a value that cannot be converted, for the caller's sentinel
+ *
+ * @example readDateTimeFormatOptions({ dateStyle: "long", extra: 1 }) // { dateStyle: "long" }
+ * @example readDateTimeFormatOptions({ month: { toString: () => "long" } }) // { month: "long" }
+ * @example readDateTimeFormatOptions(undefined) // {}
+ * @example readDateTimeFormatOptions("x") // {} (a string has no date-time options)
+ * @example readDateTimeFormatOptions(null) // throws TypeError
+ */
+export declare function readDateTimeFormatOptions(options: unknown): Intl.DateTimeFormatOptions;

package/dist/internal/readDateTimeFormatOptions.js

@@ -0,0 +1,93 @@
+/**
+ * The options ECMA-402 CreateDateTimeFormat reads, in the order it reads them: the formatter's own
+ * settings, then `timeZone`, then each date-time component, then `formatMatcher` and the styles.
+ */
+const DATE_TIME_FORMAT_OPTIONS = [
+    "localeMatcher",
+    "calendar",
+    "numberingSystem",
+    "hour12",
+    "hourCycle",
+    "timeZone",
+    "weekday",
+    "era",
+    "year",
+    "month",
+    "day",
+    "dayPeriod",
+    "hour",
+    "minute",
+    "second",
+    "fractionalSecondDigits",
+    "timeZoneName",
+    "formatMatcher",
+    "dateStyle",
+    "timeStyle",
+];
+/**
+ * Convert an option's value as ECMA-402 GetOption converts it for that option's type: ToBoolean
+ * for `hour12`, ToNumber for `fractionalSecondDigits` (GetNumberOption), ToString for every other
+ * option. `timeZone` is the exception and is returned as it was read: each caller has its own
+ * rule for a zone, and one that hands it to `Intl.DateTimeFormat` does so once.
+ *
+ * The template literal and the unary plus are ToString and ToNumber exactly, so a symbol (and a
+ * bigint for a number) throws TypeError as it does inside `Intl.DateTimeFormat`.
+ */
+function convertOption(name, value) {
+    switch (name) {
+        case "timeZone":
+            return value;
+        case "hour12":
+            return Boolean(value);
+        case "fractionalSecondDigits":
+            return +value;
+        default:
+            return `${value}`;
+    }
+}
+/**
+ * Read a caller's `Intl.DateTimeFormat` options once, into a plain object of primitives.
+ *
+ * - A formatter that inspects the options before it hands them to `Intl.DateTimeFormat` would
+ *   otherwise read each one several times, and a getter could answer one value to the check and
+ *   another to the formatter. ECMA-402 CreateDateTimeFormat reads each option with one `Get`
+ *   (GetOption); this does the same, in the same order, and everything after works on the copy.
+ * - Each value is converted once as well, right after its `Get`, as GetOption converts it:
+ *   ToString for a string option, ToNumber for `fractionalSecondDigits`, ToBoolean for `hour12`.
+ *   An option given as an object would otherwise be asked for its value by every
+ *   `Intl.DateTimeFormat` built from the copy, and could answer each one differently. The range
+ *   and the allowed values are still checked by `Intl.DateTimeFormat`. `timeZone` alone is copied
+ *   unconverted, for the caller's own zone rule.
+ * - The object is coerced as ECMA-402 CoerceOptionsToObject coerces it: `undefined` is no options,
+ *   `null` throws TypeError, and a string or a number has none of these properties. Inherited
+ *   properties are read, as `Get` reads them.
+ * - Only the options `Intl.DateTimeFormat` reads are copied, and only those that are not
+ *   `undefined`. Any other key was never read by the formatter, so dropping it changes nothing.
+ *
+ * @param options the caller's options argument
+ * @returns a plain object holding each option that was set, converted to its primitive; throws
+ *   TypeError for `null`, or for a value that cannot be converted, for the caller's sentinel
+ *
+ * @example readDateTimeFormatOptions({ dateStyle: "long", extra: 1 }) // { dateStyle: "long" }
+ * @example readDateTimeFormatOptions({ month: { toString: () => "long" } }) // { month: "long" }
+ * @example readDateTimeFormatOptions(undefined) // {}
+ * @example readDateTimeFormatOptions("x") // {} (a string has no date-time options)
+ * @example readDateTimeFormatOptions(null) // throws TypeError
+ */
+export function readDateTimeFormatOptions(options) {
+    if (options === null) {
+        throw new TypeError("options must be an object or undefined");
+    }
+    const read = {};
+    if (options === undefined) {
+        return read;
+    }
+    const source = Object(options);
+    for (const name of DATE_TIME_FORMAT_OPTIONS) {
+        const value = source[name];
+        if (value !== undefined) {
+            read[name] = convertOption(name, value);
+        }
+    }
+    return read;
+}

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 {};