@northguild/gmt 1.17.0 → 1.19.0

package/dist/utc/calculate/addUtc.d.ts

@@ -6,12 +6,9 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after addition, or "" on invalid input
  *
  * @example addUtc("2024-03-10T12:00:00Z", { days: 5 }) // "2024-03-15T12:00:00Z"
@@ -19,5 +16,11 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * @example addUtc("invalid", { days: 5 }) // ""
  */
 export declare function addUtc(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Jan 31 + 1 month is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/utc/calculate/addUtc.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -11,12 +11,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after addition, or "" on invalid input
  *
  * @example addUtc("2024-03-10T12:00:00Z", { days: 5 }) // "2024-03-15T12:00:00Z"
@@ -29,17 +26,14 @@ export function addUtc(value, units, options) {
             return "";
         }
         const validUtc = isValidUtc(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUtc || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validUtc || amounts === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            const result = zoned.add(units, {
+            const result = zoned.add(amounts, {
                 overflow: resolveOverflow(options?.overflow),
             });
             return result.toInstant().toString();

package/dist/utc/calculate/diffUtc.d.ts

@@ -31,7 +31,7 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24

package/dist/utc/calculate/diffUtc.js

@@ -38,7 +38,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24

package/dist/utc/calculate/diffUtcAsDuration.d.ts

@@ -21,7 +21,7 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUtcAsDuration("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // "PT24H"

package/dist/utc/calculate/diffUtcAsDuration.js

@@ -25,7 +25,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUtcAsDuration("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // "PT24H"

package/dist/utc/calculate/endOfUtc.d.ts

@@ -5,8 +5,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - The end is the last nanosecond of the unit, one nanosecond before the next unit starts.
  * - Returns "" for invalid input.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -14,7 +13,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the end of the unit, or "" on invalid input
  *
  * @example endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"
@@ -24,6 +23,20 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example endOfUtc("invalid", "year") // ""
  */
 export declare function endOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/endOfUtc.js

@@ -5,8 +5,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - The end is the last nanosecond of the unit, one nanosecond before the next unit starts.
  * - Returns "" for invalid input.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -14,7 +13,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the end of the unit, or "" on invalid input
  *
  * @example endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"

package/dist/utc/calculate/isBetweenUtc.d.ts

@@ -3,12 +3,11 @@
  *
  * - Uses Temporal.Instant.compare for comparison.
  * - Returns false if start > end or inputs are invalid.
- * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
  *
  * @param value ISO UTC datetime string to check
  * @param start ISO UTC datetime string for range start
  * @param end ISO UTC datetime string for range end
- * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param options Whether each boundary counts as inside the range
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUtc("2024-03-15T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // true
@@ -16,6 +15,18 @@
  * @example isBetweenUtc("invalid", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
  */
 export declare function isBetweenUtc(value: string, start: string, end: string, options?: {
+    /**
+     * Whether `value` equal to `start` counts as inside the range. `false` requires it to be after
+     * `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `value` equal to `end` counts as inside the range. `false` requires it to be before
+     * `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/utc/calculate/isBetweenUtc.js

@@ -2,17 +2,17 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return true when `value` is between `start` and `end` (inclusive by default).
  *
  * - Uses Temporal.Instant.compare for comparison.
  * - Returns false if start > end or inputs are invalid.
- * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
  *
  * @param value ISO UTC datetime string to check
  * @param start ISO UTC datetime string for range start
  * @param end ISO UTC datetime string for range end
- * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param options Whether each boundary counts as inside the range
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUtc("2024-03-15T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // true
@@ -28,8 +28,8 @@ export function isBetweenUtc(value, start, end, options) {
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
-        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
-        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!isValidUtc(value) || !isValidUtc(start) || !isValidUtc(end)) {
             return false;
         }

package/dist/utc/calculate/roundUtc.d.ts

@@ -4,22 +4,14 @@ import type { FractionalDigit } from "../../types/index.js";
  * Round a UTC datetime string to the specified unit.
  *
  * - Converts to Instant, rounds, converts back to UTC Instant string.
- * - Supports: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Day and larger units ("day", "week", "month", "year") return "". This is the Temporal spec, not
  *   a polyfill limitation: `Instant.prototype.round` validates `smallestUnit` as a time unit
  *   (ValidateTemporalUnitValue with ~time~), because an instant has no calendar or zone to define a
  *   day. Round a zoned value with `roundZoned` for a day boundary.
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
- * - Output precision follows `smallestUnit`: no fractional seconds for "second" and coarser,
- *   3 digits for "millisecond", 6 for "microsecond" and 9 for "nanosecond", so the result never
- *   hides the precision the unit asked for.
- * - `fractionalSecondDigits` overrides that count outright, coarser or finer than the unit; an
- *   invalid value returns "".
  *
  * @param value ISO UTC datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, fractionalSecondDigits
+ * @param options What to round to, how, and the precision of the result
  * @returns Rounded ISO UTC Instant string, or "" on invalid input
  *
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
@@ -33,8 +25,33 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example roundUtc("", { smallestUnit: "hour" }) // ""
  */
 export declare function roundUtc(value: string, options: {
+    /**
+     * The unit to round to: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"` or
+     * `"nanosecond"`, singular or plural as Temporal's GetTemporalUnitValuedOption accepts both.
+     */
     smallestUnit: Temporal.SmallestUnit<"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    /**
+     * The multiple of `smallestUnit` to round to, such as 15 for quarter hours. It must divide a
+     * 24-hour day evenly (Temporal's `Instant.prototype.round`); any other value returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which multiple a value between two is rounded to. `"halfExpand"` picks the nearer one and
+     * sends a tie to the later instant; `"floor"` and `"trunc"` pick the earlier, `"ceil"` and
+     * `"expand"` the later, and the other `"half…"` modes differ only in how a tie breaks.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. It overrides the unit's own count, coarser or finer; an invalid value
+     * returns `""`.
+     *
+     * @defaultValue The digits `smallestUnit` names: `3` for `"millisecond"`, `6` for
+     * `"microsecond"`, `9` for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/roundUtc.js

@@ -6,22 +6,14 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * Round a UTC datetime string to the specified unit.
  *
  * - Converts to Instant, rounds, converts back to UTC Instant string.
- * - Supports: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Day and larger units ("day", "week", "month", "year") return "". This is the Temporal spec, not
  *   a polyfill limitation: `Instant.prototype.round` validates `smallestUnit` as a time unit
  *   (ValidateTemporalUnitValue with ~time~), because an instant has no calendar or zone to define a
  *   day. Round a zoned value with `roundZoned` for a day boundary.
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
- * - Output precision follows `smallestUnit`: no fractional seconds for "second" and coarser,
- *   3 digits for "millisecond", 6 for "microsecond" and 9 for "nanosecond", so the result never
- *   hides the precision the unit asked for.
- * - `fractionalSecondDigits` overrides that count outright, coarser or finer than the unit; an
- *   invalid value returns "".
  *
  * @param value ISO UTC datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, fractionalSecondDigits
+ * @param options What to round to, how, and the precision of the result
  * @returns Rounded ISO UTC Instant string, or "" on invalid input
  *
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
@@ -39,9 +31,8 @@ export function roundUtc(value, options) {
         if (!isObject(options))
             return "";
         const { roundingIncrement, roundingMode, fractionalSecondDigits } = options;
-        const smallestUnit = typeof options.smallestUnit === "string"
-            ? resolveDateTimeUnit(options.smallestUnit)
-            : options.smallestUnit;
+        // One read (GetOption): resolveDateTimeUnit returns a value that is not a string unchanged.
+        const smallestUnit = resolveDateTimeUnit(options.smallestUnit);
         // Temporal Instant.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~)
         if (!isValidUtc(value) || !isValidTimeUnit(smallestUnit))
             return "";

package/dist/utc/calculate/setUtc.d.ts

@@ -9,26 +9,42 @@ import type { Overflow } from "../../types/index.js";
  *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
  *   resolution matters.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- *   (resulting in "").
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string with fields set, or "" on invalid input
  *
  * @example setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
  * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: "9" }) // "" (not converted)
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
-export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset" | "era" | "eraYear">, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so `month: 2` on Jan 31 is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/utc/calculate/setUtc.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
+import { DATE_TIME_FIELDS, readSetFields, resolveOverflow, } from "../../internal/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -11,24 +11,34 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
  *   resolution matters.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- *   (resulting in "").
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string with fields set, or "" on invalid input
  *
  * @example setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
  * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: "9" }) // "" (not converted)
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
 export function setUtc(value, fields, options) {
@@ -42,11 +52,12 @@ export function setUtc(value, fields, options) {
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
-            // properties found") rather than treating it as a no-op, so short-circuit here.
-            const result = Object.keys(fields).length === 0
-                ? zoned
-                : zoned.with(fields, { overflow });
+            const set = readSetFields(fields, DATE_TIME_FIELDS);
+            if (set === null)
+                return "";
+            // Only the values readSetFields checked reach Temporal. An empty result sets nothing: a
+            // no-op here, where Temporal's with() would throw.
+            const result = Object.keys(set).length === 0 ? zoned : zoned.with(set, { overflow });
             return result.toInstant().toString();
         }
         catch {

package/dist/utc/calculate/startOfUtc.d.ts

@@ -5,12 +5,11 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the start
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the start of the unit, or "" on invalid input
  *
  * @example startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"
@@ -19,6 +18,20 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example startOfUtc("invalid", "year") // ""
  */
 export declare function startOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer digits than `unit` names truncate, as Temporal's `toString` does.
+     *
+     * @defaultValue The digits `unit` names: `3` for `"millisecond"`, `6` for `"microsecond"`, `9`
+     * for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/startOfUtc.js

@@ -5,12 +5,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the start
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the start of the unit, or "" on invalid input
  *
  * @example startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"

package/dist/utc/calculate/subtractUtc.d.ts

@@ -6,12 +6,9 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after subtraction, or "" on invalid input
  *
  * @example subtractUtc("2024-03-15T12:00:00Z", { days: 5 }) // "2024-03-10T12:00:00Z"
@@ -19,5 +16,11 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * @example subtractUtc("invalid", { days: 5 }) // ""
  */
 export declare function subtractUtc(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Mar 31 − 1 month is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/utc/calculate/subtractUtc.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -11,12 +11,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after subtraction, or "" on invalid input
  *
  * @example subtractUtc("2024-03-15T12:00:00Z", { days: 5 }) // "2024-03-10T12:00:00Z"
@@ -29,17 +26,14 @@ export function subtractUtc(value, units, options) {
             return "";
         }
         const validUtc = isValidUtc(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUtc || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validUtc || amounts === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            const result = zoned.subtract(units, {
+            const result = zoned.subtract(amounts, {
                 overflow: resolveOverflow(options?.overflow),
             });
             return result.toInstant().toString();

package/dist/utc/compare/areUtcEqualBy.d.ts

@@ -7,13 +7,12 @@ import { Temporal } from "@js-temporal/polyfill";
  *   unambiguous).
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  * - Takes no `fractionalSecondDigits`: equality compares full-precision `unit` boundaries, and output
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUtcEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUtcEqualBy(a, b, "year")`
@@ -21,7 +20,7 @@ import { Temporal } from "@js-temporal/polyfill";
  * @param value1 first UTC ISO datetime string
  * @param value2 second UTC ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param options optional: weekStartsOn ("monday" | "sunday")
+ * @param options Where a week starts
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUtcEqualBy("2024-03-15T02:00:00Z", "2024-03-15T22:00:00Z", "day") // true
@@ -31,5 +30,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example areUtcEqualBy("invalid", "2024-03-15T02:00:00Z", "day") // false
  */
 export declare function areUtcEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;