@northguild/gmt 1.14.2

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

@@ -0,0 +1,17 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the end of the specified date `unit` for a given ISO 8601 date string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 date string
+ * @param unit Temporal.DateUnit to specify the unit for the end
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
+ *
+ * @example endOfDate("2024-02-29", "month") // "2024-02-29"
+ * @example endOfDate("invalid-date", "month") // ""
+ */
+export declare function endOfDate(value: string, unit: Temporal.DateUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): string;

package/dist/plain/calculate/endOfDate.js

@@ -0,0 +1,51 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+const supported = ["year", "month", "week", "day"];
+/**
+ * Return the end of the specified date `unit` for a given ISO 8601 date string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 date string
+ * @param unit Temporal.DateUnit to specify the unit for the end
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
+ *
+ * @example endOfDate("2024-02-29", "month") // "2024-02-29"
+ * @example endOfDate("invalid-date", "month") // ""
+ */
+export function endOfDate(value, unit, optionsArg) {
+    if (!isValidDate(value) || !supported.includes(unit))
+        return "";
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const source = Temporal.PlainDate.from(value);
+        let result;
+        switch (unit) {
+            case "year":
+                result = source.with({ month: 12, day: 31 });
+                break;
+            case "month": {
+                const firstOfNext = source.with({ day: 1 }).add({ months: 1 });
+                result = firstOfNext.subtract({ days: 1 });
+                break;
+            }
+            case "week": {
+                const daysToEndOfWeek = weekStartsOn === "monday"
+                    ? 7 - source.dayOfWeek
+                    : (6 - source.dayOfWeek) % 7;
+                result = source.add({ days: daysToEndOfWeek });
+                break;
+            }
+            case "day":
+                result = source;
+                break;
+            default:
+                return "";
+        }
+        return result.toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,19 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+/**
+ * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit 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("invalid-date", "month") // ""
+ */
+export declare function endOfDateTime(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/plain/calculate/endOfDateTime.js

@@ -0,0 +1,138 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+const supported = [
+    "year",
+    "month",
+    "week",
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/**
+ * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit 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("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;
+            }
+            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 "";
+        }
+        // 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 {
+        return "";
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Return the last day of the quarter for a given ISO date.
+ *
+ * - Returns the last day of the quarter containing the input date.
+ * - Q1 ends on "03-31", Q2 ends on "06-30", Q3 ends on "09-30", Q4 ends on "12-31".
+ * - Validates input using isValidDate.
+ *
+ * @param value ISO PlainDate string
+ * @returns ISO PlainDate string for the last day of the quarter, or "" on invalid input
+ *
+ * @example endOfQuarterForDate("2024-03-15") // "2024-03-31"
+ * @example endOfQuarterForDate("2024-06-15") // "2024-06-30"
+ * @example endOfQuarterForDate("2024-09-15") // "2024-09-30"
+ * @example endOfQuarterForDate("2024-12-15") // "2024-12-31"
+ * @example endOfQuarterForDate("invalid") // ""
+ */
+export declare function endOfQuarterForDate(value: string): string;

package/dist/plain/calculate/endOfQuarterForDate.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the last day of the quarter for a given ISO date.
+ *
+ * - Returns the last day of the quarter containing the input date.
+ * - Q1 ends on "03-31", Q2 ends on "06-30", Q3 ends on "09-30", Q4 ends on "12-31".
+ * - Validates input using isValidDate.
+ *
+ * @param value ISO PlainDate string
+ * @returns ISO PlainDate string for the last day of the quarter, or "" on invalid input
+ *
+ * @example endOfQuarterForDate("2024-03-15") // "2024-03-31"
+ * @example endOfQuarterForDate("2024-06-15") // "2024-06-30"
+ * @example endOfQuarterForDate("2024-09-15") // "2024-09-30"
+ * @example endOfQuarterForDate("2024-12-15") // "2024-12-31"
+ * @example endOfQuarterForDate("invalid") // ""
+ */
+export function endOfQuarterForDate(value) {
+    if (!isValidDate(value)) {
+        return "";
+    }
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const month = date.month;
+        const quarterEndMonth = Math.floor((month - 1) / 3) * 3 + 3;
+        const quarterStart = date.with({ month: quarterEndMonth, day: 1 });
+        const nextQuarterStart = quarterStart.add({ months: 1 });
+        return nextQuarterStart.subtract({ days: 1 }).toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Return the end of the quarter for a given ISO datetime.
+ *
+ * - Returns the last moment of the quarter with time set to 23:59:59.999999999.
+ * - Q1 ends on "03-31T23:59:59.999999999", Q2 ends on "06-30T23:59:59.999999999", etc.
+ * - Validates input using isValidDateTime.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainDateTime string for the end of the quarter, or "" on invalid input
+ *
+ * @example endOfQuarterForDateTime("2024-03-15T12:00:00") // "2024-03-31T23:59:59.999999999"
+ * @example endOfQuarterForDateTime("2024-06-15T12:00:00") // "2024-06-30T23:59:59.999999999"
+ * @example endOfQuarterForDateTime("invalid") // ""
+ */
+export declare function endOfQuarterForDateTime(value: string): string;

package/dist/plain/calculate/endOfQuarterForDateTime.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the end of the quarter for a given ISO datetime.
+ *
+ * - Returns the last moment of the quarter with time set to 23:59:59.999999999.
+ * - Q1 ends on "03-31T23:59:59.999999999", Q2 ends on "06-30T23:59:59.999999999", etc.
+ * - Validates input using isValidDateTime.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainDateTime string for the end of the quarter, or "" on invalid input
+ *
+ * @example endOfQuarterForDateTime("2024-03-15T12:00:00") // "2024-03-31T23:59:59.999999999"
+ * @example endOfQuarterForDateTime("2024-06-15T12:00:00") // "2024-06-30T23:59:59.999999999"
+ * @example endOfQuarterForDateTime("invalid") // ""
+ */
+export function endOfQuarterForDateTime(value) {
+    if (!isValidDateTime(value)) {
+        return "";
+    }
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        const month = dateTime.month;
+        const quarterEndMonth = Math.floor((month - 1) / 3) * 3 + 3;
+        const quarterStart = dateTime.with({
+            month: quarterEndMonth,
+            day: 1,
+            hour: 0,
+            minute: 0,
+            second: 0,
+        });
+        const nextQuarterStart = quarterStart.add({ months: 1 });
+        const lastDayOfQuarter = nextQuarterStart.subtract({ days: 1 });
+        return lastDayOfQuarter
+            .with({
+            hour: 23,
+            minute: 59,
+            second: 59,
+            millisecond: 999,
+            microsecond: 999,
+            nanosecond: 999,
+        })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+type EndOfTimeUnit = Temporal.TimeUnit | "day";
+/**
+ * Return the end of the specified time `unit` for a given ISO 8601 time string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 time string
+ * @param unit EndOfTimeUnit to specify the unit for the end
+ * @param optionsArg optional: fractionalSecondDigits (number)
+ * @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("invalid", "hour") // ""
+ */
+export declare function endOfTime(value: string, unit: EndOfTimeUnit, optionsArg?: {
+    fractionalSecondDigits?: FractionalDigit;
+}): string;
+export {};

package/dist/plain/calculate/endOfTime.js

@@ -0,0 +1,91 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+const supported = [
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/**
+ * Return the end of the specified time `unit` for a given ISO 8601 time string.
+ *
+ * - Returns "" for invalid inputs.
+ *
+ * @param value ISO 8601 time string
+ * @param unit EndOfTimeUnit to specify the unit for the end
+ * @param optionsArg optional: fractionalSecondDigits (number)
+ * @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("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 "";
+        }
+        // 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 {
+        return "";
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Return the ordinal day-of-year (1-based) for `value`.
+ *
+ * - Jan 1 is 1; Dec 31 is 365 (common year) or 366 (leap year).
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns 1-366, or null on invalid input
+ *
+ * @example getDayOfYear("2024-01-01") // 1
+ * @example getDayOfYear("2024-12-31") // 366 (leap year)
+ * @example getDayOfYear("2023-12-31") // 365
+ * @example getDayOfYear("2024-03-01") // 61 (after the Feb 29 leap day)
+ * @example getDayOfYear("invalid") // null
+ */
+export declare function getDayOfYear(value: string): number | null;

package/dist/plain/calculate/getDayOfYear.js

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the ordinal day-of-year (1-based) for `value`.
+ *
+ * - Jan 1 is 1; Dec 31 is 365 (common year) or 366 (leap year).
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns 1-366, or null on invalid input
+ *
+ * @example getDayOfYear("2024-01-01") // 1
+ * @example getDayOfYear("2024-12-31") // 366 (leap year)
+ * @example getDayOfYear("2023-12-31") // 365
+ * @example getDayOfYear("2024-03-01") // 61 (after the Feb 29 leap day)
+ * @example getDayOfYear("invalid") // null
+ */
+export function getDayOfYear(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.dayOfYear;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Return the number of days in the month containing `value`.
+ *
+ * - 28–31 depending on the month; February varies by leap year.
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns number of days in the month (28-31), or null on invalid input
+ *
+ * @example getDaysInMonth("2024-02-15") // 29 (leap year)
+ * @example getDaysInMonth("2023-02-15") // 28
+ * @example getDaysInMonth("2024-04-01") // 30
+ * @example getDaysInMonth("2024-01-01") // 31
+ * @example getDaysInMonth("invalid") // null
+ */
+export declare function getDaysInMonth(value: string): number | null;

package/dist/plain/calculate/getDaysInMonth.js

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the number of days in the month containing `value`.
+ *
+ * - 28–31 depending on the month; February varies by leap year.
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns number of days in the month (28-31), or null on invalid input
+ *
+ * @example getDaysInMonth("2024-02-15") // 29 (leap year)
+ * @example getDaysInMonth("2023-02-15") // 28
+ * @example getDaysInMonth("2024-04-01") // 30
+ * @example getDaysInMonth("2024-01-01") // 31
+ * @example getDaysInMonth("invalid") // null
+ */
+export function getDaysInMonth(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.daysInMonth;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Return the number of days in the calendar year containing `value`.
+ *
+ * - 365 for a common year, 366 for a leap year.
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns 365 or 366, or null on invalid input
+ *
+ * @example getDaysInYear("2024-06-15") // 366 (leap year)
+ * @example getDaysInYear("2023-06-15") // 365
+ * @example getDaysInYear("invalid") // null
+ */
+export declare function getDaysInYear(value: string): number | null;

package/dist/plain/calculate/getDaysInYear.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the number of days in the calendar year containing `value`.
+ *
+ * - 365 for a common year, 366 for a leap year.
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns 365 or 366, or null on invalid input
+ *
+ * @example getDaysInYear("2024-06-15") // 366 (leap year)
+ * @example getDaysInYear("2023-06-15") // 365
+ * @example getDaysInYear("invalid") // null
+ */
+export function getDaysInYear(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.daysInYear;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,16 @@
+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.
+ *
+ * @param units array of DateDurationUnits to evaluate
+ * @returns the largest DateDurationUnit found in the array, or "days" if none are valid
+ *
+ * @example getLargestDateDurationUnit(["months", "days"]) // "months"
+ * @example getLargestDateDurationUnit(["weeks", "days"]) // "weeks"
+ * @example getLargestDateDurationUnit(["days"]) // "days"
+ * @example getLargestDateDurationUnit([]) // "days"
+ */
+export declare function getLargestDateDurationUnit(units: DateDurationUnit[]): DateDurationUnit;

package/dist/plain/calculate/getLargestDateDurationUnit.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ * @param units array of DateDurationUnits to evaluate
+ * @returns the largest DateDurationUnit found in the array, or "days" if none are valid
+ *
+ * @example getLargestDateDurationUnit(["months", "days"]) // "months"
+ * @example getLargestDateDurationUnit(["weeks", "days"]) // "weeks"
+ * @example getLargestDateDurationUnit(["days"]) // "days"
+ * @example getLargestDateDurationUnit([]) // "days"
+ */
+export function getLargestDateDurationUnit(units) {
+    const order = ["years", "months", "weeks", "days"];
+    for (const unit of order) {
+        if (units.includes(unit)) {
+            return unit;
+        }
+    }
+    // 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

@@ -0,0 +1,16 @@
+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.
+ *
+ * @param units array of DateTimeDurationUnit to evaluate
+ * @returns the largest DateTimeDurationUnit found, or "seconds" if none are valid
+ *
+ * @example getLargestDateTimeDurationUnit(["hours", "minutes", "seconds"]) // "hours"
+ * @example getLargestDateTimeDurationUnit(["minutes", "seconds"]) // "minutes"
+ * @example getLargestDateTimeDurationUnit(["seconds"]) // "seconds"
+ * @example getLargestDateTimeDurationUnit([]) // "seconds"
+ */
+export declare function getLargestDateTimeDurationUnit(units: DateTimeDurationUnit[]): DateTimeDurationUnit;