@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/calculate/endOfDateTime.js

@@ -1,5 +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 { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { isValidDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 const supported = [
     "year",
     "month",
@@ -15,124 +19,143 @@ const supported = [
 /**
  * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
+ * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
+ * - The end is computed forward from `value`, so it is returned even when the unit began before
+ *   the first representable date (`-271821-04-19`).
+ * - 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.
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
+ * - **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 8601 datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the unit for the end
+ * @param unit date or time unit, singular or plural, to specify the unit for the end
  * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-29T23:59:59.999999999"
+ * @example endOfDateTime("2024-02-29T12:34:56", "month", { fractionalSecondDigits: 0 }) // "2024-02-29T23:59:59" — the pre-1.16.0 string
+ * @example endOfDateTime("2024-02-29T12:34:56.123456789", "second", { fractionalSecondDigits: 9 }) // "2024-02-29T12:34:56.999999999"
+ * @example endOfDateTime("2024-03-03T12:00:00", "week", { weekStartsOn: "sunday" }) // "2024-03-09T23:59:59.999999999"
+ * @example endOfDateTime("-271821-04-19T12:00:00", "month") // "-271821-04-30T23:59:59.999999999" (the month began before the range; its end did not)
+ * @example endOfDateTime("2024-02-29T12:34:56", "hours") // "2024-02-29T12:59:59.999999999"
  * @example endOfDateTime("invalid-date", "month") // ""
  */
 export function endOfDateTime(value, unit, optionsArg) {
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
-    if (!isValidDateTime(value) || !supported.includes(unit))
-        return "";
     try {
-        const source = Temporal.PlainDateTime.from(value);
-        let result;
-        switch (unit) {
-            case "year":
-                result = source.with({ month: 12, day: 31 }).withPlainTime({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "month": {
-                const lastDay = Temporal.PlainDate.from({
-                    year: source.year,
-                    month: source.month,
-                    day: 1, // Start from day 1 to get daysInMonth
-                }).daysInMonth;
-                result = source.with({ day: lastDay }).withPlainTime({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            }
-            case "week": {
-                const daysToAdd = weekStartsOn === "monday"
-                    ? 7 - source.dayOfWeek
-                    : (6 - source.dayOfWeek) % 7;
-                result = source
-                    .with({ year: source.year, month: source.month, day: source.day })
-                    .add({ days: daysToAdd })
-                    .withPlainTime({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        if (weekStartsOn === null ||
+            !isValidDateTime(value) ||
+            !supported.includes(resolvedUnit))
+            return "";
+        try {
+            const source = Temporal.PlainDateTime.from(value);
+            let result;
+            switch (resolvedUnit) {
+                case "year":
+                    result = source.with({ month: 12, day: 31 }).withPlainTime({
+                        hour: 23,
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "month": {
+                    // Computed from `value` itself: the month's first day may lie before the range.
+                    result = source.with({ day: source.daysInMonth }).withPlainTime({
+                        hour: 23,
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                }
+                case "week": {
+                    // Sunday is day 7, so `dayOfWeek % 7` counts Sunday as day 0 of a Sunday-first week.
+                    const daysToAdd = weekStartsOn === "monday"
+                        ? 7 - source.dayOfWeek
+                        : 6 - (source.dayOfWeek % 7);
+                    result = source.add({ days: daysToAdd }).withPlainTime({
+                        hour: 23,
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                }
+                case "day":
+                    result = source.withPlainTime({
+                        hour: 23,
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "hour":
+                    result = source.with({
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "minute":
+                    result = source.with({
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "second":
+                    result = source.with({
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "millisecond":
+                    result = source.with({ microsecond: 999, nanosecond: 999 });
+                    break;
+                case "microsecond":
+                    result = source.with({ nanosecond: 999 });
+                    break;
+                case "nanosecond":
+                    result = source;
+                    break;
+                default:
+                    return "";
             }
-            case "day":
-                result = source.withPlainTime({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "hour":
-                result = source.with({
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "minute":
-                result = source.with({
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "second":
-                result = source.with({
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "millisecond":
-                result = source.with({ microsecond: 999, nanosecond: 999 });
-                break;
-            case "microsecond":
-                result = source.with({ nanosecond: 999 });
-                break;
-            case "nanosecond":
-                result = source;
-                break;
-            default:
-                return "";
+            // An end is the next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
+            // print an earlier value than the end (Calendar & zone semantics §3).
+            return result.toString({
+                fractionalSecondDigits: fractionalSecondDigits === undefined ? 9 : fractionalSecondDigits,
+            });
+        }
+        catch {
+            return "";
         }
-        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[unit] || 0);
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,10 +1,23 @@
 import { Temporal } from "@js-temporal/polyfill";
 import type { FractionalDigit } from "../../types/index.js";
-type EndOfTimeUnit = Temporal.TimeUnit | "day";
+/**
+ * Units `endOfTime` accepts: a Temporal time unit, or `"day"` for the last moment of the day, each singular
+ * or plural.
+ *
+ * @example
+ * import { EndOfTimeUnit } from "@northguild/gmt/plain";
+ * const unit: EndOfTimeUnit = "minutes";
+ */
+export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *
+ * - 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.
+ * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid inputs.
+ * - **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 8601 time string
  * @param unit EndOfTimeUnit to specify the unit for the end
@@ -12,9 +25,10 @@ type EndOfTimeUnit = Temporal.TimeUnit | "day";
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfTime("12:34:56", "hour") // "12:59:59.999999999"
+ * @example endOfTime("12:34:56", "hour", { fractionalSecondDigits: 0 }) // "12:59:59" — the pre-1.16.0 string
+ * @example endOfTime("12:34:56.123", "milliseconds") // "12:34:56.123999999"
  * @example endOfTime("invalid", "hour") // ""
  */
 export declare function endOfTime(value: string, unit: EndOfTimeUnit, optionsArg?: {
     fractionalSecondDigits?: FractionalDigit;
 }): string;
-export {};

package/dist/plain/calculate/endOfTime.js

@@ -1,5 +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 { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { isValidTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 const supported = [
     "day",
     "hour",
@@ -12,7 +15,12 @@ const supported = [
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *
+ * - 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.
+ * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid inputs.
+ * - **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 8601 time string
  * @param unit EndOfTimeUnit to specify the unit for the end
@@ -20,72 +28,82 @@ const supported = [
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfTime("12:34:56", "hour") // "12:59:59.999999999"
+ * @example endOfTime("12:34:56", "hour", { fractionalSecondDigits: 0 }) // "12:59:59" — the pre-1.16.0 string
+ * @example endOfTime("12:34:56.123", "milliseconds") // "12:34:56.123999999"
  * @example endOfTime("invalid", "hour") // ""
  */
 export function endOfTime(value, unit, optionsArg) {
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
-    if (!isValidTime(value) || !supported.includes(unit))
-        return "";
     try {
-        const source = Temporal.PlainTime.from(value);
-        let result;
-        switch (unit) {
-            case "day":
-                result = source.with({
-                    hour: 23,
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "hour":
-                result = source.with({
-                    minute: 59,
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "minute":
-                result = source.with({
-                    second: 59,
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "second":
-                result = source.with({
-                    millisecond: 999,
-                    microsecond: 999,
-                    nanosecond: 999,
-                });
-                break;
-            case "millisecond":
-                result = source.with({ microsecond: 999, nanosecond: 999 });
-                break;
-            case "microsecond":
-                result = source.with({ nanosecond: 999 });
-                break;
-            case "nanosecond":
-                result = source;
-                break;
-            default:
-                return "";
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        if (!isValidTime(value) || !supported.includes(resolvedUnit))
+            return "";
+        try {
+            const source = Temporal.PlainTime.from(value);
+            let result;
+            switch (resolvedUnit) {
+                case "day":
+                    result = source.with({
+                        hour: 23,
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "hour":
+                    result = source.with({
+                        minute: 59,
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "minute":
+                    result = source.with({
+                        second: 59,
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "second":
+                    result = source.with({
+                        millisecond: 999,
+                        microsecond: 999,
+                        nanosecond: 999,
+                    });
+                    break;
+                case "millisecond":
+                    result = source.with({ microsecond: 999, nanosecond: 999 });
+                    break;
+                case "microsecond":
+                    result = source.with({ nanosecond: 999 });
+                    break;
+                case "nanosecond":
+                    result = source;
+                    break;
+                default:
+                    return "";
+            }
+            // An end is the next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
+            // print an earlier value than the end (Calendar & zone semantics §3).
+            return result.toString({
+                fractionalSecondDigits: fractionalSecondDigits === undefined ? 9 : fractionalSecondDigits,
+            });
+        }
+        catch {
+            return "";
         }
-        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[unit] || 0);
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,16 +1,24 @@
+import type { Temporal } from "@js-temporal/polyfill";
 import type { DateDurationUnit } from "../../types/index.js";
 /**
  * Return the largest DateDurationUnit from the provided array.
  *
  * - Returns the largest unit based on Temporal's unit order: years > months > weeks > days.
- * - Defaults to "days" if no valid unit is found in the array.
+ * - Each unit may be singular or plural (`"day"` or `"days"`), as Temporal accepts; the result is
+ *   the plural name.
+ * - Returns "" when `units` is not an array, is empty, or holds anything that is not a unit of
+ *   this family.
+ * - **Compatibility:** before 1.16.0 an empty or invalid `units` returned a default unit
+ *   (`"days"`).
  *
- * @param units array of DateDurationUnits to evaluate
- * @returns the largest DateDurationUnit found in the array, or "days" if none are valid
+ * @param units array of DateDurationUnits (singular or plural names) to evaluate
+ * @returns the largest DateDurationUnit found in the array, or "" on invalid input
  *
  * @example getLargestDateDurationUnit(["months", "days"]) // "months"
  * @example getLargestDateDurationUnit(["weeks", "days"]) // "weeks"
+ * @example getLargestDateDurationUnit(["day", "month"]) // "months" (singular names count as their plural)
  * @example getLargestDateDurationUnit(["days"]) // "days"
- * @example getLargestDateDurationUnit([]) // "days"
+ * @example getLargestDateDurationUnit([]) // "" (no unit to choose from)
+ * @example getLargestDateDurationUnit(["days", "bananas"]) // "" (an invalid unit)
  */
-export declare function getLargestDateDurationUnit(units: DateDurationUnit[]): DateDurationUnit;
+export declare function getLargestDateDurationUnit(units: Array<DateDurationUnit | Temporal.DateUnit>): DateDurationUnit | "";

package/dist/plain/calculate/getLargestDateDurationUnit.js

@@ -1,24 +1,40 @@
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
+import { isValidDateDurationUnit } from "../validate/isValidDateDurationUnit.js";
+const ORDER = ["years", "months", "weeks", "days"];
 /**
  * Return the largest DateDurationUnit from the provided array.
  *
  * - Returns the largest unit based on Temporal's unit order: years > months > weeks > days.
- * - Defaults to "days" if no valid unit is found in the array.
+ * - Each unit may be singular or plural (`"day"` or `"days"`), as Temporal accepts; the result is
+ *   the plural name.
+ * - Returns "" when `units` is not an array, is empty, or holds anything that is not a unit of
+ *   this family.
+ * - **Compatibility:** before 1.16.0 an empty or invalid `units` returned a default unit
+ *   (`"days"`).
  *
- * @param units array of DateDurationUnits to evaluate
- * @returns the largest DateDurationUnit found in the array, or "days" if none are valid
+ * @param units array of DateDurationUnits (singular or plural names) to evaluate
+ * @returns the largest DateDurationUnit found in the array, or "" on invalid input
  *
  * @example getLargestDateDurationUnit(["months", "days"]) // "months"
  * @example getLargestDateDurationUnit(["weeks", "days"]) // "weeks"
+ * @example getLargestDateDurationUnit(["day", "month"]) // "months" (singular names count as their plural)
  * @example getLargestDateDurationUnit(["days"]) // "days"
- * @example getLargestDateDurationUnit([]) // "days"
+ * @example getLargestDateDurationUnit([]) // "" (no unit to choose from)
+ * @example getLargestDateDurationUnit(["days", "bananas"]) // "" (an invalid unit)
  */
 export function getLargestDateDurationUnit(units) {
-    const order = ["years", "months", "weeks", "days"];
-    for (const unit of order) {
-        if (units.includes(unit)) {
-            return unit;
+    try {
+        if (!Array.isArray(units) || units.length === 0)
+            return "";
+        const plurals = units.map((unit) => resolveDurationUnit(unit));
+        if (!plurals.every((unit) => typeof unit === "string" && isValidDateDurationUnit(unit))) {
+            return "";
         }
+        return ORDER.find((unit) => plurals.includes(unit)) ?? "";
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
     }
-    // Default to days if no valid unit found, though this case should be prevented by validation
-    return "days";
 }

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

@@ -1,16 +1,23 @@
+import type { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeDurationUnit } from "../../types/index.js";
 /**
  * Return the largest DateTimeDurationUnit from the provided array.
  *
  * - Returns the largest unit based on Temporal's unit order: years > months > weeks > days > hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
- * - Defaults to "seconds" if no valid unit is found in the array.
+ * - Each unit may be singular or plural (`"day"` or `"days"`), as Temporal accepts; the result is
+ *   the plural name.
+ * - Returns "" when `units` is not an array, is empty, or holds anything that is not a unit of
+ *   this family.
+ * - **Compatibility:** before 1.16.0 an empty or invalid `units` returned a default unit
+ *   (`"seconds"`).
  *
- * @param units array of DateTimeDurationUnit to evaluate
- * @returns the largest DateTimeDurationUnit found, or "seconds" if none are valid
+ * @param units array of DateTimeDurationUnits (singular or plural names) to evaluate
+ * @returns the largest DateTimeDurationUnit found in the array, or "" on invalid input
  *
  * @example getLargestDateTimeDurationUnit(["hours", "minutes", "seconds"]) // "hours"
  * @example getLargestDateTimeDurationUnit(["minutes", "seconds"]) // "minutes"
- * @example getLargestDateTimeDurationUnit(["seconds"]) // "seconds"
- * @example getLargestDateTimeDurationUnit([]) // "seconds"
+ * @example getLargestDateTimeDurationUnit(["hour", "day"]) // "days" (singular names count as their plural)
+ * @example getLargestDateTimeDurationUnit([]) // "" (no unit to choose from)
+ * @example getLargestDateTimeDurationUnit(["seconds", "fortnights"]) // "" (an invalid unit)
  */
-export declare function getLargestDateTimeDurationUnit(units: DateTimeDurationUnit[]): DateTimeDurationUnit;
+export declare function getLargestDateTimeDurationUnit(units: Array<DateTimeDurationUnit | Temporal.DateTimeUnit>): DateTimeDurationUnit | "";

package/dist/plain/calculate/getLargestDateTimeDurationUnit.js

@@ -1,35 +1,50 @@
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
+import { isValidDateTimeDurationUnit } from "../validate/isValidDateTimeDurationUnit.js";
+const ORDER = [
+    "years",
+    "months",
+    "weeks",
+    "days",
+    "hours",
+    "minutes",
+    "seconds",
+    "milliseconds",
+    "microseconds",
+    "nanoseconds",
+];
 /**
  * Return the largest DateTimeDurationUnit from the provided array.
  *
  * - Returns the largest unit based on Temporal's unit order: years > months > weeks > days > hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
- * - Defaults to "seconds" if no valid unit is found in the array.
+ * - Each unit may be singular or plural (`"day"` or `"days"`), as Temporal accepts; the result is
+ *   the plural name.
+ * - Returns "" when `units` is not an array, is empty, or holds anything that is not a unit of
+ *   this family.
+ * - **Compatibility:** before 1.16.0 an empty or invalid `units` returned a default unit
+ *   (`"seconds"`).
  *
- * @param units array of DateTimeDurationUnit to evaluate
- * @returns the largest DateTimeDurationUnit found, or "seconds" if none are valid
+ * @param units array of DateTimeDurationUnits (singular or plural names) to evaluate
+ * @returns the largest DateTimeDurationUnit found in the array, or "" on invalid input
  *
  * @example getLargestDateTimeDurationUnit(["hours", "minutes", "seconds"]) // "hours"
  * @example getLargestDateTimeDurationUnit(["minutes", "seconds"]) // "minutes"
- * @example getLargestDateTimeDurationUnit(["seconds"]) // "seconds"
- * @example getLargestDateTimeDurationUnit([]) // "seconds"
+ * @example getLargestDateTimeDurationUnit(["hour", "day"]) // "days" (singular names count as their plural)
+ * @example getLargestDateTimeDurationUnit([]) // "" (no unit to choose from)
+ * @example getLargestDateTimeDurationUnit(["seconds", "fortnights"]) // "" (an invalid unit)
  */
 export function getLargestDateTimeDurationUnit(units) {
-    const order = [
-        "years",
-        "months",
-        "weeks",
-        "days",
-        "hours",
-        "minutes",
-        "seconds",
-        "milliseconds",
-        "microseconds",
-        "nanoseconds",
-    ];
-    for (const unit of order) {
-        if (units.includes(unit)) {
-            return unit;
+    try {
+        if (!Array.isArray(units) || units.length === 0)
+            return "";
+        const plurals = units.map((unit) => resolveDurationUnit(unit));
+        if (!plurals.every((unit) => typeof unit === "string" && isValidDateTimeDurationUnit(unit))) {
+            return "";
         }
+        return ORDER.find((unit) => plurals.includes(unit)) ?? "";
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
     }
-    // Default to seconds if no valid unit found, though this case should be prevented by validation
-    return "seconds";
 }