@northguild/gmt 1.15.0 → 1.17.0

package/dist/unix/validate/isValidUnixSeconds.js

@@ -1,19 +1,20 @@
+import { unixEpochToInstant } from "../../internal/unixEpochValue.js";
 /**
- * Return true when `timestamp` is a valid Unix seconds value.
+ * Return true when `timestamp` is a Unix seconds value every `unix/` function accepts.
  *
- * - Must be an integer (positive or negative, for dates before/after 1970).
- * - Returns false for non-numbers or non-integers.
+ * - A number must be a safe integer; a string must be an optionally negative run of ASCII digits
+ *   (`"1700000000"`, `"-86400"`), with no whitespace, `+`, decimal point, exponent or hex.
+ * - The instant must lie in the Temporal range: ±8.64e12 seconds (10^8 days) from the epoch.
  *
- * @param timestamp number candidate
+ * @param timestamp candidate value of any type
  * @returns boolean indicating whether the timestamp is a valid Unix seconds value
  *
  * @example isValidUnixSeconds(1700000000) // true
- * @example isValidUnixSeconds(-86400) // true (1969-12-31)
+ * @example isValidUnixSeconds("-86400") // true (1969-12-31)
  * @example isValidUnixSeconds(1.5) // false
+ * @example isValidUnixSeconds("1e9") // false (not a digit string)
+ * @example isValidUnixSeconds(8640000000001) // false (past the last Temporal instant)
  */
 export function isValidUnixSeconds(timestamp) {
-    if (typeof timestamp === "number") {
-        return Number.isInteger(timestamp);
-    }
-    return false;
+    return unixEpochToInstant(timestamp, "seconds") !== null;
 }

package/dist/unix/validate/isValidUnixUnit.d.ts

@@ -6,26 +6,28 @@
  *
  * | Member | Description |
  * | --- | --- |
- * | `seconds` | Value is Unix epoch seconds (e.g. `1700000000`). |
- * | `milliseconds` | Value is Unix epoch milliseconds (e.g. `1700000000000`). |
+ * | `seconds` / `second` | Value is Unix epoch seconds (e.g. `1700000000`). |
+ * | `milliseconds` / `millisecond` | Value is Unix epoch milliseconds (e.g. `1700000000000`). |
+ *
+ * Singular and plural names are the same unit, as in Temporal's unit-valued options.
  *
  * @example
  * import { isValidUnixUnit } from "@northguild/gmt/unix";
  * isValidUnixUnit("milliseconds"); // true
  */
-export type UnixUnit = "seconds" | "milliseconds";
+export type UnixUnit = "seconds" | "second" | "milliseconds" | "millisecond";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *
- * - Valid units are: "seconds", "milliseconds".
- * - Accepts any input type and returns false for non-string values.
- * - Uses type assertion to narrow the type.
+ * - Valid units are `"seconds"`, `"milliseconds"` and their singular forms `"second"`,
+ *   `"millisecond"` (Temporal §13.17 GetTemporalUnitValuedOption accepts both).
+ * - Names are case-sensitive; any non-string input returns false.
  *
  * @param unit candidate value of any type
  * @returns boolean indicating whether the unit is a valid UnixUnit
  *
  * @example isValidUnixUnit("seconds") // true
- * @example isValidUnixUnit("milliseconds") // true
+ * @example isValidUnixUnit("millisecond") // true
  * @example isValidUnixUnit("invalid") // false
  * @example isValidUnixUnit(123) // false
  * @example isValidUnixUnit(null) // false

package/dist/unix/validate/isValidUnixUnit.js

@@ -1,22 +1,20 @@
+import { resolveUnixEpochUnit } from "../../internal/unixEpochValue.js";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *
- * - Valid units are: "seconds", "milliseconds".
- * - Accepts any input type and returns false for non-string values.
- * - Uses type assertion to narrow the type.
+ * - Valid units are `"seconds"`, `"milliseconds"` and their singular forms `"second"`,
+ *   `"millisecond"` (Temporal §13.17 GetTemporalUnitValuedOption accepts both).
+ * - Names are case-sensitive; any non-string input returns false.
  *
  * @param unit candidate value of any type
  * @returns boolean indicating whether the unit is a valid UnixUnit
  *
  * @example isValidUnixUnit("seconds") // true
- * @example isValidUnixUnit("milliseconds") // true
+ * @example isValidUnixUnit("millisecond") // true
  * @example isValidUnixUnit("invalid") // false
  * @example isValidUnixUnit(123) // false
  * @example isValidUnixUnit(null) // false
  */
 export function isValidUnixUnit(unit) {
-    if (typeof unit !== "string") {
-        return false;
-    }
-    return unit === "seconds" || unit === "milliseconds";
+    return unit !== undefined && resolveUnixEpochUnit(unit) !== null;
 }

package/dist/utc/calculate/addUtc.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/isValidUtc.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Add a temporal amount to a UTC datetime string and return a new UTC Instant string.
  *
@@ -22,21 +24,33 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example addUtc("invalid", { days: 5 }) // ""
  */
 export function addUtc(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.add(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.add(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/calculate/diffUtc.d.ts

@@ -3,7 +3,10 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
 /**
  * Return the difference between two UTC datetimes measured in the given date-time unit.
  *
- * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Converts both values to a `Temporal.ZonedDateTime` in UTC and uses its `until()`, so calendar
+ *   units (days, weeks, months, years) are measured on the UTC wall clock — which has no DST, so
+ *   every day is 24 hours — while time units are exact elapsed time.
+ *   `Temporal.Instant.until()` is not used: it rejects every calendar `largestUnit`.
  * - Supports single unit or array of units.
  * - Returns null for invalid input.
  *
@@ -11,17 +14,29 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest hour before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   array (e.g. `["days", "hours"]` with `smallestUnit: "week"`) — this combination is rejected by
  *   Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Nanosecond precision: the result is a JavaScript `number`, so it stops being exact once it
+ *   passes `Number.MAX_SAFE_INTEGER` — about 104 days in nanoseconds and about 285 years in
+ *   microseconds. `diffUtc("2024-01-01T00:00:00Z", "2024-04-15T00:00:00.000000001Z", "nanoseconds")`
+ *   returns `9072000000000000` rather than `9072000000000001`. For an exact count use the `bigint` APIs: `spanNs`
+ *   in `span/`, or `toNanoseconds` in `precision/`.
  *
  * @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)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); 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", "hour") // 24
- * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["year", "month"]) // { year: 1, month: 1 }
- * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hour") // null
+ * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24
+ * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["years", "months"]) // { years: 1, months: 1 }
+ * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hours") // null
+ * @example diffUtc("2024-01-01T00:00:00Z", "2025-03-01T00:00:00Z", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
-export declare function diffUtc(value1: string, value2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;
+export declare function diffUtc(value1: string, value2: string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/utc/calculate/diffUtc.js

@@ -1,11 +1,19 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
+import { addToZoned, zonedUntil } from "../../internal/index.js";
+import { differenceRecord } from "../../internal/differenceRecord.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two UTC datetimes measured in the given date-time unit.
  *
- * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Converts both values to a `Temporal.ZonedDateTime` in UTC and uses its `until()`, so calendar
+ *   units (days, weeks, months, years) are measured on the UTC wall clock — which has no DST, so
+ *   every day is 24 hours — while time units are exact elapsed time.
+ *   `Temporal.Instant.until()` is not used: it rejects every calendar `largestUnit`.
  * - Supports single unit or array of units.
  * - Returns null for invalid input.
  *
@@ -13,49 +21,85 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest hour before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   array (e.g. `["days", "hours"]` with `smallestUnit: "week"`) — this combination is rejected by
  *   Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Nanosecond precision: the result is a JavaScript `number`, so it stops being exact once it
+ *   passes `Number.MAX_SAFE_INTEGER` — about 104 days in nanoseconds and about 285 years in
+ *   microseconds. `diffUtc("2024-01-01T00:00:00Z", "2024-04-15T00:00:00.000000001Z", "nanoseconds")`
+ *   returns `9072000000000000` rather than `9072000000000001`. For an exact count use the `bigint` APIs: `spanNs`
+ *   in `span/`, or `toNanoseconds` in `precision/`.
  *
  * @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)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); 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", "hour") // 24
- * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["year", "month"]) // { year: 1, month: 1 }
- * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hour") // null
+ * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24
+ * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["years", "months"]) // { years: 1, months: 1 }
+ * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hours") // null
+ * @example diffUtc("2024-01-01T00:00:00Z", "2025-03-01T00:00:00Z", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
 export function diffUtc(value1, value2, units, options) {
-    const validUtc1 = isValidUtc(value1);
-    const validUtc2 = isValidUtc(value2);
-    const isSingleUnit = !Array.isArray(units);
-    const validUnits = isSingleUnit
-        ? isValidDateTimeDurationUnit(units)
-        : units.every(isValidDateTimeDurationUnit);
-    if (!validUtc1 || !validUtc2 || !validUnits) {
-        return null;
-    }
     try {
-        const instant1 = Temporal.Instant.from(value1);
-        const instant2 = Temporal.Instant.from(value2);
-        const zdt1 = instant1.toZonedDateTimeISO("UTC");
-        const zdt2 = instant2.toZonedDateTimeISO("UTC");
-        const duration = zdt1.until(zdt2, {
-            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
-            smallestUnit: options?.smallestUnit,
-            roundingIncrement: options?.roundingIncrement,
-            roundingMode: options?.roundingMode,
-        });
-        if (isSingleUnit) {
-            return duration[units] ?? 0;
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const validUtc1 = isValidUtc(value1);
+        const validUtc2 = isValidUtc(value2);
+        // Singular names resolve to their plural (Temporal §13.17); record keys are the plural names.
+        const resolved = Array.isArray(units)
+            ? units.map((unit) => resolveDurationUnit(unit))
+            : resolveDurationUnit(units);
+        const isSingleUnit = !Array.isArray(resolved);
+        const validUnits = isSingleUnit
+            ? isValidDateTimeDurationUnit(resolved)
+            : resolved.every(isValidDateTimeDurationUnit);
+        if (!validUtc1 || !validUtc2 || !validUnits) {
+            return null;
+        }
+        try {
+            // An empty units list names no largest unit, so there is nothing to measure.
+            const largestUnit = isSingleUnit
+                ? resolved
+                : getLargestDateTimeDurationUnit(resolved);
+            if (largestUnit === "")
+                return null;
+            const instant1 = Temporal.Instant.from(value1);
+            const instant2 = Temporal.Instant.from(value2);
+            const zdt1 = instant1.toZonedDateTimeISO("UTC");
+            const zdt2 = instant2.toZonedDateTimeISO("UTC");
+            const duration = zonedUntil(zdt1, zdt2, {
+                largestUnit,
+                smallestUnit: options?.smallestUnit,
+                roundingIncrement: options?.roundingIncrement,
+                roundingMode: options?.roundingMode,
+            });
+            if (isSingleUnit) {
+                return duration[resolved] ?? 0;
+            }
+            // An unlisted unit between two listed units is carried into the next smaller listed unit.
+            return differenceRecord(zdt1, duration, resolved, {
+                add: (from, amount) => addToZoned(from, amount),
+                until: (from, to, largest) => zonedUntil(from, to, {
+                    largestUnit: largest,
+                }),
+            });
+        }
+        catch {
+            return null;
         }
-        return units.reduce((result, unit) => {
-            result[unit] = duration[unit] ?? 0;
-            return result;
-        }, {});
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -21,11 +21,11 @@ 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)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); 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"
  * @example diffUtcAsDuration("2024-03-11T12:00:00Z", "2024-03-10T12:00:00Z", "hours") // "-PT24H"
  * @example diffUtcAsDuration("invalid", "2024-03-11T12:00:00Z", "hours") // ""
  */
-export declare function diffUtcAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;
+export declare function diffUtcAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/utc/calculate/diffUtcAsDuration.js

@@ -1,7 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { durationUntilString } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two UTC datetimes as an ISO 8601 duration string,
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
@@ -23,7 +25,7 @@ import { isValidUtc } from "../validate/isValidUtc.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)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); 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"
@@ -31,9 +33,14 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example diffUtcAsDuration("invalid", "2024-03-11T12:00:00Z", "hours") // ""
  */
 export function diffUtcAsDuration(value1, value2, unit, options) {
+    // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     const validUtc1 = isValidUtc(value1);
     const validUtc2 = isValidUtc(value2);
-    const validUnit = isValidDateTimeDurationUnit(unit);
+    const resolvedUnit = resolveDurationUnit(unit);
+    const validUnit = isValidDateTimeDurationUnit(resolvedUnit);
     if (!validUtc1 || !validUtc2 || !validUnit) {
         return "";
     }
@@ -42,7 +49,7 @@ export function diffUtcAsDuration(value1, value2, unit, options) {
         const instant2 = Temporal.Instant.from(value2);
         const zdt1 = instant1.toZonedDateTimeISO("UTC");
         const zdt2 = instant2.toZonedDateTimeISO("UTC");
-        return durationUntilString(zdt1, zdt2, unit, options);
+        return durationUntilString(zdt1, zdt2, resolvedUnit, options);
     }
     catch {
         return "";

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

@@ -8,7 +8,7 @@
  * @param value UTC Instant string
  * @returns UTC Instant string for the end of the quarter, or "" on invalid input
  *
- * @example endOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-03-31T23:59:59.999Z"
+ * @example endOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-03-31T23:59:59.999999999Z"
  * @example endOfQuarterForUtc("invalid") // ""
  */
 export declare function endOfQuarterForUtc(value: string): string;

package/dist/utc/calculate/endOfQuarterForUtc.js

@@ -10,7 +10,7 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @param value UTC Instant string
  * @returns UTC Instant string for the end of the quarter, or "" on invalid input
  *
- * @example endOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-03-31T23:59:59.999Z"
+ * @example endOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-03-31T23:59:59.999999999Z"
  * @example endOfQuarterForUtc("invalid") // ""
  */
 export function endOfQuarterForUtc(value) {

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

@@ -1,22 +1,29 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the specified date-time `unit` for a given UTC datetime string.
  *
  * - Converts to ZonedDateTime, sets to end 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 "".
+ * - 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.
  * - 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
+ *   than the end. Pass that `fractionalSecondDigits` to keep the previous string.
  *
  * @param value ISO UTC datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
+ * @param unit date or time unit, singular or plural, to specify the end
  * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @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"
+ * @example endOfUtc("2024-03-15T14:30:45Z", "month", { fractionalSecondDigits: 0 }) // "2024-03-31T23:59:59Z" — the pre-1.16.0 string
  * @example endOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-31T23:59:59.999999999Z"
+ * @example endOfUtc("2024-03-15T14:30:45Z", "hours") // "2024-03-15T14:59:59.999999999Z"
  * @example endOfUtc("invalid", "year") // ""
  */
-export declare function endOfUtc(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+export declare function endOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
     weekStartsOn?: "monday" | "sunday";
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/endOfUtc.js

@@ -1,21 +1,38 @@
-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 end of the specified date-time `unit` for a given UTC datetime string.
  *
  * - Converts to ZonedDateTime, sets to end 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 "".
+ * - 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.
  * - 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
+ *   than the end. Pass that `fractionalSecondDigits` to keep the previous string.
  *
  * @param value ISO UTC datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
+ * @param unit date or time unit, singular or plural, to specify the end
  * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @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"
+ * @example endOfUtc("2024-03-15T14:30:45Z", "month", { fractionalSecondDigits: 0 }) // "2024-03-31T23:59:59Z" — the pre-1.16.0 string
  * @example endOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-31T23:59:59.999999999Z"
+ * @example endOfUtc("2024-03-15T14:30:45Z", "hours") // "2024-03-15T14:59:59.999999999Z"
  * @example endOfUtc("invalid", "year") // ""
  */
 export function endOfUtc(value, unit, options) {
-    return startOrEndOfUtc(value, unit, options ?? {}, true);
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        return startOrEndOfUtc(value, unit, options ?? {}, true);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
 }

package/dist/utc/calculate/isBetweenUtc.js

@@ -1,5 +1,7 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true when `value` is between `start` and `end` (inclusive by default).
  *
@@ -18,35 +20,49 @@ import { isValidUtc } from "../validate/index.js";
  * @example isBetweenUtc("invalid", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
  */
 export function isBetweenUtc(value, start, end, options) {
-    const inclusiveStart = options?.inclusiveStart ?? true;
-    const inclusiveEnd = options?.inclusiveEnd ?? true;
-    if (!isValidUtc(value) || !isValidUtc(start) || !isValidUtc(end)) {
-        return false;
-    }
-    let instant;
-    let startInstant;
-    let endInstant;
-    try {
-        instant = Temporal.Instant.from(value);
-        startInstant = Temporal.Instant.from(start);
-        endInstant = Temporal.Instant.from(end);
-    }
-    catch {
-        return false;
-    }
     try {
-        if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
+        // 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;
+        if (!isValidUtc(value) || !isValidUtc(start) || !isValidUtc(end)) {
+            return false;
+        }
+        let instant;
+        let startInstant;
+        let endInstant;
+        try {
+            instant = Temporal.Instant.from(value);
+            startInstant = Temporal.Instant.from(start);
+            endInstant = Temporal.Instant.from(end);
+        }
+        catch {
+            return false;
+        }
+        try {
+            if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
+                return false;
+            }
+            const startCheck = inclusiveStart
+                ? Temporal.Instant.compare(startInstant, instant) <= 0
+                : Temporal.Instant.compare(startInstant, instant) < 0;
+            const endCheck = inclusiveEnd
+                ? Temporal.Instant.compare(instant, endInstant) <= 0
+                : Temporal.Instant.compare(instant, endInstant) < 0;
+            return startCheck && endCheck;
+        }
+        catch {
             return false;
         }
-        const startCheck = inclusiveStart
-            ? Temporal.Instant.compare(startInstant, instant) <= 0
-            : Temporal.Instant.compare(startInstant, instant) < 0;
-        const endCheck = inclusiveEnd
-            ? Temporal.Instant.compare(instant, endInstant) <= 0
-            : Temporal.Instant.compare(instant, endInstant) < 0;
-        return startCheck && endCheck;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/utc/calculate/maxUtc.js

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