@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/calculate/roundDate.js

@@ -1,13 +1,29 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { addDateUnit, getStartOfDateUnit, } from "../../internal/dateUnitHelpers.js";
+import { addDateUnit, getDaysIntoDateUnit, getStartOfDateUnit, getStartOfNextDateUnit, } from "../../internal/dateUnitHelpers.js";
+import { measureNearRangeEnd } from "../../internal/measureNearRangeEnd.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveManualRoundingOptions } from "../../internal/resolveManualRoundingOptions.js";
 import { isValidDate, isValidDateUnit } from "../validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Round an ISO 8601 date string to the specified date unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts date units: "year", "month", "week", "day".
+ * - Accepts date units: "year", "month", "week", "day", each in its singular or plural form
+ *   ("month" or "months"), as Temporal's GetTemporalUnitValuedOption accepts both (§13.17).
  * - Time units ("hour", "minute", etc.) are rejected and return "".
- * - All date units use manual start-of-unit rounding.
+ * - All date units use manual start-of-unit rounding. Weeks start on Monday.
+ * - The rounding grid is anchored at the unit containing `value`, so `"halfEven"` breaks an exact
+ *   tie towards that unit's start (multiple 0, the even one).
+ * - The position within the unit is measured towards the next start, so a date in a unit that
+ *   began before the first representable date (`-271821-04-19`) still rounds up to the next start.
+ *   When it rounds down to that unrepresentable start, the result is "".
+ * - In the last representable year (`+275760`) a date that rounds down still returns its unit's
+ *   start; only rounding up past `+275760-09-13` returns "".
+ * - `roundingIncrement` and `roundingMode` are read as Temporal reads them: a non-integer increment
+ *   is truncated (`1.5` rounds by 1), an increment below 1 or not finite returns "", and a
+ *   `roundingMode` outside Temporal's nine returns "" (previously it floored silently).
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
  *
  * @param value ISO 8601 date string
@@ -15,58 +31,84 @@ import { isValidDate, isValidDateUnit } from "../validate/index.js";
  * @returns Rounded ISO 8601 date string, or "" on invalid input
  *
  * @example roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"
- * @example roundDate("2024-06-15", { smallestUnit: "month" }) // "2024-07-01"
- * @example roundDate("2024-06-15", { smallestUnit: "week" }) // "2024-06-16"
+ * @example roundDate("2024-06-15", { smallestUnit: "month" }) // "2024-06-01" (14 of 30 days in: rounds down)
+ * @example roundDate("2024-06-16", { smallestUnit: "month" }) // "2024-07-01" (half way: rounds up)
+ * @example roundDate("2024-06-15", { smallestUnit: "week" }) // "2024-06-17" (a Saturday: the next Monday is closer)
  * @example roundDate("2024-06-15", { smallestUnit: "day" }) // "2024-06-15"
+ * @example roundDate("2024-06-15", { smallestUnit: "months" }) // "2024-06-01" (plural unit name)
+ * @example roundDate("-271821-04-19", { smallestUnit: "month" }) // "-271821-05-01" (the month began before the range)
+ * @example roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "floor" }) // "+275760-01-01" (the next year is past the range)
+ * @example roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "ceil" }) // "" (+275761-01-01 is past the range)
+ * @example roundDate("2024-05-20", { smallestUnit: "month", roundingIncrement: 1.5 }) // "2024-06-01" (the increment truncates to 1)
+ * @example roundDate("2024-05-20", { smallestUnit: "month", roundingMode: "bogus" as never }) // ""
  * @example roundDate("invalid", { smallestUnit: "year" }) // ""
  */
 export function roundDate(value, options) {
-    const { smallestUnit, roundingIncrement, roundingMode } = options;
-    if (!isValidDate(value) || !isValidDateUnit(smallestUnit))
-        return "";
     try {
-        const source = Temporal.PlainDate.from(value);
-        // Manual rounding for all date units (year, month, week, day)
-        const startOfCurrent = getStartOfDateUnit(source, smallestUnit);
-        const increment = roundingIncrement ?? 1;
-        if (increment <= 0)
+        if (!isObject(options))
+            return "";
+        const { roundingIncrement, roundingMode } = options;
+        const smallestUnit = typeof options.smallestUnit === "string"
+            ? resolveDateTimeUnit(options.smallestUnit)
+            : options.smallestUnit;
+        if (!isValidDate(value) || !isValidDateUnit(smallestUnit))
+            return "";
+        try {
+            const source = Temporal.PlainDate.from(value);
+            // Manual rounding for all date units (year, month, week, day)
+            const resolved = resolveManualRoundingOptions(roundingIncrement, roundingMode);
+            if (resolved === null)
+                return "";
+            const { increment, mode } = resolved;
+            // Measured towards the next start, never from the current one: at the first representable
+            // date the current month or year began before the range, and only the next start exists. Each
+            // start is built only when the mode needs it, and the unit's length is measured on a date in
+            // the same place of its 400-year cycle when the next start lies after the last representable
+            // date (+275760-09-13), where the current start may still be the answer.
+            const elapsedDays = getDaysIntoDateUnit(source, smallestUnit);
+            const startOfNextFrom = (from) => addDateUnit(getStartOfNextDateUnit(from, smallestUnit), smallestUnit, increment - 1);
+            const startOfNext = () => startOfNextFrom(source);
+            // Throws (so returns "") when the start lies outside the range.
+            const startOfCurrent = () => getStartOfDateUnit(source, smallestUnit);
+            const fraction = () => elapsedDays /
+                (elapsedDays +
+                    measureNearRangeEnd(source, (from) => from.until(startOfNextFrom(from)).total("days")));
+            let rounded;
+            switch (mode) {
+                case "ceil":
+                case "expand":
+                    rounded = elapsedDays > 0 ? startOfNext() : startOfCurrent();
+                    break;
+                case "floor":
+                case "trunc":
+                    rounded = startOfCurrent();
+                    break;
+                case "halfExpand":
+                case "halfCeil":
+                    rounded = fraction() >= 0.5 ? startOfNext() : startOfCurrent();
+                    break;
+                case "halfTrunc":
+                case "halfFloor":
+                    rounded = fraction() > 0.5 ? startOfNext() : startOfCurrent();
+                    break;
+                case "halfEven":
+                    // Half-even breaks an exact tie towards the even multiple of the increment. The grid here
+                    // is anchored at the unit containing `source` — `startOfNext` counts the increment from
+                    // that unit, not from an absolute epoch — so the current start is multiple 0 and
+                    // `startOfNext` is multiple 1. The even multiple at a tie is therefore always the current
+                    // start. Above and below the tie it rounds to the nearer start, like every other half mode.
+                    rounded = fraction() > 0.5 ? startOfNext() : startOfCurrent();
+                    break;
+            }
+            return rounded.toString();
+        }
+        catch {
             return "";
-        const startOfNext = addDateUnit(startOfCurrent, smallestUnit, increment);
-        const elapsed = source.since(startOfCurrent);
-        const total = startOfNext.since(startOfCurrent);
-        const fraction = elapsed.total("days") / total.total("days");
-        let rounded;
-        const mode = roundingMode ?? "halfExpand";
-        switch (mode) {
-            case "ceil":
-            case "expand":
-                rounded =
-                    Temporal.PlainDate.compare(source, startOfCurrent) > 0
-                        ? startOfNext
-                        : startOfCurrent;
-                break;
-            case "floor":
-            case "trunc":
-                rounded = startOfCurrent;
-                break;
-            case "halfExpand":
-            case "halfCeil":
-                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
-                break;
-            case "halfTrunc":
-            case "halfFloor":
-                rounded = fraction > 0.5 ? startOfNext : startOfCurrent;
-                break;
-            case "halfEven":
-                // Simplified: use halfExpand behavior
-                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
-                break;
-            default:
-                rounded = startOfCurrent;
         }
-        return rounded.toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/roundDateTime.d.ts

@@ -5,22 +5,46 @@ import type { DateTimeUnit } from "../../types/index.js";
  *
  * - Returns "" for invalid inputs.
  * - Accepts all date and time units: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both.
  * - Time units use Temporal.PlainDateTime.round() directly.
- * - Date units (year, month, week) use manual start-of-unit rounding.
+ * - Date units (year, month, week) use manual start-of-unit rounding. Weeks start on Monday.
+ * - For date units the rounding grid is anchored at the unit containing `value`, so `"halfEven"`
+ *   breaks an exact tie towards that unit's start (multiple 0, the even one). Time units round
+ *   through Temporal, which anchors half-even on its own absolute grid.
+ * - For date units the position within the unit is measured towards the next start, so a value in
+ *   a unit that began before the first representable PlainDateTime
+ *   (`-271821-04-19T00:00:00.000000001`) still rounds up to the next start. When it rounds down to
+ *   that unrepresentable start, the result is "".
+ * - In the last representable year (`+275760`) a value that rounds down to a date unit still
+ *   returns that unit's start; only rounding up past `+275760-09-13T23:59:59.999999999` returns "".
+ * - `roundingIncrement` and `roundingMode` are read as Temporal reads them for every unit: a
+ *   non-integer increment is truncated (`1.5` rounds by 1), an increment below 1 or not finite
+ *   returns "", and a `roundingMode` outside Temporal's nine returns "" (previously a date unit
+ *   floored silently).
  * - 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.
  *
  * @param value ISO 8601 datetime string
  * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
  * @returns Rounded ISO 8601 datetime string, or "" on invalid input
  *
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "year" }) // "2024-01-01T00:00:00"
- * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "month" }) // "2024-07-01T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "month" }) // "2024-06-01T00:00:00" (under half way: rounds down)
+ * @example roundDateTime("2024-06-16T12:34:56", { smallestUnit: "month" }) // "2024-07-01T00:00:00" (past half way: rounds up)
+ * @example roundDateTime("-271821-04-19T12:00:00", { smallestUnit: "month" }) // "-271821-05-01T00:00:00" (the month began before the range)
+ * @example roundDateTime("+275760-06-15T00:00:00", { smallestUnit: "year", roundingMode: "floor" }) // "+275760-01-01T00:00:00" (the next year is past the range)
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "day" }) // "2024-06-16T00:00:00"
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "hour" }) // "2024-06-15T13:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "hours" }) // "2024-06-15T13:00:00" (plural unit name)
+ * @example roundDateTime("2024-06-15T12:34:56.123456789", { smallestUnit: "millisecond" }) // "2024-06-15T12:34:56.123" (precision follows the unit)
+ * @example roundDateTime("2024-05-15T12:00:00", { smallestUnit: "month", roundingMode: "bogus" as never }) // ""
  * @example roundDateTime("invalid", { smallestUnit: "year" }) // ""
  */
 export declare function roundDateTime(value: string, options: {
-    smallestUnit: DateTimeUnit;
+    smallestUnit: Temporal.SmallestUnit<DateTimeUnit>;
     roundingIncrement?: number;
     roundingMode?: Temporal.RoundingMode;
 }): string;

package/dist/plain/calculate/roundDateTime.js

@@ -1,98 +1,157 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { addDateTimeUnit, getStartOfDateTimeUnit, } from "../../internal/dateTimeUnitHelpers.js";
+import { defaultFractionalDigits, isObject, resolveDateTimeUnit, } from "../../internal/index.js";
+import { addDateTimeUnit, getStartOfDateTimeUnit, getStartOfNextDateTimeUnit, } from "../../internal/dateTimeUnitHelpers.js";
+import { getDaysIntoDateUnit } from "../../internal/dateUnitHelpers.js";
+import { measureNearRangeEnd } from "../../internal/measureNearRangeEnd.js";
+import { resolveManualRoundingOptions } from "../../internal/resolveManualRoundingOptions.js";
 import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
+const MILLISECONDS_PER_DAY = 86_400_000;
+/** Milliseconds (with sub-millisecond fraction) from midnight to `source`'s wall-clock time. */
+function millisecondsIntoDay(source) {
+    return (source.hour * 3_600_000 +
+        source.minute * 60_000 +
+        source.second * 1_000 +
+        source.millisecond +
+        source.microsecond / 1_000 +
+        source.nanosecond / 1_000_000);
+}
+/** Temporal.PlainDateTime.round() in this polyfill supports day and time units. */
+const TIME_UNITS = [
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/** Round a day or time unit through Temporal.PlainDateTime.round(). Throws on invalid options. */
+function roundTimeUnit(source, smallestUnit, roundingIncrement, roundingMode) {
+    const result = source.round({
+        smallestUnit,
+        roundingIncrement,
+        roundingMode,
+    });
+    const fractionalDigits = defaultFractionalDigits(smallestUnit);
+    return result.toString({ fractionalSecondDigits: fractionalDigits });
+}
+/** Rounds up at or past the half-way point. */
+const upAtHalf = (_elapsedMs, fraction) => fraction() >= 0.5;
+/** Rounds up only past the half-way point. */
+const upPastHalf = (_elapsedMs, fraction) => fraction() > 0.5;
+/**
+ * Whether a date unit rounds up to the next start, per rounding mode.
+ *
+ * `fraction` is the position within the unit, computed lazily because only the half modes need it.
+ */
+const ROUNDS_UP_TO_NEXT_START = {
+    ceil: (elapsedMs) => elapsedMs > 0,
+    expand: (elapsedMs) => elapsedMs > 0,
+    floor: () => false,
+    trunc: () => false,
+    halfExpand: upAtHalf,
+    halfCeil: upAtHalf,
+    halfTrunc: upPastHalf,
+    halfFloor: upPastHalf,
+    // Half-even breaks an exact tie towards the even multiple of the increment. The grid here is
+    // anchored at the unit containing `source` — `startOfNext` counts the increment from that unit,
+    // not from an absolute epoch — so the current start is multiple 0 and `startOfNext` is multiple
+    // 1. The even multiple at a tie is therefore always the current start. Above and below the tie it
+    // rounds to the nearer start, like every other half mode.
+    halfEven: upPastHalf,
+};
+/** Manually round to a date unit (year, month, week). Throws when a needed start is out of range. */
+function roundDateUnit(source, smallestUnit, increment, mode) {
+    // Measured towards the next start, never from the current one: the first representable
+    // PlainDateTime is -271821-04-19T00:00:00.000000001, so the week, month and year holding it
+    // began before the range, and only the next start exists. A PlainDateTime has no DST, so a day
+    // is always 86,400,000 ms. Each start is built only when the mode needs it, and the unit's
+    // length is measured on a value in the same place of its 400-year cycle when the next start lies
+    // after the last representable value, where the current start may still be the answer.
+    const elapsedMs = getDaysIntoDateUnit(source, smallestUnit) * MILLISECONDS_PER_DAY +
+        millisecondsIntoDay(source);
+    const startOfNextFrom = (from) => addDateTimeUnit(getStartOfNextDateTimeUnit(from, smallestUnit), smallestUnit, increment - 1);
+    const fraction = () => elapsedMs /
+        (elapsedMs +
+            measureNearRangeEnd(source, (from) => from.until(startOfNextFrom(from)).total("milliseconds")));
+    // getStartOfDateTimeUnit throws (so the caller returns "") when the start lies outside the range.
+    const rounded = ROUNDS_UP_TO_NEXT_START[mode](elapsedMs, fraction)
+        ? startOfNextFrom(source)
+        : getStartOfDateTimeUnit(source, smallestUnit);
+    return rounded.toString();
+}
 /**
  * Round an ISO 8601 datetime string to the specified date-time unit.
  *
  * - Returns "" for invalid inputs.
  * - Accepts all date and time units: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both.
  * - Time units use Temporal.PlainDateTime.round() directly.
- * - Date units (year, month, week) use manual start-of-unit rounding.
+ * - Date units (year, month, week) use manual start-of-unit rounding. Weeks start on Monday.
+ * - For date units the rounding grid is anchored at the unit containing `value`, so `"halfEven"`
+ *   breaks an exact tie towards that unit's start (multiple 0, the even one). Time units round
+ *   through Temporal, which anchors half-even on its own absolute grid.
+ * - For date units the position within the unit is measured towards the next start, so a value in
+ *   a unit that began before the first representable PlainDateTime
+ *   (`-271821-04-19T00:00:00.000000001`) still rounds up to the next start. When it rounds down to
+ *   that unrepresentable start, the result is "".
+ * - In the last representable year (`+275760`) a value that rounds down to a date unit still
+ *   returns that unit's start; only rounding up past `+275760-09-13T23:59:59.999999999` returns "".
+ * - `roundingIncrement` and `roundingMode` are read as Temporal reads them for every unit: a
+ *   non-integer increment is truncated (`1.5` rounds by 1), an increment below 1 or not finite
+ *   returns "", and a `roundingMode` outside Temporal's nine returns "" (previously a date unit
+ *   floored silently).
  * - 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.
  *
  * @param value ISO 8601 datetime string
  * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
  * @returns Rounded ISO 8601 datetime string, or "" on invalid input
  *
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "year" }) // "2024-01-01T00:00:00"
- * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "month" }) // "2024-07-01T00:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "month" }) // "2024-06-01T00:00:00" (under half way: rounds down)
+ * @example roundDateTime("2024-06-16T12:34:56", { smallestUnit: "month" }) // "2024-07-01T00:00:00" (past half way: rounds up)
+ * @example roundDateTime("-271821-04-19T12:00:00", { smallestUnit: "month" }) // "-271821-05-01T00:00:00" (the month began before the range)
+ * @example roundDateTime("+275760-06-15T00:00:00", { smallestUnit: "year", roundingMode: "floor" }) // "+275760-01-01T00:00:00" (the next year is past the range)
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "day" }) // "2024-06-16T00:00:00"
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "hour" }) // "2024-06-15T13:00:00"
+ * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "hours" }) // "2024-06-15T13:00:00" (plural unit name)
+ * @example roundDateTime("2024-06-15T12:34:56.123456789", { smallestUnit: "millisecond" }) // "2024-06-15T12:34:56.123" (precision follows the unit)
+ * @example roundDateTime("2024-05-15T12:00:00", { smallestUnit: "month", roundingMode: "bogus" as never }) // ""
  * @example roundDateTime("invalid", { smallestUnit: "year" }) // ""
  */
 export function roundDateTime(value, options) {
-    const { smallestUnit, roundingIncrement, roundingMode } = options;
-    if (!isValidDateTime(value) || !isValidDateTimeUnit(smallestUnit))
-        return "";
     try {
-        const source = Temporal.PlainDateTime.from(value);
-        // PlainDateTime.round() in this polyfill supports day and time units
-        const timeUnits = [
-            "day",
-            "hour",
-            "minute",
-            "second",
-            "millisecond",
-            "microsecond",
-            "nanosecond",
-        ];
-        if (timeUnits.includes(smallestUnit)) {
-            const timeUnit = smallestUnit;
-            const result = source.round({
-                smallestUnit: timeUnit,
-                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 = precisionMap[smallestUnit] || 0;
-            return result.toString({ fractionalSecondDigits: fractionalDigits });
+        if (!isObject(options))
+            return "";
+        const { roundingIncrement, roundingMode } = options;
+        const smallestUnit = typeof options.smallestUnit === "string"
+            ? resolveDateTimeUnit(options.smallestUnit)
+            : options.smallestUnit;
+        if (!isValidDateTime(value) || !isValidDateTimeUnit(smallestUnit))
+            return "";
+        try {
+            const source = Temporal.PlainDateTime.from(value);
+            if (TIME_UNITS.includes(smallestUnit)) {
+                return roundTimeUnit(source, smallestUnit, roundingIncrement, roundingMode);
+            }
+            // Manual rounding for date units (year, month, week)
+            const resolved = resolveManualRoundingOptions(roundingIncrement, roundingMode);
+            if (resolved === null)
+                return "";
+            return roundDateUnit(source, smallestUnit, resolved.increment, resolved.mode);
         }
-        // Manual rounding for date units (year, month, week)
-        const startOfCurrent = getStartOfDateTimeUnit(source, smallestUnit);
-        const increment = roundingIncrement ?? 1;
-        if (increment <= 0)
+        catch {
             return "";
-        const startOfNext = addDateTimeUnit(startOfCurrent, smallestUnit, increment);
-        const elapsed = source.since(startOfCurrent);
-        const total = startOfNext.since(startOfCurrent);
-        const fraction = elapsed.total("milliseconds") / total.total("milliseconds");
-        let rounded;
-        const mode = roundingMode ?? "halfExpand";
-        switch (mode) {
-            case "ceil":
-            case "expand":
-                rounded =
-                    Temporal.PlainDateTime.compare(source, startOfCurrent) > 0
-                        ? startOfNext
-                        : startOfCurrent;
-                break;
-            case "floor":
-            case "trunc":
-                rounded = startOfCurrent;
-                break;
-            case "halfExpand":
-            case "halfCeil":
-                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
-                break;
-            case "halfTrunc":
-            case "halfFloor":
-                rounded = fraction > 0.5 ? startOfNext : startOfCurrent;
-                break;
-            case "halfEven":
-                // Simplified: use halfExpand behavior
-                rounded = fraction >= 0.5 ? startOfNext : startOfCurrent;
-                break;
-            default:
-                rounded = startOfCurrent;
         }
-        return rounded.toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/roundTime.d.ts

@@ -4,7 +4,12 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Returns "" for invalid inputs.
  * - Only time units are accepted: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both.
  * - Wraps Temporal.PlainTime.round() which throws on invalid options.
+ * - 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.
  *
  * @param value ISO 8601 time string
  * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
@@ -13,10 +18,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example roundTime("12:34:56", { smallestUnit: "hour" }) // "13:00:00"
  * @example roundTime("12:34:56", { smallestUnit: "minute" }) // "12:35:00"
  * @example roundTime("12:34:56", { smallestUnit: "second", roundingMode: "floor" }) // "12:34:56"
+ * @example roundTime("12:34:56", { smallestUnit: "hours" }) // "13:00:00" (plural unit name)
+ * @example roundTime("12:34:56.123456789", { smallestUnit: "microsecond" }) // "12:34:56.123457" (precision follows the unit)
  * @example roundTime("invalid", { smallestUnit: "hour" }) // ""
  */
 export declare function roundTime(value: string, options: {
-    smallestUnit: Temporal.SmallestUnit<"hour">;
+    smallestUnit: Temporal.SmallestUnit<Temporal.TimeUnit>;
     roundingIncrement?: number;
     roundingMode?: Temporal.RoundingMode;
 }): string;

package/dist/plain/calculate/roundTime.js

@@ -1,11 +1,18 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
+import { defaultFractionalDigits, isObject, resolveDateTimeUnit, } from "../../internal/index.js";
 import { isValidTime, isValidTimeUnit } from "../validate/index.js";
 /**
  * Round an ISO 8601 time string to the specified time unit.
  *
  * - Returns "" for invalid inputs.
  * - Only time units are accepted: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both.
  * - Wraps Temporal.PlainTime.round() which throws on invalid options.
+ * - 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.
  *
  * @param value ISO 8601 time string
  * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
@@ -14,29 +21,37 @@ import { isValidTime, isValidTimeUnit } from "../validate/index.js";
  * @example roundTime("12:34:56", { smallestUnit: "hour" }) // "13:00:00"
  * @example roundTime("12:34:56", { smallestUnit: "minute" }) // "12:35:00"
  * @example roundTime("12:34:56", { smallestUnit: "second", roundingMode: "floor" }) // "12:34:56"
+ * @example roundTime("12:34:56", { smallestUnit: "hours" }) // "13:00:00" (plural unit name)
+ * @example roundTime("12:34:56.123456789", { smallestUnit: "microsecond" }) // "12:34:56.123457" (precision follows the unit)
  * @example roundTime("invalid", { smallestUnit: "hour" }) // ""
  */
 export function roundTime(value, options) {
-    const { smallestUnit, roundingIncrement, roundingMode } = options;
-    if (!isValidTime(value) || !isValidTimeUnit(smallestUnit))
-        return "";
     try {
-        const source = Temporal.PlainTime.from(value);
-        const result = source.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 = precisionMap[smallestUnit] || 0;
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
+        if (!isObject(options))
+            return "";
+        const { roundingIncrement, roundingMode } = options;
+        const smallestUnit = typeof options.smallestUnit === "string"
+            ? resolveDateTimeUnit(options.smallestUnit)
+            : options.smallestUnit;
+        if (!isValidTime(value) || !isValidTimeUnit(smallestUnit))
+            return "";
+        try {
+            const source = Temporal.PlainTime.from(value);
+            const result = source.round({
+                smallestUnit,
+                roundingIncrement,
+                roundingMode,
+            });
+            const fractionalDigits = defaultFractionalDigits(smallestUnit);
+            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/plain/calculate/setDate.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { resolveOverflow } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDate ISO string with the given `fields` set on `value`.
  *
@@ -29,6 +30,9 @@ import { isValidDate } from "../validate/index.js";
  * @example setDate("invalid", { year: 2025 }) // ""
  */
 export function setDate(value, fields, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (!isValidDate(value))
         return "";
     try {

package/dist/plain/calculate/setDateTime.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDateTime ISO string with the given `fields` set on `value`.
  *
@@ -28,6 +29,9 @@ import { isValidDateTime } from "../validate/index.js";
  * @example setDateTime("invalid", { hour: 9 }) // ""
  */
 export function setDateTime(value, fields, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (!isValidDateTime(value))
         return "";
     try {

package/dist/plain/calculate/setTime.d.ts

@@ -12,7 +12,7 @@ import type { Overflow } from "../../types/index.js";
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range field values, e.g.
  * `hour: 25`: "constrain" clamps to 23, "reject" throws (resulting in ""). Unlike `addTime`
- * (where `overflow` is inert because addition always wraps around the clock), `overflow` has
+ * (which takes no `overflow`, because addition always wraps around the clock), `overflow` has
  * a real effect here because `.with()` assigns fixed field values rather than adding a delta.
  *
  * @param value ISO PlainTime string

package/dist/plain/calculate/setTime.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { resolveOverflow } from "../../internal/index.js";
 import { isValidTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainTime ISO string with the given `fields` set on `value`.
  *
@@ -13,7 +14,7 @@ import { isValidTime } from "../validate/index.js";
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range field values, e.g.
  * `hour: 25`: "constrain" clamps to 23, "reject" throws (resulting in ""). Unlike `addTime`
- * (where `overflow` is inert because addition always wraps around the clock), `overflow` has
+ * (which takes no `overflow`, because addition always wraps around the clock), `overflow` has
  * a real effect here because `.with()` assigns fixed field values rather than adding a delta.
  *
  * @param value ISO PlainTime string
@@ -28,6 +29,9 @@ import { isValidTime } from "../validate/index.js";
  * @example setTime("invalid", { hour: 9 }) // ""
  */
 export function setTime(value, fields, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (!isValidTime(value))
         return "";
     try {