@northguild/gmt 1.14.2

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

@@ -0,0 +1,24 @@
+/**
+ * Return the number of weeks (52 or 53) in the locale week-numbering year
+ * containing `value`, using `locale`'s first day of week and
+ * minimal-days-in-first-week.
+ *
+ * - `getWeeksInYear`'s locale-relative counterpart — that function uses
+ *   the fixed ISO rule, this one uses `locale`'s week-numbering rule
+ *   (via `Intl.Locale.prototype.weekInfo`), and the two can disagree on
+ *   the same date.
+ * - Computed as the number of calendar days between the locale
+ *   week-year's start and the next week-year's start, divided by 7 —
+ *   always a whole number, since both bounds fall on the locale's first
+ *   day of week.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns 52 or 53, or null on invalid input
+ *
+ * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52
+ * @example getWeeksInLocaleWeekYear("2020-06-15", "de-DE") // 53
+ * @example getWeeksInLocaleWeekYear("invalid", "en-US") // null
+ */
+export declare function getWeeksInLocaleWeekYear(value: string, locale: string): number | null;

package/dist/plain/calculate/getWeeksInLocaleWeekYear.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek, getLocaleMinimalDaysInFirstWeek, getLocaleWeekYearBounds, } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the number of weeks (52 or 53) in the locale week-numbering year
+ * containing `value`, using `locale`'s first day of week and
+ * minimal-days-in-first-week.
+ *
+ * - `getWeeksInYear`'s locale-relative counterpart — that function uses
+ *   the fixed ISO rule, this one uses `locale`'s week-numbering rule
+ *   (via `Intl.Locale.prototype.weekInfo`), and the two can disagree on
+ *   the same date.
+ * - Computed as the number of calendar days between the locale
+ *   week-year's start and the next week-year's start, divided by 7 —
+ *   always a whole number, since both bounds fall on the locale's first
+ *   day of week.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns 52 or 53, or null on invalid input
+ *
+ * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52
+ * @example getWeeksInLocaleWeekYear("2020-06-15", "de-DE") // 53
+ * @example getWeeksInLocaleWeekYear("invalid", "en-US") // null
+ */
+export function getWeeksInLocaleWeekYear(value, locale) {
+    if (!isValidDate(value))
+        return null;
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    const minimalDays = getLocaleMinimalDaysInFirstWeek(locale);
+    if (firstDay === null || minimalDays === null)
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const { start, end } = getLocaleWeekYearBounds(date, firstDay, minimalDays);
+        const days = start.until(end, { largestUnit: "days" }).days;
+        return days / 7;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Return the number of calendar-grid rows (4, 5, or 6) `value`'s month
+ * spans, using `locale`'s first day of week.
+ *
+ * - The count depends on which day the week starts — the same month can
+ *   span 4, 5, or 6 rows depending on locale (e.g. February 2026 is 4
+ *   rows starting Sunday but 5 rows starting Monday).
+ * - Sized the same way `@internationalized/date`'s `getWeeksInMonth`
+ *   sizes a datepicker's calendar grid.
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns number of week-rows the month spans (4-6), or null on invalid input
+ *
+ * @example getWeeksInMonth("2024-02-15", "en-US") // 5
+ * @example getWeeksInMonth("2026-02-15", "en-US") // 4
+ * @example getWeeksInMonth("2026-02-15", "en-GB") // 5
+ * @example getWeeksInMonth("invalid", "en-US") // null
+ */
+export declare function getWeeksInMonth(value: string, locale: string): number | null;

package/dist/plain/calculate/getWeeksInMonth.js

@@ -0,0 +1,40 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek, monthGridWeekRow } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the number of calendar-grid rows (4, 5, or 6) `value`'s month
+ * spans, using `locale`'s first day of week.
+ *
+ * - The count depends on which day the week starts — the same month can
+ *   span 4, 5, or 6 rows depending on locale (e.g. February 2026 is 4
+ *   rows starting Sunday but 5 rows starting Monday).
+ * - Sized the same way `@internationalized/date`'s `getWeeksInMonth`
+ *   sizes a datepicker's calendar grid.
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`.
+ * - Returns null if `value` or `locale` is invalid.
+ *
+ * @param value ISO PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns number of week-rows the month spans (4-6), or null on invalid input
+ *
+ * @example getWeeksInMonth("2024-02-15", "en-US") // 5
+ * @example getWeeksInMonth("2026-02-15", "en-US") // 4
+ * @example getWeeksInMonth("2026-02-15", "en-GB") // 5
+ * @example getWeeksInMonth("invalid", "en-US") // null
+ */
+export function getWeeksInMonth(value, locale) {
+    if (!isValidDate(value))
+        return null;
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const firstOfMonth = date.with({ day: 1 });
+        return monthGridWeekRow(firstOfMonth, firstDay, date.daysInMonth);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Return the number of ISO weeks (52 or 53) in the ISO week-numbering year
+ * containing `value`.
+ *
+ * - Uses `value`'s ISO week-numbering year (`Temporal.PlainDate.yearOfWeek`),
+ *   not its calendar year — late-December/early-January dates can belong to
+ *   a different ISO week-year than their calendar year (e.g. 2021-01-01 is
+ *   ISO week-year 2020's week 53).
+ * - December 28 always falls in the ISO week-numbering year's final week
+ *   (ISO week 1 always contains Jan 4, so Dec 28 — exactly 52 weeks after —
+ *   is always in the last week), so its `weekOfYear` reports the year's
+ *   total week count.
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns 52 or 53, or null on invalid input
+ *
+ * @example getWeeksInYear("2024-06-15") // 52
+ * @example getWeeksInYear("2020-06-15") // 53
+ * @example getWeeksInYear("2021-01-01") // 53 (belongs to ISO week-year 2020)
+ * @example getWeeksInYear("invalid") // null
+ */
+export declare function getWeeksInYear(value: string): number | null;

package/dist/plain/calculate/getWeeksInYear.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the number of ISO weeks (52 or 53) in the ISO week-numbering year
+ * containing `value`.
+ *
+ * - Uses `value`'s ISO week-numbering year (`Temporal.PlainDate.yearOfWeek`),
+ *   not its calendar year — late-December/early-January dates can belong to
+ *   a different ISO week-year than their calendar year (e.g. 2021-01-01 is
+ *   ISO week-year 2020's week 53).
+ * - December 28 always falls in the ISO week-numbering year's final week
+ *   (ISO week 1 always contains Jan 4, so Dec 28 — exactly 52 weeks after —
+ *   is always in the last week), so its `weekOfYear` reports the year's
+ *   total week count.
+ * - Returns null on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @returns 52 or 53, or null on invalid input
+ *
+ * @example getWeeksInYear("2024-06-15") // 52
+ * @example getWeeksInYear("2020-06-15") // 53
+ * @example getWeeksInYear("2021-01-01") // 53 (belongs to ISO week-year 2020)
+ * @example getWeeksInYear("invalid") // null
+ */
+export function getWeeksInYear(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const yearOfWeek = date.yearOfWeek;
+        if (yearOfWeek === undefined)
+            return null;
+        const lastWeekAnchor = Temporal.PlainDate.from({
+            year: yearOfWeek,
+            month: 12,
+            day: 28,
+        });
+        return lastWeekAnchor.weekOfYear ?? null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,64 @@
+export * from "./addBusinessDays.js";
+export * from "./addDate.js";
+export * from "./addDateTime.js";
+export * from "./addTime.js";
+export * from "./clampDate.js";
+export * from "./closestDateTo.js";
+export * from "./cycleDate.js";
+export * from "./cycleDateTime.js";
+export * from "./cycleTime.js";
+export * from "./diffDate.js";
+export * from "./diffDateAsDuration.js";
+export * from "./diffDateTime.js";
+export * from "./diffDateTimeAsDuration.js";
+export * from "./diffTime.js";
+export * from "./endOfDate.js";
+export * from "./endOfDateTime.js";
+export * from "./endOfQuarterForDate.js";
+export * from "./endOfQuarterForDateTime.js";
+export * from "./endOfTime.js";
+export * from "./getDayOfYear.js";
+export * from "./getDaysInMonth.js";
+export * from "./getDaysInYear.js";
+export * from "./getLargestDateDurationUnit.js";
+export * from "./getLargestDateTimeDurationUnit.js";
+export * from "./getLargestTimeDurationUnit.js";
+export * from "./getLocaleDayOfWeek.js";
+export * from "./getLocaleEndOfWeek.js";
+export * from "./getLocaleStartOfWeek.js";
+export * from "./getLocaleWeekYear.js";
+export * from "./getQuarterForDate.js";
+export * from "./getQuarterForDateTime.js";
+export * from "./getWeekNumber.js";
+export * from "./getWeekOfMonth.js";
+export * from "./getWeekYear.js";
+export * from "./getWeeksInLocaleWeekYear.js";
+export * from "./getWeeksInMonth.js";
+export * from "./getWeeksInYear.js";
+export * from "./maxDate.js";
+export * from "./maxDateTime.js";
+export * from "./maxTime.js";
+export * from "./minDate.js";
+export * from "./minDateTime.js";
+export * from "./minTime.js";
+export * from "./nextWeekday.js";
+export * from "./previousWeekday.js";
+export * from "./roundDate.js";
+export * from "./roundDateTime.js";
+export * from "./roundTime.js";
+export * from "./setDate.js";
+export * from "./setDateTime.js";
+export * from "./setTime.js";
+export * from "./sortDates.js";
+export * from "./sortDateTimes.js";
+export * from "./sortTimes.js";
+export * from "./startOfDate.js";
+export * from "./startOfDateTime.js";
+export * from "./startOfQuarterForDate.js";
+export * from "./startOfQuarterForDateTime.js";
+export * from "./startOfTime.js";
+export * from "./subtractBusinessDays.js";
+export * from "./subtractDate.js";
+export * from "./subtractDateTime.js";
+export * from "./subtractTime.js";
+export * from "./weekOfYear.js";

package/dist/plain/calculate/index.js

@@ -0,0 +1,64 @@
+export * from "./addBusinessDays.js";
+export * from "./addDate.js";
+export * from "./addDateTime.js";
+export * from "./addTime.js";
+export * from "./clampDate.js";
+export * from "./closestDateTo.js";
+export * from "./cycleDate.js";
+export * from "./cycleDateTime.js";
+export * from "./cycleTime.js";
+export * from "./diffDate.js";
+export * from "./diffDateAsDuration.js";
+export * from "./diffDateTime.js";
+export * from "./diffDateTimeAsDuration.js";
+export * from "./diffTime.js";
+export * from "./endOfDate.js";
+export * from "./endOfDateTime.js";
+export * from "./endOfQuarterForDate.js";
+export * from "./endOfQuarterForDateTime.js";
+export * from "./endOfTime.js";
+export * from "./getDayOfYear.js";
+export * from "./getDaysInMonth.js";
+export * from "./getDaysInYear.js";
+export * from "./getLargestDateDurationUnit.js";
+export * from "./getLargestDateTimeDurationUnit.js";
+export * from "./getLargestTimeDurationUnit.js";
+export * from "./getLocaleDayOfWeek.js";
+export * from "./getLocaleEndOfWeek.js";
+export * from "./getLocaleStartOfWeek.js";
+export * from "./getLocaleWeekYear.js";
+export * from "./getQuarterForDate.js";
+export * from "./getQuarterForDateTime.js";
+export * from "./getWeekNumber.js";
+export * from "./getWeekOfMonth.js";
+export * from "./getWeekYear.js";
+export * from "./getWeeksInLocaleWeekYear.js";
+export * from "./getWeeksInMonth.js";
+export * from "./getWeeksInYear.js";
+export * from "./maxDate.js";
+export * from "./maxDateTime.js";
+export * from "./maxTime.js";
+export * from "./minDate.js";
+export * from "./minDateTime.js";
+export * from "./minTime.js";
+export * from "./nextWeekday.js";
+export * from "./previousWeekday.js";
+export * from "./roundDate.js";
+export * from "./roundDateTime.js";
+export * from "./roundTime.js";
+export * from "./setDate.js";
+export * from "./setDateTime.js";
+export * from "./setTime.js";
+export * from "./sortDates.js";
+export * from "./sortDateTimes.js";
+export * from "./sortTimes.js";
+export * from "./startOfDate.js";
+export * from "./startOfDateTime.js";
+export * from "./startOfQuarterForDate.js";
+export * from "./startOfQuarterForDateTime.js";
+export * from "./startOfTime.js";
+export * from "./subtractBusinessDays.js";
+export * from "./subtractDate.js";
+export * from "./subtractDateTime.js";
+export * from "./subtractTime.js";
+export * from "./weekOfYear.js";

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

@@ -0,0 +1,13 @@
+/**
+ * Return the latest (maximum) of the given PlainDate values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dates Array of ISO PlainDate strings (e.g. "2024-03-10")
+ * @returns The latest date string, or null on invalid input
+ *
+ * @example maxDate(["2024-03-10", "2024-03-15", "2024-03-12"]) // "2024-03-15"
+ * @example maxDate([]) // null
+ */
+export declare function maxDate(dates: string[]): string | null;

package/dist/plain/calculate/maxDate.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the latest (maximum) of the given PlainDate values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dates Array of ISO PlainDate strings (e.g. "2024-03-10")
+ * @returns The latest date string, or null on invalid input
+ *
+ * @example maxDate(["2024-03-10", "2024-03-15", "2024-03-12"]) // "2024-03-15"
+ * @example maxDate([]) // null
+ */
+export function maxDate(dates) {
+    if (!dates.length)
+        return null;
+    const valid = dates.filter(isValidDate);
+    if (!valid.length)
+        return null;
+    try {
+        const max = valid.reduce((currentMax, candidateStr) => {
+            const candidate = Temporal.PlainDate.from(candidateStr);
+            return Temporal.PlainDate.compare(candidate, currentMax) > 0
+                ? candidate
+                : currentMax;
+        }, Temporal.PlainDate.from(valid[0]));
+        return max.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the latest (maximum) of the given PlainDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid datetimes.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dateTimes Array of ISO PlainDateTime strings (e.g. "2024-03-10T12:00:00")
+ * @returns The latest datetime string, or null on invalid input
+ *
+ * @example maxDateTime(["2024-03-10T12:00:00", "2024-03-15T12:00:00", "2024-03-12T12:00:00"]) // "2024-03-15T12:00:00"
+ * @example maxDateTime([]) // null
+ */
+export declare function maxDateTime(dateTimes: string[]): string | null;

package/dist/plain/calculate/maxDateTime.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the latest (maximum) of the given PlainDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid datetimes.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dateTimes Array of ISO PlainDateTime strings (e.g. "2024-03-10T12:00:00")
+ * @returns The latest datetime string, or null on invalid input
+ *
+ * @example maxDateTime(["2024-03-10T12:00:00", "2024-03-15T12:00:00", "2024-03-12T12:00:00"]) // "2024-03-15T12:00:00"
+ * @example maxDateTime([]) // null
+ */
+export function maxDateTime(dateTimes) {
+    if (!dateTimes.length)
+        return null;
+    const valid = dateTimes.filter(isValidDateTime);
+    if (!valid.length)
+        return null;
+    try {
+        const max = valid.reduce((currentMax, candidateStr) => {
+            const candidate = Temporal.PlainDateTime.from(candidateStr);
+            return Temporal.PlainDateTime.compare(candidate, currentMax) > 0
+                ? candidate
+                : currentMax;
+        }, Temporal.PlainDateTime.from(valid[0]));
+        return max.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the latest (maximum) of the given PlainTime values.
+ *
+ * - Returns null if the array is empty or contains no valid times.
+ * - Validation is performed on each item in the array.
+ *
+ * @param times Array of ISO PlainTime strings (e.g. "14:30:00")
+ * @returns The latest time string, or null on invalid input
+ *
+ * @example maxTime(["14:30:00", "09:00:00", "20:45:00"]) // "20:45:00"
+ * @example maxTime([]) // null
+ */
+export declare function maxTime(times: string[]): string | null;

package/dist/plain/calculate/maxTime.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Return the latest (maximum) of the given PlainTime values.
+ *
+ * - Returns null if the array is empty or contains no valid times.
+ * - Validation is performed on each item in the array.
+ *
+ * @param times Array of ISO PlainTime strings (e.g. "14:30:00")
+ * @returns The latest time string, or null on invalid input
+ *
+ * @example maxTime(["14:30:00", "09:00:00", "20:45:00"]) // "20:45:00"
+ * @example maxTime([]) // null
+ */
+export function maxTime(times) {
+    if (!times.length)
+        return null;
+    const valid = times.filter(isValidTime);
+    if (!valid.length)
+        return null;
+    try {
+        const max = valid.reduce((currentMax, candidateStr) => {
+            const candidate = Temporal.PlainTime.from(candidateStr);
+            return Temporal.PlainTime.compare(candidate, currentMax) > 0
+                ? candidate
+                : currentMax;
+        }, Temporal.PlainTime.from(valid[0]));
+        return max.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the earliest (minimum) of the given PlainDate values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dates Array of ISO PlainDate strings (e.g. "2024-03-10")
+ * @returns The earliest date string, or null on invalid input
+ *
+ * @example minDate(["2024-03-10", "2024-03-15", "2024-03-12"]) // "2024-03-10"
+ * @example minDate([]) // null
+ */
+export declare function minDate(dates: string[]): string | null;

package/dist/plain/calculate/minDate.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the earliest (minimum) of the given PlainDate values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dates Array of ISO PlainDate strings (e.g. "2024-03-10")
+ * @returns The earliest date string, or null on invalid input
+ *
+ * @example minDate(["2024-03-10", "2024-03-15", "2024-03-12"]) // "2024-03-10"
+ * @example minDate([]) // null
+ */
+export function minDate(dates) {
+    if (!dates.length)
+        return null;
+    const valid = dates.filter(isValidDate);
+    if (!valid.length)
+        return null;
+    try {
+        const min = valid.reduce((currentMin, candidateStr) => {
+            const candidate = Temporal.PlainDate.from(candidateStr);
+            return Temporal.PlainDate.compare(candidate, currentMin) < 0
+                ? candidate
+                : currentMin;
+        }, Temporal.PlainDate.from(valid[0]));
+        return min.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the earliest (minimum) of the given PlainDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid datetimes.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dateTimes Array of ISO PlainDateTime strings (e.g. "2024-03-10T12:00:00")
+ * @returns The earliest datetime string, or null on invalid input
+ *
+ * @example minDateTime(["2024-03-10T12:00:00", "2024-03-15T12:00:00", "2024-03-12T12:00:00"]) // "2024-03-10T12:00:00"
+ * @example minDateTime([]) // null
+ */
+export declare function minDateTime(dateTimes: string[]): string | null;

package/dist/plain/calculate/minDateTime.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the earliest (minimum) of the given PlainDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid datetimes.
+ * - Validation is performed on each item in the array.
+ *
+ * @param dateTimes Array of ISO PlainDateTime strings (e.g. "2024-03-10T12:00:00")
+ * @returns The earliest datetime string, or null on invalid input
+ *
+ * @example minDateTime(["2024-03-10T12:00:00", "2024-03-15T12:00:00", "2024-03-12T12:00:00"]) // "2024-03-10T12:00:00"
+ * @example minDateTime([]) // null
+ */
+export function minDateTime(dateTimes) {
+    if (!dateTimes.length)
+        return null;
+    const valid = dateTimes.filter(isValidDateTime);
+    if (!valid.length)
+        return null;
+    try {
+        const min = valid.reduce((currentMin, candidateStr) => {
+            const candidate = Temporal.PlainDateTime.from(candidateStr);
+            return Temporal.PlainDateTime.compare(candidate, currentMin) < 0
+                ? candidate
+                : currentMin;
+        }, Temporal.PlainDateTime.from(valid[0]));
+        return min.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the earliest (minimum) of the given PlainTime values.
+ *
+ * - Returns null if the array is empty or contains no valid times.
+ * - Validation is performed on each item in the array.
+ *
+ * @param times Array of ISO PlainTime strings (e.g. "14:30:00")
+ * @returns The earliest time string, or null on invalid input
+ *
+ * @example minTime(["14:30:00", "09:00:00", "20:45:00"]) // "09:00:00"
+ * @example minTime([]) // null
+ */
+export declare function minTime(times: string[]): string | null;

package/dist/plain/calculate/minTime.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Return the earliest (minimum) of the given PlainTime values.
+ *
+ * - Returns null if the array is empty or contains no valid times.
+ * - Validation is performed on each item in the array.
+ *
+ * @param times Array of ISO PlainTime strings (e.g. "14:30:00")
+ * @returns The earliest time string, or null on invalid input
+ *
+ * @example minTime(["14:30:00", "09:00:00", "20:45:00"]) // "09:00:00"
+ * @example minTime([]) // null
+ */
+export function minTime(times) {
+    if (!times.length)
+        return null;
+    const valid = times.filter(isValidTime);
+    if (!valid.length)
+        return null;
+    try {
+        const min = valid.reduce((currentMin, candidateStr) => {
+            const candidate = Temporal.PlainTime.from(candidateStr);
+            return Temporal.PlainTime.compare(candidate, currentMin) < 0
+                ? candidate
+                : currentMin;
+        }, Temporal.PlainTime.from(valid[0]));
+        return min.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Return a PlainDate ISO string for the next occurrence of `dayOfWeek` on or after `value`.
+ *
+ * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
+ *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
+ * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
+ *   `dayOfWeek`: `false` advances a full week (matching date-fns), `true` returns `value` as-is.
+ * - Returns "" on invalid input.
+ *
+ * Replaces date-fns's sixteen `next*` functions with one parameterized call:
+ *
+ * | date-fns          | gmt                          |
+ * | ----------------- | ----------------------------- |
+ * | `nextMonday`      | `nextWeekday(value, 1)`      |
+ * | `nextTuesday`     | `nextWeekday(value, 2)`      |
+ * | `nextWednesday`   | `nextWeekday(value, 3)`      |
+ * | `nextThursday`    | `nextWeekday(value, 4)`      |
+ * | `nextFriday`      | `nextWeekday(value, 5)`      |
+ * | `nextSaturday`    | `nextWeekday(value, 6)`      |
+ * | `nextSunday`      | `nextWeekday(value, 7)`      |
+ * | `nextDay(v, n)`   | `nextWeekday(value, n)`      |
+ *
+ * @param value ISO PlainDate string
+ * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
+ * @param options optional: inclusive (boolean, default false)
+ * @returns ISO PlainDate string for the next occurrence of `dayOfWeek`, or "" on invalid input
+ *
+ * @example nextWeekday("2024-03-15", 5) // "2024-03-22" (2024-03-15 is already a Friday, so it advances a full week)
+ * @example nextWeekday("2024-03-15", 5, { inclusive: true }) // "2024-03-15"
+ * @example nextWeekday("2024-03-13", 5) // "2024-03-15" (Wednesday -> next Friday)
+ * @example nextWeekday("invalid", 5) // ""
+ * @example nextWeekday("2024-03-15", 8) // "" (dayOfWeek out of range)
+ */
+export declare function nextWeekday(value: string, dayOfWeek: number, options?: {
+    inclusive?: boolean;
+}): string;