@northguild/gmt 1.14.2 → 1.16.0

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;

package/dist/utc/compare/areUtcEqualBy.js

@@ -1,7 +1,10 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTimeUnit } from "../../plain/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { startOfUtc } from "../calculate/startOfUtc.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two UTC ISO datetime strings for equality at a given unit.
  *
@@ -9,7 +12,12 @@ import { isValidUtc } from "../validate/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")`
@@ -18,28 +26,43 @@ import { isValidUtc } from "../validate/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 function areUtcEqualBy(value1, value2, unit, options) {
-    if (!isValidUtc(value1) ||
-        !isValidUtc(value2) ||
-        !isValidDateTimeUnit(unit)) {
-        return false;
-    }
     try {
-        const start1 = startOfUtc(value1, unit, options);
-        const start2 = startOfUtc(value2, unit, options);
-        if (start1 === "" || start2 === "")
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
+        if (!isValidUtc(value1) ||
+            !isValidUtc(value2) ||
+            !isValidDateTimeUnit(resolvedUnit) ||
+            weekStartsOn === null) {
+            return false;
+        }
+        try {
+            const start1 = startOfUtc(value1, resolvedUnit, { weekStartsOn });
+            const start2 = startOfUtc(value2, resolvedUnit, { weekStartsOn });
+            if (start1 === "" || start2 === "")
+                return false;
+            return (Temporal.Instant.compare(Temporal.Instant.from(start1), Temporal.Instant.from(start2)) === 0);
+        }
+        catch {
             return false;
-        return (Temporal.Instant.compare(Temporal.Instant.from(start1), Temporal.Instant.from(start2)) === 0);
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/utc/convert/convertUtcToPlainDate.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../../zoned/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
@@ -17,19 +19,29 @@ import { isValidUtc } from "../validate/index.js";
  * @example convertUtcToPlainDate("invalid") // ""
  */
 export function convertUtcToPlainDate(value, options) {
-    const { timeZone = "UTC" } = options ?? {};
-    if (!isValidTimeZone(timeZone))
-        return "";
-    if (!isValidUtc(value))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-            .toString()
-            .padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`;
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const { timeZone = "UTC" } = options ?? {};
+        if (!isValidTimeZone(timeZone))
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
+                .toString()
+                .padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/convert/convertUtcToPlainDateTime.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../../zoned/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
@@ -17,25 +19,35 @@ import { isValidUtc } from "../validate/index.js";
  * @example convertUtcToPlainDateTime("invalid") // ""
  */
 export function convertUtcToPlainDateTime(value, options) {
-    const { timeZone = "UTC" } = options ?? {};
-    if (!isValidTimeZone(timeZone))
-        return "";
-    if (!isValidUtc(value))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-            .toString()
-            .padStart(2, "0")}-${zonedDateTime.day
-            .toString()
-            .padStart(2, "0")}T${zonedDateTime.hour
-            .toString()
-            .padStart(2, "0")}:${zonedDateTime.minute
-            .toString()
-            .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const { timeZone = "UTC" } = options ?? {};
+        if (!isValidTimeZone(timeZone))
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
+                .toString()
+                .padStart(2, "0")}-${zonedDateTime.day
+                .toString()
+                .padStart(2, "0")}T${zonedDateTime.hour
+                .toString()
+                .padStart(2, "0")}:${zonedDateTime.minute
+                .toString()
+                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/convert/convertUtcToPlainTime.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../../zoned/index.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain time string in the format "HH:mm:ss".
  *
@@ -17,19 +19,29 @@ import { isValidUtc } from "../validate/index.js";
  * @example convertUtcToPlainTime("invalid") // ""
  */
 export function convertUtcToPlainTime(value, options) {
-    const { timeZone = "UTC" } = options ?? {};
-    if (!isValidTimeZone(timeZone))
-        return "";
-    if (!isValidUtc(value))
-        return "";
     try {
-        const instant = Temporal.Instant.from(value);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return `${zonedDateTime.hour.toString().padStart(2, "0")}:${zonedDateTime.minute
-            .toString()
-            .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const { timeZone = "UTC" } = options ?? {};
+        if (!isValidTimeZone(timeZone))
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        try {
+            const instant = Temporal.Instant.from(value);
+            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
+            return `${zonedDateTime.hour.toString().padStart(2, "0")}:${zonedDateTime.minute
+                .toString()
+                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }