@northguild/gmt 1.15.0 → 1.17.0

package/dist/utc/calculate/minUtc.js

@@ -15,21 +15,28 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example minUtc([]) // null
  */
 export function minUtc(utcDateTimes) {
-    if (!utcDateTimes.length)
-        return null;
-    const valid = utcDateTimes.filter(isValidUtc);
-    if (!valid.length)
-        return null;
     try {
-        const min = valid.reduce((currentMin, candidateStr) => {
-            const candidate = Temporal.Instant.from(candidateStr);
-            return Temporal.Instant.compare(candidate, currentMin) < 0
-                ? candidate
-                : currentMin;
-        }, Temporal.Instant.from(valid[0]));
-        return min.toString();
+        if (!Array.isArray(utcDateTimes) || !utcDateTimes.length)
+            return null;
+        const valid = utcDateTimes.filter(isValidUtc);
+        if (!valid.length)
+            return null;
+        try {
+            const min = valid.reduce((currentMin, candidateStr) => {
+                const candidate = Temporal.Instant.from(candidateStr);
+                return Temporal.Instant.compare(candidate, currentMin) < 0
+                    ? candidate
+                    : currentMin;
+            }, Temporal.Instant.from(valid[0]));
+            return min.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -5,16 +5,30 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Converts to Instant, rounds, converts back to UTC Instant string.
  * - Supports: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Date units ("year", "month", "week", "day") are not supported by the Temporal polyfill's Instant.round() — they return "".
+ * - 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
  * @returns Rounded ISO UTC Instant string, or "" on invalid input
  *
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
- * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:30:00Z"
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "second", roundingMode: "floor" }) // "2024-06-15T12:34:56Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hours" }) // "2024-06-15T13:00:00Z" (plural unit name)
+ * @example roundUtc("2024-06-15T12:34:56.123456789Z", { smallestUnit: "microsecond" }) // "2024-06-15T12:34:56.123457Z" (precision follows the unit)
+ * @example roundUtc("2024-06-15T12:34:56.123456789Z", { smallestUnit: "nanosecond", fractionalSecondDigits: 3 }) // "2024-06-15T12:34:56.123Z" (explicit digits win)
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "day" as never }) // "" (Instant rounds to time units only)
  * @example roundUtc("invalid", { smallestUnit: "hour" }) // ""
  * @example roundUtc("", { smallestUnit: "hour" }) // ""
  */

package/dist/utc/calculate/roundUtc.js

@@ -1,56 +1,67 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidDateTimeUnit } from "../../plain/index.js";
+import { defaultFractionalDigits, isObject, resolveDateTimeUnit, } from "../../internal/index.js";
+import { isValidTimeUnit } from "../../plain/index.js";
 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".
- * - Date units ("year", "month", "week", "day") are not supported by the Temporal polyfill's Instant.round() — they return "".
+ * - 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
  * @returns Rounded ISO UTC Instant string, or "" on invalid input
  *
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
- * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:30:00Z"
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "second", roundingMode: "floor" }) // "2024-06-15T12:34:56Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hours" }) // "2024-06-15T13:00:00Z" (plural unit name)
+ * @example roundUtc("2024-06-15T12:34:56.123456789Z", { smallestUnit: "microsecond" }) // "2024-06-15T12:34:56.123457Z" (precision follows the unit)
+ * @example roundUtc("2024-06-15T12:34:56.123456789Z", { smallestUnit: "nanosecond", fractionalSecondDigits: 3 }) // "2024-06-15T12:34:56.123Z" (explicit digits win)
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "day" as never }) // "" (Instant rounds to time units only)
  * @example roundUtc("invalid", { smallestUnit: "hour" }) // ""
  * @example roundUtc("", { smallestUnit: "hour" }) // ""
  */
 export function roundUtc(value, options) {
-    const { smallestUnit, roundingIncrement, roundingMode, fractionalSecondDigits, } = options;
-    if (!isValidUtc(value) || !isValidDateTimeUnit(smallestUnit))
-        return "";
-    // Polyfill limitation: day/year/month/week not supported for Instant.round()
-    const supportedUnits = [
-        "hour",
-        "minute",
-        "second",
-        "millisecond",
-        "microsecond",
-        "nanosecond",
-    ];
-    if (!supportedUnits.includes(smallestUnit))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const result = instant.round({
-            smallestUnit,
-            roundingIncrement,
-            roundingMode,
-        });
-        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[smallestUnit] || 0);
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
+        if (!isObject(options))
+            return "";
+        const { roundingIncrement, roundingMode, fractionalSecondDigits } = options;
+        const smallestUnit = typeof options.smallestUnit === "string"
+            ? resolveDateTimeUnit(options.smallestUnit)
+            : options.smallestUnit;
+        // Temporal Instant.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~)
+        if (!isValidUtc(value) || !isValidTimeUnit(smallestUnit))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const result = instant.round({
+                smallestUnit,
+                roundingIncrement,
+                roundingMode,
+            });
+            const fractionalDigits = defaultFractionalDigits(smallestUnit, fractionalSecondDigits);
+            return result.toString({ fractionalSecondDigits: fractionalDigits });
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
+import type { Overflow } from "../../types/index.js";
 /**
  * Return a UTC Instant string with the given `fields` set on `value`.
  *
@@ -14,15 +14,13 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * - `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 "").
- * - `disambiguation` and `offset` are accepted for API consistency with `setZoned`/`setUnix`,
- *   but are **permanently inert** here: "UTC" has no DST transitions, so there is never an
- *   ambiguous local time or a stale offset for either option to act on (same precedent as
- *   `startOfUtc`/`endOfUtc`, Story C1/C2). Do not "fix" this by removing them.
+ * - 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"), disambiguation (accepted but inert, see above), offset (accepted but inert, see above)
+ * @param options optional: overflow ("constrain" | "reject")
  * @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"
@@ -33,6 +31,4 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  */
 export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
     overflow?: Overflow;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): string;

package/dist/utc/calculate/setUtc.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { resolveOverflow } from "../../internal/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a UTC Instant string with the given `fields` set on `value`.
  *
@@ -15,15 +16,13 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * - `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 "").
- * - `disambiguation` and `offset` are accepted for API consistency with `setZoned`/`setUnix`,
- *   but are **permanently inert** here: "UTC" has no DST transitions, so there is never an
- *   ambiguous local time or a stale offset for either option to act on (same precedent as
- *   `startOfUtc`/`endOfUtc`, Story C1/C2). Do not "fix" this by removing them.
+ * - 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"), disambiguation (accepted but inert, see above), offset (accepted but inert, see above)
+ * @param options optional: overflow ("constrain" | "reject")
  * @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"
@@ -33,22 +32,30 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
 export function setUtc(value, fields, options) {
-    if (!isValidUtc(value))
-        return "";
-    const overflow = resolveOverflow(options?.overflow);
-    const disambiguation = options?.disambiguation ?? "compatible";
-    const offset = options?.offset ?? "ignore";
     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, disambiguation, offset });
-        return result.toInstant().toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        if (!isValidUtc(value))
+            return "";
+        const overflow = resolveOverflow(options?.overflow);
+        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 });
+            return result.toInstant().toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/calculate/sortUtc.js

@@ -17,20 +17,27 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example sortUtc([]) // []
  */
 export function sortUtc(utcDateTimes, order = "asc") {
-    if (!utcDateTimes.length)
-        return [];
-    const valid = utcDateTimes.filter(isValidUtc);
-    if (!valid.length)
-        return [];
     try {
-        const comparables = valid.map((d) => Temporal.Instant.from(d));
-        comparables.sort(Temporal.Instant.compare);
-        if (order === "desc") {
-            return comparables.reverse().map((d) => d.toString());
+        if (!Array.isArray(utcDateTimes) || !utcDateTimes.length)
+            return [];
+        const valid = utcDateTimes.filter(isValidUtc);
+        if (!valid.length)
+            return [];
+        try {
+            const comparables = valid.map((d) => Temporal.Instant.from(d));
+            comparables.sort(Temporal.Instant.compare);
+            if (order === "desc") {
+                return comparables.reverse().map((d) => d.toString());
+            }
+            return comparables.map((d) => d.toString());
+        }
+        catch {
+            return [];
         }
-        return comparables.map((d) => d.toString());
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

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

@@ -2,12 +2,14 @@
  * Return the start of the quarter for a given UTC datetime string.
  *
  * - Calculates quarter start month: Q1=1, Q2=4, Q3=7, Q4=10.
+ * - Resets every time field, including milliseconds, microseconds and nanoseconds.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-15T12:00:00Z")
  * @returns ISO UTC datetime string representing the start of the quarter, or "" on invalid input
  *
  * @example startOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-01-01T00:00:00Z"
+ * @example startOfQuarterForUtc("2024-05-15T12:34:56.789Z") // "2024-04-01T00:00:00Z"
  * @example startOfQuarterForUtc("invalid") // ""
  */
 export declare function startOfQuarterForUtc(value: string): string;

package/dist/utc/calculate/startOfQuarterForUtc.js

@@ -4,12 +4,14 @@ import { isValidUtc } from "../validate/index.js";
  * Return the start of the quarter for a given UTC datetime string.
  *
  * - Calculates quarter start month: Q1=1, Q2=4, Q3=7, Q4=10.
+ * - Resets every time field, including milliseconds, microseconds and nanoseconds.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-15T12:00:00Z")
  * @returns ISO UTC datetime string representing the start of the quarter, or "" on invalid input
  *
  * @example startOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-01-01T00:00:00Z"
+ * @example startOfQuarterForUtc("2024-05-15T12:34:56.789Z") // "2024-04-01T00:00:00Z"
  * @example startOfQuarterForUtc("invalid") // ""
  */
 export function startOfQuarterForUtc(value) {
@@ -22,7 +24,16 @@ export function startOfQuarterForUtc(value) {
         const month = zdt.month;
         const quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
         const result = zdt
-            .with({ month: quarterStartMonth, day: 1, hour: 0, minute: 0, second: 0 })
+            .with({
+            month: quarterStartMonth,
+            day: 1,
+            hour: 0,
+            minute: 0,
+            second: 0,
+            millisecond: 0,
+            microsecond: 0,
+            nanosecond: 0,
+        })
             .toInstant();
         return result.toString();
     }

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

@@ -1,22 +1,24 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the start of the specified date-time `unit` for a given UTC datetime string.
  *
  * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
- * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - 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 Temporal.DateUnit | Temporal.TimeUnit to specify the start
+ * @param unit date or time unit, singular or plural, to specify the start
  * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @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"
  * @example startOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-01T00:00:00Z"
+ * @example startOfUtc("2024-03-15T14:30:45Z", "days") // "2024-03-15T00:00:00Z"
  * @example startOfUtc("invalid", "year") // ""
  */
-export declare function startOfUtc(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+export declare function startOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
     weekStartsOn?: "monday" | "sunday";
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/startOfUtc.js

@@ -1,21 +1,33 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { startOrEndOfUtc } from "./startOrEndOfUtc.js";
+import { startOrEndOfUtc } from "../../internal/startOrEndOfUtc.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the start of the specified date-time `unit` for a given UTC datetime string.
  *
  * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
- * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - 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 Temporal.DateUnit | Temporal.TimeUnit to specify the start
+ * @param unit date or time unit, singular or plural, to specify the start
  * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @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"
  * @example startOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-01T00:00:00Z"
+ * @example startOfUtc("2024-03-15T14:30:45Z", "days") // "2024-03-15T00:00:00Z"
  * @example startOfUtc("invalid", "year") // ""
  */
 export function startOfUtc(value, unit, options) {
-    return startOrEndOfUtc(value, unit, options ?? {}, false);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return startOrEndOfUtc(value, unit, options ?? {}, false);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

package/dist/utc/calculate/subtractUtc.js

@@ -1,7 +1,9 @@
+// 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 { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Subtract a temporal amount from a UTC datetime string and return a new UTC Instant string.
  *
@@ -22,21 +24,33 @@ import { isValidUtc } from "../validate/index.js";
  * @example subtractUtc("invalid", { days: 5 }) // ""
  */
 export function subtractUtc(value, units, options) {
-    const validUtc = isValidUtc(value);
-    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validUtc || !validUnits || !validAmounts) {
-        return "";
-    }
     try {
-        const instant = Temporal.Instant.from(value);
-        const zoned = instant.toZonedDateTimeISO("UTC");
-        const result = zoned.subtract(units, {
-            overflow: resolveOverflow(options?.overflow),
-        });
-        return result.toInstant().toString();
+        if (!isOptionsArgument(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) {
+            return "";
+        }
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zoned = instant.toZonedDateTimeISO("UTC");
+            const result = zoned.subtract(units, {
+                overflow: resolveOverflow(options?.overflow),
+            });
+            return result.toInstant().toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/chop/chopUtc.d.ts

@@ -1,14 +1,17 @@
 /**
  * Return the UTC datetime string with a trailing Z removed if present.
  *
- * - Uses regex to remove trailing "z" or "Z".
+ * - Removes the trailing "Z"; a lower-case "z" is not a GMT UTC string (`isValidUtc`), so it returns "".
+ * - Drops the RFC 9557 annotations `Temporal.Instant.from` ignores (`[foo=bar]`, `[Europe/Paris]`).
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (ISO 8601)
  * @returns UTC datetime string without trailing Z or "" on invalid input
  *
  * @example chopUtc("2024-03-10T12:00:00Z") // "2024-03-10T12:00:00"
- * @example chopUtc("2024-03-10T12:00:00") // "2024-03-10T12:00:00"
+ * @example chopUtc("2024-03-10T12:00:00") // "" (no Z: not a UTC instant)
+ * @example chopUtc("2024-03-10T12:00:00z") // "" (lower-case z)
  * @example chopUtc("invalid") // ""
+ * @example chopUtc("2024-03-10T12:00:00Z[foo=bar]") // "2024-03-10T12:00:00"
  */
 export declare function chopUtc(value: string): string;

package/dist/utc/chop/chopUtc.js

@@ -1,21 +1,25 @@
+import { isoStringBody } from "../../internal/isoStringBody.js";
 import { isValidUtc } from "../validate/index.js";
 /**
  * Return the UTC datetime string with a trailing Z removed if present.
  *
- * - Uses regex to remove trailing "z" or "Z".
+ * - Removes the trailing "Z"; a lower-case "z" is not a GMT UTC string (`isValidUtc`), so it returns "".
+ * - Drops the RFC 9557 annotations `Temporal.Instant.from` ignores (`[foo=bar]`, `[Europe/Paris]`).
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (ISO 8601)
  * @returns UTC datetime string without trailing Z or "" on invalid input
  *
  * @example chopUtc("2024-03-10T12:00:00Z") // "2024-03-10T12:00:00"
- * @example chopUtc("2024-03-10T12:00:00") // "2024-03-10T12:00:00"
+ * @example chopUtc("2024-03-10T12:00:00") // "" (no Z: not a UTC instant)
+ * @example chopUtc("2024-03-10T12:00:00z") // "" (lower-case z)
  * @example chopUtc("invalid") // ""
+ * @example chopUtc("2024-03-10T12:00:00Z[foo=bar]") // "2024-03-10T12:00:00"
  */
 export function chopUtc(value) {
     if (!isValidUtc(value)) {
         return "";
     }
-    // only shaves off z or Z at the end of the string, if it exists
-    return value.replace(/z$/i, "");
+    // only shaves off the Z at the end of the string, if it exists
+    return isoStringBody(value).replace(/Z$/, "");
 }

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

@@ -1,5 +1,4 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { FractionalDigit } from "../../types/index.js";
 /**
  * Compare two UTC ISO datetime strings for equality at a given unit.
  *
@@ -7,7 +6,12 @@ import type { FractionalDigit } from "../../types/index.js";
  *   so `"day"` always means the UTC calendar day (UTC has no DST, so this is
  *   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`):
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
@@ -16,15 +20,16 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @param value1 first UTC ISO datetime string
  * @param value2 second UTC ISO datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param unit date or time unit, singular or plural, to compare by
+ * @param options optional: weekStartsOn ("monday" | "sunday")
  * @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
  * @example areUtcEqualBy("2024-03-15T23:30:00Z", "2024-03-16T00:30:00Z", "day") // false
+ * @example areUtcEqualBy("2024-05-15T10:20:30.123Z", "2024-05-15T10:20:30.999Z", "milliseconds") // false (different milliseconds)
+ * @example areUtcEqualBy("2024-05-15T10:20:30.123Z", "2024-05-15T10:20:30.999Z", "second") // true
  * @example areUtcEqualBy("invalid", "2024-03-15T02:00:00Z", "day") // false
  */
-export declare function areUtcEqualBy(value1: string, value2: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+export declare function areUtcEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
     weekStartsOn?: "monday" | "sunday";
-    fractionalSecondDigits?: FractionalDigit;
 }): boolean;