@northguild/gmt 1.14.2

package/dist/internal/resolveRelativeRounding.js

@@ -0,0 +1,20 @@
+/**
+ * Round a relative-time distance to an integer using the given method, defaulting to "round".
+ *
+ * Applied directly to the signed fractional value (not its absolute value), so floor/ceil
+ * respect whether the distance is past (negative) or future (positive) — matches date-fns's
+ * `formatDistanceStrict` `roundingMethod` semantics. A rounded `-0` is preserved rather than
+ * normalized to `0`: `Intl.RelativeTimeFormat` treats the sign of zero as meaningful (with
+ * `numeric: "always"`, `-0` renders as "0 <unit> ago" and `0` as "in 0 <unit>"), so collapsing
+ * it here would change existing `formatRelative*` output for near-zero distances.
+ *
+ * @param value the fractional distance in the target display unit
+ * @param method optional: "floor" | "ceil" | "round" (default "round")
+ * @returns the rounded amount
+ * @example resolveRelativeRounding(2.7) // 3
+ * @example resolveRelativeRounding(2.7, "floor") // 2
+ * @example resolveRelativeRounding(-2.7, "ceil") // -2
+ */
+export function resolveRelativeRounding(value, method = "round") {
+    return Math[method](value);
+}

package/dist/internal/resolveUnixTimeZone.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve an optional Unix diff timeZone to its default (system timeZone) when unset.
+ *
+ * @param timeZone optional IANA timeZone
+ * @returns the resolved timeZone, or "" if invalid
+ * @example resolveUnixTimeZone(undefined) // system timeZone, e.g. "America/New_York"
+ * @example resolveUnixTimeZone("Europe/Helsinki") // "Europe/Helsinki"
+ * @example resolveUnixTimeZone("not-a-timezone") // ""
+ */
+export declare function resolveUnixTimeZone(timeZone?: string): string;
+/**
+ * Validate that both Unix epoch values are finite integers.
+ *
+ * @param value1 first Unix timestamp
+ * @param value2 second Unix timestamp
+ * @returns true if both values are finite integers
+ * @example isValidUnixEpochPair(1704067200000, 1704153600000) // true
+ * @example isValidUnixEpochPair(NaN, 1704153600000) // false
+ */
+export declare function isValidUnixEpochPair(value1: number, value2: number): boolean;

package/dist/internal/resolveUnixTimeZone.js

@@ -0,0 +1,30 @@
+import { getSystemTimeZone } from "../zoned/get/index.js";
+import { isValidTimeZone } from "../zoned/validate/index.js";
+/**
+ * Resolve an optional Unix diff timeZone to its default (system timeZone) when unset.
+ *
+ * @param timeZone optional IANA timeZone
+ * @returns the resolved timeZone, or "" if invalid
+ * @example resolveUnixTimeZone(undefined) // system timeZone, e.g. "America/New_York"
+ * @example resolveUnixTimeZone("Europe/Helsinki") // "Europe/Helsinki"
+ * @example resolveUnixTimeZone("not-a-timezone") // ""
+ */
+export function resolveUnixTimeZone(timeZone) {
+    const resolved = timeZone ?? getSystemTimeZone();
+    return resolved && isValidTimeZone(resolved) ? resolved : "";
+}
+/**
+ * Validate that both Unix epoch values are finite integers.
+ *
+ * @param value1 first Unix timestamp
+ * @param value2 second Unix timestamp
+ * @returns true if both values are finite integers
+ * @example isValidUnixEpochPair(1704067200000, 1704153600000) // true
+ * @example isValidUnixEpochPair(NaN, 1704153600000) // false
+ */
+export function isValidUnixEpochPair(value1, value2) {
+    return (Number.isFinite(value1) &&
+        Number.isInteger(value1) &&
+        Number.isFinite(value2) &&
+        Number.isInteger(value2));
+}

package/dist/internal/timeCycleFieldBounds.d.ts

@@ -0,0 +1,16 @@
+import type { TimeCycleField } from "../types/index.js";
+/**
+ * Return the inclusive wrap bounds for a `TimeCycleField`. Unlike date fields, time field bounds
+ * never depend on the source value — `hour` is always `0–23` (see the `cycleDate`/`cycleTime`/
+ * `cycleZoned` module docs for why GMT doesn't offer a 12-hour `hourCycle` variant).
+ *
+ * @param field the time field being cycled
+ * @example timeCycleFieldBounds("hour") // { min: 0, max: 23 }
+ * @example timeCycleFieldBounds("minute") // { min: 0, max: 59 }
+ * @example timeCycleFieldBounds("millisecond") // { min: 0, max: 999 }
+ * @returns `{ min, max }` inclusive bounds
+ */
+export declare function timeCycleFieldBounds(field: TimeCycleField): {
+    min: number;
+    max: number;
+};

package/dist/internal/timeCycleFieldBounds.js

@@ -0,0 +1,24 @@
+/**
+ * Return the inclusive wrap bounds for a `TimeCycleField`. Unlike date fields, time field bounds
+ * never depend on the source value — `hour` is always `0–23` (see the `cycleDate`/`cycleTime`/
+ * `cycleZoned` module docs for why GMT doesn't offer a 12-hour `hourCycle` variant).
+ *
+ * @param field the time field being cycled
+ * @example timeCycleFieldBounds("hour") // { min: 0, max: 23 }
+ * @example timeCycleFieldBounds("minute") // { min: 0, max: 59 }
+ * @example timeCycleFieldBounds("millisecond") // { min: 0, max: 999 }
+ * @returns `{ min, max }` inclusive bounds
+ */
+export function timeCycleFieldBounds(field) {
+    switch (field) {
+        case "hour":
+            return { min: 0, max: 23 };
+        case "minute":
+        case "second":
+            return { min: 0, max: 59 };
+        case "millisecond":
+        case "microsecond":
+        case "nanosecond":
+            return { min: 0, max: 999 };
+    }
+}

package/dist/internal/toInstantFromUtc.d.ts

@@ -0,0 +1,2 @@
+import { Temporal } from "@js-temporal/polyfill";
+export declare function toInstantFromUtc(value: string): Temporal.Instant | null;

package/dist/internal/toInstantFromUtc.js

@@ -0,0 +1,11 @@
+import { Temporal } from "@js-temporal/polyfill";
+// Convert a UTC ISO datetime string to a Temporal.Instant.
+// Returns null on failure (caller should have already validated with isValidUtc).
+export function toInstantFromUtc(value) {
+    try {
+        return Temporal.Instant.from(value);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Return a PlainDate ISO string with `amount` business days added to `value`.
+ *
+ * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Saturday and Sunday are skipped during the count.
+ * - Returns "" on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param amount number of business days to add
+ * @returns ISO PlainDate string after adding business days, or "" on invalid input
+ *
+ * @example addBusinessDays("2024-03-15", 1) // "2024-03-18"
+ * @example addBusinessDays("2024-03-16", 1) // "2024-03-18"
+ * @example addBusinessDays("2024-03-15", 0) // "2024-03-15"
+ * @example addBusinessDays("invalid", 1) // ""
+ */
+export declare function addBusinessDays(value: string, amount: number): string;

package/dist/plain/calculate/addBusinessDays.js

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { advanceBusinessDays, isValidAmount } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string with `amount` business days added to `value`.
+ *
+ * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Saturday and Sunday are skipped during the count.
+ * - Returns "" on invalid input.
+ *
+ * @param value ISO PlainDate string
+ * @param amount number of business days to add
+ * @returns ISO PlainDate string after adding business days, or "" on invalid input
+ *
+ * @example addBusinessDays("2024-03-15", 1) // "2024-03-18"
+ * @example addBusinessDays("2024-03-16", 1) // "2024-03-18"
+ * @example addBusinessDays("2024-03-15", 0) // "2024-03-15"
+ * @example addBusinessDays("invalid", 1) // ""
+ */
+export function addBusinessDays(value, amount) {
+    if (!isValidDate(value) || !isValidAmount(amount)) {
+        return "";
+    }
+    if (amount === 0) {
+        return value;
+    }
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const direction = amount > 0 ? 1 : -1;
+        return advanceBusinessDays(date, direction, Math.abs(amount)).toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { DateDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDate ISO string with `amount` added according to `units`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the add.
+ * - Accepts a GMT calendar-annotated PlainDate string (as produced by `convertDateToCalendar`,
+ *   e.g. `"5784-06-15[u-ca=hebrew]"`), not just a bare ISO string — E5 (issue #78). Calendar-unit
+ *   arithmetic ("add 1 month") resolves against that calendar (a Hebrew leap month, a Persian
+ *   leap year), and the result is re-formatted in the same calendar — re-derived from the
+ *   arithmetic result, never copied from the input tag, since arithmetic can cross a leap-month
+ *   or era boundary (e.g. Adar I -> Adar). A bare ISO string is unaffected — always treated as,
+ *   and always returns, `"gregorian"`.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in ""). Whether `reject`
+ * actually throws is calendar-dependent: adding 1 year from Hebrew Adar I (a leap-only month)
+ * does NOT throw even with `overflow: "reject"` (Temporal remaps to the non-leap year's Adar
+ * instead of rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the
+ * 5/6-day Pagumen DOES throw.
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param units Partial<Record<DateDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string after addition, or "" on invalid input
+ *
+ * @example addDate("2024-03-10", { days: 5 }) // "2024-03-15"
+ * @example addDate("invalid", { days: 5 }) // ""
+ * @example addDate("2024-01-31", { months: 1 }, { overflow: "constrain" }) // "2024-02-29"
+ * @example addDate("2024-01-31", { months: 1 }, { overflow: "reject" }) // ""
+ * @example addDate("5784-06-15[u-ca=hebrew]", { months: 1 }) // "5784-07-15[u-ca=hebrew]" (Adar I -> Adar, both 30 days)
+ */
+export declare function addDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/addDate.js

@@ -0,0 +1,55 @@
+import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, resolveOverflow, } from "../../internal/index.js";
+import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string with `amount` added according to `units`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the add.
+ * - Accepts a GMT calendar-annotated PlainDate string (as produced by `convertDateToCalendar`,
+ *   e.g. `"5784-06-15[u-ca=hebrew]"`), not just a bare ISO string — E5 (issue #78). Calendar-unit
+ *   arithmetic ("add 1 month") resolves against that calendar (a Hebrew leap month, a Persian
+ *   leap year), and the result is re-formatted in the same calendar — re-derived from the
+ *   arithmetic result, never copied from the input tag, since arithmetic can cross a leap-month
+ *   or era boundary (e.g. Adar I -> Adar). A bare ISO string is unaffected — always treated as,
+ *   and always returns, `"gregorian"`.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in ""). Whether `reject`
+ * actually throws is calendar-dependent: adding 1 year from Hebrew Adar I (a leap-only month)
+ * does NOT throw even with `overflow: "reject"` (Temporal remaps to the non-leap year's Adar
+ * instead of rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the
+ * 5/6-day Pagumen DOES throw.
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param units Partial<Record<DateDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string after addition, or "" on invalid input
+ *
+ * @example addDate("2024-03-10", { days: 5 }) // "2024-03-15"
+ * @example addDate("invalid", { days: 5 }) // ""
+ * @example addDate("2024-01-31", { months: 1 }, { overflow: "constrain" }) // "2024-02-29"
+ * @example addDate("2024-01-31", { months: 1 }, { overflow: "reject" }) // ""
+ * @example addDate("5784-06-15[u-ca=hebrew]", { months: 1 }) // "5784-07-15[u-ca=hebrew]" (Adar I -> Adar, both 30 days)
+ */
+export function addDate(value /* ISO 8601 date */, units, options) {
+    const validDate = isValidCalendarDate(value);
+    const validUnits = Object.keys(units).every(isValidDateDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validDate || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const calendar = calendarSystemOfDateValue(value);
+        if (!calendar) {
+            return "";
+        }
+        const date = parseCalendarDateValue(value);
+        const result = date.add(units, {
+            overflow: resolveOverflow(options?.overflow),
+        });
+        return formatDateInCalendar(result, calendar);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDateTime ISO string with `units` added to `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the add.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ *
+ * @param value ISO PlainDateTime string
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string after addition, or "" on invalid input
+ *
+ * @example addDateTime("2024-03-10T12:00:00", { days: 5 }) // "2024-03-15T12:00:00"
+ * @example addDateTime("invalid", { days: 5 }) // ""
+ * @example addDateTime("2024-01-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
+ */
+export declare function addDateTime(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/addDateTime.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+/**
+ * Return a PlainDateTime ISO string with `units` added to `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the add.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ *
+ * @param value ISO PlainDateTime string
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string after addition, or "" on invalid input
+ *
+ * @example addDateTime("2024-03-10T12:00:00", { days: 5 }) // "2024-03-15T12:00:00"
+ * @example addDateTime("invalid", { days: 5 }) // ""
+ * @example addDateTime("2024-01-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
+ */
+export function addDateTime(value, units, options) {
+    const validDateTime = isValidDateTime(value);
+    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validDateTime || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        return dateTime
+            .add(units, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { Overflow, TimeDurationUnit } from "../../types/index.js";
+/**
+ * Return a PlainTime ISO string with `units` added to `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the add.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
+ * add functions, but PlainTime arithmetic always wraps around the clock (e.g. 23:00 + 2 hours
+ * = 01:00) rather than producing an out-of-range value, so it has no observable effect here.
+ *
+ * @param value ISO PlainTime string
+ * @param units Partial<Record<TimeDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
+ * @returns ISO PlainTime string after addition, or "" on invalid input
+ *
+ * @example addTime("12:00:00", { hours: 1 }) // "13:00:00"
+ * @example addTime("invalid", { hours: 1 }) // ""
+ */
+export declare function addTime(value: string, units: Partial<Record<TimeDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/addTime.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
+/**
+ * Return a PlainTime ISO string with `units` added to `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the add.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
+ * add functions, but PlainTime arithmetic always wraps around the clock (e.g. 23:00 + 2 hours
+ * = 01:00) rather than producing an out-of-range value, so it has no observable effect here.
+ *
+ * @param value ISO PlainTime string
+ * @param units Partial<Record<TimeDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
+ * @returns ISO PlainTime string after addition, or "" on invalid input
+ *
+ * @example addTime("12:00:00", { hours: 1 }) // "13:00:00"
+ * @example addTime("invalid", { hours: 1 }) // ""
+ */
+export function addTime(value, units, options) {
+    const validTime = isValidTime(value);
+    const validUnits = Object.keys(units).every(isValidTimeDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validTime || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const time = Temporal.PlainTime.from(value);
+        return time
+            .add(units, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Restrict `value` to the range [`min`, `max`].
+ *
+ * - Returns `value` if it falls within the bounds (inclusive on both ends).
+ * - Returns `min` if `value` is before `min`.
+ * - Returns `max` if `value` is after `max`.
+ * - Returns `""` if any input is invalid or `min > max`.
+ *
+ * @param value ISO PlainDate string to clamp
+ * @param min ISO PlainDate string for the lower bound (inclusive)
+ * @param max ISO PlainDate string for the upper bound (inclusive)
+ * @returns The clamped date string, or "" on invalid input
+ *
+ * @example clampDate("2024-03-15", "2024-03-01", "2024-03-31") // "2024-03-15"
+ * @example clampDate("2024-02-01", "2024-03-01", "2024-03-31") // "2024-03-01"
+ * @example clampDate("2024-05-01", "2024-03-01", "2024-03-31") // "2024-03-31"
+ * @example clampDate("2024-03-15", "2024-03-31", "2024-03-01") // ""
+ * @example clampDate("invalid", "2024-03-01", "2024-03-31") // ""
+ */
+export declare function clampDate(value: string, min: string, max: string): string;

package/dist/plain/calculate/clampDate.js

@@ -0,0 +1,46 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Restrict `value` to the range [`min`, `max`].
+ *
+ * - Returns `value` if it falls within the bounds (inclusive on both ends).
+ * - Returns `min` if `value` is before `min`.
+ * - Returns `max` if `value` is after `max`.
+ * - Returns `""` if any input is invalid or `min > max`.
+ *
+ * @param value ISO PlainDate string to clamp
+ * @param min ISO PlainDate string for the lower bound (inclusive)
+ * @param max ISO PlainDate string for the upper bound (inclusive)
+ * @returns The clamped date string, or "" on invalid input
+ *
+ * @example clampDate("2024-03-15", "2024-03-01", "2024-03-31") // "2024-03-15"
+ * @example clampDate("2024-02-01", "2024-03-01", "2024-03-31") // "2024-03-01"
+ * @example clampDate("2024-05-01", "2024-03-01", "2024-03-31") // "2024-03-31"
+ * @example clampDate("2024-03-15", "2024-03-31", "2024-03-01") // ""
+ * @example clampDate("invalid", "2024-03-01", "2024-03-31") // ""
+ */
+export function clampDate(value, min, max) {
+    if (!isValidDate(value) || !isValidDate(min) || !isValidDate(max)) {
+        return "";
+    }
+    try {
+        const v = Temporal.PlainDate.from(value);
+        const mn = Temporal.PlainDate.from(min);
+        const mx = Temporal.PlainDate.from(max);
+        if (Temporal.PlainDate.compare(mn, mx) === 1) {
+            return "";
+        }
+        const cmpMin = Temporal.PlainDate.compare(v, mn);
+        const cmpMax = Temporal.PlainDate.compare(v, mx);
+        if (cmpMin < 0) {
+            return min;
+        }
+        if (cmpMax > 0) {
+            return max;
+        }
+        return value;
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Return the candidate date nearest to `target` by calendar distance.
+ *
+ * - Distance is measured in whole days using `Temporal.PlainDate.compare`.
+ * - Returns `null` if the candidates array is empty or contains no valid dates.
+ * - Returns `null` if `target` is invalid.
+ * - On a tie (two equidistant candidates), returns the first one in array order.
+ *
+ * @param target ISO PlainDate string to measure distance from
+ * @param candidates Array of ISO PlainDate strings to choose from
+ * @returns The nearest candidate date string, or null on invalid input
+ *
+ * @example closestDateTo("2024-03-15", ["2024-03-01", "2024-03-20", "2024-03-18"]) // "2024-03-18"
+ * @example closestDateTo("2024-03-15", ["2024-03-01", "2024-03-29"]) // "2024-03-01"
+ * @example closestDateTo("2024-03-15", []) // null
+ * @example closestDateTo("invalid", ["2024-03-01"]) // null
+ */
+export declare function closestDateTo(target: string, candidates: string[]): string | null;

package/dist/plain/calculate/closestDateTo.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the candidate date nearest to `target` by calendar distance.
+ *
+ * - Distance is measured in whole days using `Temporal.PlainDate.compare`.
+ * - Returns `null` if the candidates array is empty or contains no valid dates.
+ * - Returns `null` if `target` is invalid.
+ * - On a tie (two equidistant candidates), returns the first one in array order.
+ *
+ * @param target ISO PlainDate string to measure distance from
+ * @param candidates Array of ISO PlainDate strings to choose from
+ * @returns The nearest candidate date string, or null on invalid input
+ *
+ * @example closestDateTo("2024-03-15", ["2024-03-01", "2024-03-20", "2024-03-18"]) // "2024-03-18"
+ * @example closestDateTo("2024-03-15", ["2024-03-01", "2024-03-29"]) // "2024-03-01"
+ * @example closestDateTo("2024-03-15", []) // null
+ * @example closestDateTo("invalid", ["2024-03-01"]) // null
+ */
+export function closestDateTo(target, candidates) {
+    if (!isValidDate(target) ||
+        !candidates.length ||
+        !candidates.some(isValidDate)) {
+        return null;
+    }
+    try {
+        const t = Temporal.PlainDate.from(target);
+        const validCandidates = candidates.filter(isValidDate);
+        const parsed = validCandidates.map((c) => ({
+            str: c,
+            date: Temporal.PlainDate.from(c),
+        }));
+        const closest = parsed.reduce((best, candidate) => {
+            const bestDist = Math.abs(t.until(best.date).days);
+            const candDist = Math.abs(t.until(candidate.date).days);
+            return candDist < bestDist ? candidate : best;
+        }, parsed[0]);
+        return closest.str;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { DateCycleField, Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDate ISO string with `field` cycled by `amount`, wrapping at that field's own
+ * min/max instead of carrying into the next larger field.
+ *
+ * - `cycleDate` is not `addDate`: cycling December's `month` by `+1` stays in the same year
+ *   (`"2024-12-15"` → `"2024-01-15"`), where `addDate(value, { months: 1 })` would correctly
+ *   overflow into January of the *next* year. Reach for `addDate` when you want calendar
+ *   arithmetic; reach for `cycleDate` when a single field (e.g. a datepicker segment) must stay
+ *   isolated from the others.
+ * - `year` has no upper/lower wrap — cycling it is plain addition (or rounding, see below).
+ *   `month` wraps `1–12`. `day` wraps `1`–the **current** month's day count, so cycling `day`
+ *   never changes `month`.
+ * - Cycling `month` or `year` can still shift `day` via `overflow` — e.g. cycling `month` from a
+ *   31st into a shorter month clamps under the default `"constrain"` (or returns `""` under
+ *   `"reject"`) exactly the way `setDate`'s own `.with()` call does; this is the same clamping
+ *   `addDate`'s Jan 31 + 1 month case produces, not new behavior.
+ * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
+ *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
+ *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling `year` `2022` by `+5` with
+ *   `round: true` lands on `2025` (the next multiple of 5 above 2022), not `2020` (the nearest
+ *   multiple).
+ * - Returns "" for an invalid `value` or an invalid `field`.
+ *
+ * @param value ISO PlainDate string
+ * @param field the field to cycle: "year" | "month" | "day"
+ * @param amount signed amount to cycle by
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleDate("2024-06-15", "month", 1) // "2024-07-15"
+ * @example cycleDate("2024-12-15", "month", 1) // "2024-01-15" (wraps, stays in the same year)
+ * @example cycleDate("2024-12-31", "day", 1) // "2024-12-01" (wraps within the same month)
+ * @example cycleDate("2024-01-15", "month", 13) // "2024-02-15" (amount larger than the range)
+ * @example cycleDate("2024-01-31", "month", 1) // "2024-02-29" (constrain clamps the day)
+ * @example cycleDate("2024-01-31", "month", 1, { overflow: "reject" }) // ""
+ * @example cycleDate("2022-02-03", "year", 5, { round: true }) // "2025-02-03"
+ * @example cycleDate("2024-06-15", "week", 1) // "" ("week" is not a cyclable date field)
+ * @example cycleDate("invalid", "month", 1) // ""
+ */
+export declare function cycleDate(value: string, field: DateCycleField, amount: number, options?: {
+    round?: boolean;
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/cycleDate.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { cycleFieldValue, dateCycleFieldBounds } from "../../internal/index.js";
+import { isValidDate, isValidDateCycleField } from "../validate/index.js";
+import { setDate } from "./setDate.js";
+/**
+ * Return a PlainDate ISO string with `field` cycled by `amount`, wrapping at that field's own
+ * min/max instead of carrying into the next larger field.
+ *
+ * - `cycleDate` is not `addDate`: cycling December's `month` by `+1` stays in the same year
+ *   (`"2024-12-15"` → `"2024-01-15"`), where `addDate(value, { months: 1 })` would correctly
+ *   overflow into January of the *next* year. Reach for `addDate` when you want calendar
+ *   arithmetic; reach for `cycleDate` when a single field (e.g. a datepicker segment) must stay
+ *   isolated from the others.
+ * - `year` has no upper/lower wrap — cycling it is plain addition (or rounding, see below).
+ *   `month` wraps `1–12`. `day` wraps `1`–the **current** month's day count, so cycling `day`
+ *   never changes `month`.
+ * - Cycling `month` or `year` can still shift `day` via `overflow` — e.g. cycling `month` from a
+ *   31st into a shorter month clamps under the default `"constrain"` (or returns `""` under
+ *   `"reject"`) exactly the way `setDate`'s own `.with()` call does; this is the same clamping
+ *   `addDate`'s Jan 31 + 1 month case produces, not new behavior.
+ * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
+ *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
+ *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling `year` `2022` by `+5` with
+ *   `round: true` lands on `2025` (the next multiple of 5 above 2022), not `2020` (the nearest
+ *   multiple).
+ * - Returns "" for an invalid `value` or an invalid `field`.
+ *
+ * @param value ISO PlainDate string
+ * @param field the field to cycle: "year" | "month" | "day"
+ * @param amount signed amount to cycle by
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleDate("2024-06-15", "month", 1) // "2024-07-15"
+ * @example cycleDate("2024-12-15", "month", 1) // "2024-01-15" (wraps, stays in the same year)
+ * @example cycleDate("2024-12-31", "day", 1) // "2024-12-01" (wraps within the same month)
+ * @example cycleDate("2024-01-15", "month", 13) // "2024-02-15" (amount larger than the range)
+ * @example cycleDate("2024-01-31", "month", 1) // "2024-02-29" (constrain clamps the day)
+ * @example cycleDate("2024-01-31", "month", 1, { overflow: "reject" }) // ""
+ * @example cycleDate("2022-02-03", "year", 5, { round: true }) // "2025-02-03"
+ * @example cycleDate("2024-06-15", "week", 1) // "" ("week" is not a cyclable date field)
+ * @example cycleDate("invalid", "month", 1) // ""
+ */
+export function cycleDate(value, field, amount, options) {
+    if (!isValidDate(value) || !isValidDateCycleField(field))
+        return "";
+    try {
+        const date = Temporal.PlainDate.from(value);
+        const bounds = dateCycleFieldBounds(field, date);
+        const newValue = cycleFieldValue(date[field], amount, bounds, options?.round ?? false);
+        return setDate(value, { [field]: newValue }, { overflow: options?.overflow });
+    }
+    catch {
+        return "";
+    }
+}