@northguild/gmt 1.14.2

package/dist/utc/calculate/endOfQuarterForUtc.js

@@ -0,0 +1,49 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Return the end of the quarter for a given UTC Instant string.
+ *
+ * - Calculates quarter end month: Q1=3, Q2=6, Q3=9, Q4=12.
+ * - Returns last moment of the quarter.
+ * - Returns "" for invalid input.
+ *
+ * @param value UTC Instant string
+ * @returns UTC Instant string for the end of the quarter, or "" on invalid input
+ *
+ * @example endOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-03-31T23:59:59.999Z"
+ * @example endOfQuarterForUtc("invalid") // ""
+ */
+export function endOfQuarterForUtc(value) {
+    if (!isValidUtc(value)) {
+        return "";
+    }
+    try {
+        const instant = Temporal.Instant.from(value);
+        const zdt = instant.toZonedDateTimeISO("UTC");
+        const month = zdt.month;
+        const quarterEndMonth = Math.floor((month - 1) / 3) * 3 + 3;
+        const quarterStart = zdt.with({
+            month: quarterEndMonth,
+            day: 1,
+            hour: 0,
+            minute: 0,
+            second: 0,
+        });
+        const nextQuarterStart = quarterStart.add({ months: 1 });
+        const lastDayOfQuarter = nextQuarterStart.subtract({ days: 1 });
+        const result = lastDayOfQuarter
+            .with({
+            hour: 23,
+            minute: 59,
+            second: 59,
+            millisecond: 999,
+            microsecond: 999,
+            nanosecond: 999,
+        })
+            .toInstant();
+        return result.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/utc/calculate/endOfUtc.d.ts

@@ -0,0 +1,22 @@
+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 UTC datetime string.
+ *
+ * - Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns UTC Instant string representing the end of the unit, or "" on invalid input
+ *
+ * @example endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"
+ * @example endOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-31T23:59:59.999999999Z"
+ * @example endOfUtc("invalid", "year") // ""
+ */
+export declare function endOfUtc(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/utc/calculate/endOfUtc.js

@@ -0,0 +1,21 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { startOrEndOfUtc } from "./startOrEndOfUtc.js";
+/**
+ * Return the end of the specified date-time `unit` for a given UTC datetime string.
+ *
+ * - Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns UTC Instant string representing the end of the unit, or "" on invalid input
+ *
+ * @example endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"
+ * @example endOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-31T23:59:59.999999999Z"
+ * @example endOfUtc("invalid", "year") // ""
+ */
+export function endOfUtc(value, unit, options) {
+    return startOrEndOfUtc(value, unit, options ?? {}, true);
+}

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

@@ -0,0 +1,14 @@
+export * from "./addUtc.js";
+export * from "./diffUtc.js";
+export * from "./diffUtcAsDuration.js";
+export * from "./endOfQuarterForUtc.js";
+export * from "./endOfUtc.js";
+export * from "./isBetweenUtc.js";
+export * from "./maxUtc.js";
+export * from "./minUtc.js";
+export * from "./roundUtc.js";
+export * from "./setUtc.js";
+export * from "./sortUtc.js";
+export * from "./startOfQuarterForUtc.js";
+export * from "./startOfUtc.js";
+export * from "./subtractUtc.js";

package/dist/utc/calculate/index.js

@@ -0,0 +1,14 @@
+export * from "./addUtc.js";
+export * from "./diffUtc.js";
+export * from "./diffUtcAsDuration.js";
+export * from "./endOfQuarterForUtc.js";
+export * from "./endOfUtc.js";
+export * from "./isBetweenUtc.js";
+export * from "./maxUtc.js";
+export * from "./minUtc.js";
+export * from "./roundUtc.js";
+export * from "./setUtc.js";
+export * from "./sortUtc.js";
+export * from "./startOfQuarterForUtc.js";
+export * from "./startOfUtc.js";
+export * from "./subtractUtc.js";

package/dist/utc/calculate/isBetweenUtc.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return true when `value` is between `start` and `end` (inclusive by default).
+ *
+ * - Uses Temporal.Instant.compare for comparison.
+ * - Returns false if start > end or inputs are invalid.
+ * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
+ *
+ * @param value ISO UTC datetime string to check
+ * @param start ISO UTC datetime string for range start
+ * @param end ISO UTC datetime string for range end
+ * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @returns boolean indicating whether value is between start and end
+ *
+ * @example isBetweenUtc("2024-03-15T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // true
+ * @example isBetweenUtc("2024-03-25T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
+ * @example isBetweenUtc("invalid", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
+ */
+export declare function isBetweenUtc(value: string, start: string, end: string, options?: {
+    inclusiveStart?: boolean;
+    inclusiveEnd?: boolean;
+}): boolean;

package/dist/utc/calculate/isBetweenUtc.js

@@ -0,0 +1,52 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return true when `value` is between `start` and `end` (inclusive by default).
+ *
+ * - Uses Temporal.Instant.compare for comparison.
+ * - Returns false if start > end or inputs are invalid.
+ * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
+ *
+ * @param value ISO UTC datetime string to check
+ * @param start ISO UTC datetime string for range start
+ * @param end ISO UTC datetime string for range end
+ * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @returns boolean indicating whether value is between start and end
+ *
+ * @example isBetweenUtc("2024-03-15T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // true
+ * @example isBetweenUtc("2024-03-25T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
+ * @example isBetweenUtc("invalid", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
+ */
+export function isBetweenUtc(value, start, end, options) {
+    const inclusiveStart = options?.inclusiveStart ?? true;
+    const inclusiveEnd = options?.inclusiveEnd ?? true;
+    if (!isValidUtc(value) || !isValidUtc(start) || !isValidUtc(end)) {
+        return false;
+    }
+    let instant;
+    let startInstant;
+    let endInstant;
+    try {
+        instant = Temporal.Instant.from(value);
+        startInstant = Temporal.Instant.from(start);
+        endInstant = Temporal.Instant.from(end);
+    }
+    catch {
+        return false;
+    }
+    try {
+        if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
+            return false;
+        }
+        const startCheck = inclusiveStart
+            ? Temporal.Instant.compare(startInstant, instant) <= 0
+            : Temporal.Instant.compare(startInstant, instant) < 0;
+        const endCheck = inclusiveEnd
+            ? Temporal.Instant.compare(instant, endInstant) <= 0
+            : Temporal.Instant.compare(instant, endInstant) < 0;
+        return startCheck && endCheck;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utc/calculate/maxUtc.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return the latest (maximum) of the given UTC datetime values.
+ *
+ * - Filters invalid values before finding maximum.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param utcDateTimes Array of ISO datetime strings (e.g. "2024-03-10T12:00:00Z")
+ * @returns The latest UTC datetime string, or null on invalid input
+ *
+ * @example maxUtc(["2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z", "2024-03-12T12:00:00Z"]) // "2024-03-15T12:00:00Z"
+ * @example maxUtc(["invalid", "2024-03-15T12:00:00Z"]) // "2024-03-15T12:00:00Z"
+ * @example maxUtc(["invalid", "also invalid"]) // null
+ * @example maxUtc([]) // null
+ */
+export declare function maxUtc(utcDateTimes: string[]): string | null;

package/dist/utc/calculate/maxUtc.js

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Return the latest (maximum) of the given UTC datetime values.
+ *
+ * - Filters invalid values before finding maximum.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param utcDateTimes Array of ISO datetime strings (e.g. "2024-03-10T12:00:00Z")
+ * @returns The latest UTC datetime string, or null on invalid input
+ *
+ * @example maxUtc(["2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z", "2024-03-12T12:00:00Z"]) // "2024-03-15T12:00:00Z"
+ * @example maxUtc(["invalid", "2024-03-15T12:00:00Z"]) // "2024-03-15T12:00:00Z"
+ * @example maxUtc(["invalid", "also invalid"]) // null
+ * @example maxUtc([]) // null
+ */
+export function maxUtc(utcDateTimes) {
+    if (!utcDateTimes.length)
+        return null;
+    const valid = utcDateTimes.filter(isValidUtc);
+    if (!valid.length)
+        return null;
+    try {
+        const max = valid.reduce((currentMax, candidateStr) => {
+            const candidate = Temporal.Instant.from(candidateStr);
+            return Temporal.Instant.compare(candidate, currentMax) > 0
+                ? candidate
+                : currentMax;
+        }, Temporal.Instant.from(valid[0]));
+        return max.toString();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utc/calculate/minUtc.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return the earliest (minimum) of the given UTC datetime values.
+ *
+ * - Filters invalid values before finding minimum using Temporal.Instant.compare.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param utcDateTimes Array of ISO datetime strings (e.g. "2024-03-10T12:00:00Z")
+ * @returns The earliest UTC datetime string, or null on invalid input
+ *
+ * @example minUtc(["2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z", "2024-03-12T12:00:00Z"]) // "2024-03-10T12:00:00Z"
+ * @example minUtc(["invalid", "2024-03-15T12:00:00Z"]) // "2024-03-15T12:00:00Z"
+ * @example minUtc(["invalid", "also invalid"]) // null
+ * @example minUtc([]) // null
+ */
+export declare function minUtc(utcDateTimes: string[]): string | null;

package/dist/utc/calculate/minUtc.js

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Return the earliest (minimum) of the given UTC datetime values.
+ *
+ * - Filters invalid values before finding minimum using Temporal.Instant.compare.
+ * - Returns null if array is empty or has no valid values.
+ *
+ * @param utcDateTimes Array of ISO datetime strings (e.g. "2024-03-10T12:00:00Z")
+ * @returns The earliest UTC datetime string, or null on invalid input
+ *
+ * @example minUtc(["2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z", "2024-03-12T12:00:00Z"]) // "2024-03-10T12:00:00Z"
+ * @example minUtc(["invalid", "2024-03-15T12:00:00Z"]) // "2024-03-15T12:00:00Z"
+ * @example minUtc(["invalid", "also invalid"]) // null
+ * @example minUtc([]) // null
+ */
+export function minUtc(utcDateTimes) {
+    if (!utcDateTimes.length)
+        return null;
+    const valid = utcDateTimes.filter(isValidUtc);
+    if (!valid.length)
+        return null;
+    try {
+        const min = valid.reduce((currentMin, candidateStr) => {
+            const candidate = Temporal.Instant.from(candidateStr);
+            return Temporal.Instant.compare(candidate, currentMin) < 0
+                ? candidate
+                : currentMin;
+        }, Temporal.Instant.from(valid[0]));
+        return min.toString();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utc/calculate/roundUtc.d.ts

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+/**
+ * Round a UTC datetime string to the specified unit.
+ *
+ * - Converts to Instant, rounds, converts back to UTC Instant string.
+ * - Supports: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Date units ("year", "month", "week", "day") are not supported by the Temporal polyfill's Instant.round() — they return "".
+ * - Wraps all Temporal calls in try-catch; returns "" on any error.
+ *
+ * @param value ISO UTC datetime string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, fractionalSecondDigits
+ * @returns Rounded ISO UTC Instant string, or "" on invalid input
+ *
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "second", roundingMode: "floor" }) // "2024-06-15T12:34:56Z"
+ * @example roundUtc("invalid", { smallestUnit: "hour" }) // ""
+ * @example roundUtc("", { smallestUnit: "hour" }) // ""
+ */
+export declare function roundUtc(value: string, options: {
+    smallestUnit: Temporal.SmallestUnit<"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/utc/calculate/roundUtc.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeUnit } from "../../plain/index.js";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Round a UTC datetime string to the specified unit.
+ *
+ * - Converts to Instant, rounds, converts back to UTC Instant string.
+ * - Supports: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Date units ("year", "month", "week", "day") are not supported by the Temporal polyfill's Instant.round() — they return "".
+ * - Wraps all Temporal calls in try-catch; returns "" on any error.
+ *
+ * @param value ISO UTC datetime string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, fractionalSecondDigits
+ * @returns Rounded ISO UTC Instant string, or "" on invalid input
+ *
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00Z"
+ * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "second", roundingMode: "floor" }) // "2024-06-15T12:34:56Z"
+ * @example roundUtc("invalid", { smallestUnit: "hour" }) // ""
+ * @example roundUtc("", { smallestUnit: "hour" }) // ""
+ */
+export function roundUtc(value, options) {
+    const { smallestUnit, roundingIncrement, roundingMode, fractionalSecondDigits, } = options;
+    if (!isValidUtc(value) || !isValidDateTimeUnit(smallestUnit))
+        return "";
+    // Polyfill limitation: day/year/month/week not supported for Instant.round()
+    const supportedUnits = [
+        "hour",
+        "minute",
+        "second",
+        "millisecond",
+        "microsecond",
+        "nanosecond",
+    ];
+    if (!supportedUnits.includes(smallestUnit))
+        return "";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const result = instant.round({
+            smallestUnit,
+            roundingIncrement,
+            roundingMode,
+        });
+        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
+        const precisionMap = {
+            millisecond: 3,
+            microsecond: 6,
+            nanosecond: 9,
+        };
+        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[smallestUnit] || 0);
+        return result.toString({ fractionalSecondDigits: fractionalDigits });
+    }
+    catch {
+        return "";
+    }
+}

package/dist/utc/calculate/setUtc.d.ts

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
+/**
+ * Return a UTC Instant string with the given `fields` set on `value`.
+ *
+ * - Converts to ZonedDateTime (fixed timeZone "UTC"), wraps
+ *   `Temporal.ZonedDateTime.prototype.with()` (resolving every supplied field in a single atomic
+ *   overflow pass), then converts back to an Instant. This is the safe alternative to composing
+ *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
+ *   resolution matters.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ *   (resulting in "").
+ * - `disambiguation` and `offset` are accepted for API consistency with `setZoned`/`setUnix`,
+ *   but are **permanently inert** here: "UTC" has no DST transitions, so there is never an
+ *   ambiguous local time or a stale offset for either option to act on (same precedent as
+ *   `startOfUtc`/`endOfUtc`, Story C1/C2). Do not "fix" this by removing them.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
+ * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject"), disambiguation (accepted but inert, see above), offset (accepted but inert, see above)
+ * @returns UTC Instant string with fields set, or "" on invalid input
+ *
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"
+ * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
+ * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("invalid", { hour: 9 }) // ""
+ */
+export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+    overflow?: Overflow;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/utc/calculate/setUtc.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Return a UTC Instant string with the given `fields` set on `value`.
+ *
+ * - Converts to ZonedDateTime (fixed timeZone "UTC"), wraps
+ *   `Temporal.ZonedDateTime.prototype.with()` (resolving every supplied field in a single atomic
+ *   overflow pass), then converts back to an Instant. This is the safe alternative to composing
+ *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
+ *   resolution matters.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ *   (resulting in "").
+ * - `disambiguation` and `offset` are accepted for API consistency with `setZoned`/`setUnix`,
+ *   but are **permanently inert** here: "UTC" has no DST transitions, so there is never an
+ *   ambiguous local time or a stale offset for either option to act on (same precedent as
+ *   `startOfUtc`/`endOfUtc`, Story C1/C2). Do not "fix" this by removing them.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
+ * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject"), disambiguation (accepted but inert, see above), offset (accepted but inert, see above)
+ * @returns UTC Instant string with fields set, or "" on invalid input
+ *
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"
+ * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
+ * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("invalid", { hour: 9 }) // ""
+ */
+export function setUtc(value, fields, options) {
+    if (!isValidUtc(value))
+        return "";
+    const overflow = resolveOverflow(options?.overflow);
+    const disambiguation = options?.disambiguation ?? "compatible";
+    const offset = options?.offset ?? "ignore";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const zoned = instant.toZonedDateTimeISO("UTC");
+        // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
+        // properties found") rather than treating it as a no-op, so short-circuit here.
+        const result = Object.keys(fields).length === 0
+            ? zoned
+            : zoned.with(fields, { overflow, disambiguation, offset });
+        return result.toInstant().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/utc/calculate/sortUtc.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Sort an array of UTC datetime values in ascending or descending order.
+ *
+ * - Filters invalid values before sorting.
+ * - Supports "asc" (earliest first) or "desc" (latest first).
+ * - Returns [] if array is empty or has no valid values.
+ *
+ * @param utcDateTimes Array of ISO datetime strings (e.g. "2024-03-10T12:00:00Z")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of UTC datetime strings
+ *
+ * @example sortUtc(["2024-03-12T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z"]) // ["2024-03-10T12:00:00Z", "2024-03-12T12:00:00Z", "2024-03-15T12:00:00Z"]
+ * @example sortUtc(["2024-03-12T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z"], "desc") // ["2024-03-15T12:00:00Z", "2024-03-12T12:00:00Z", "2024-03-10T12:00:00Z"]
+ * @example sortUtc(["invalid", "2024-03-10T12:00:00Z", "also invalid"]) // ["2024-03-10T12:00:00Z"]
+ * @example sortUtc([]) // []
+ */
+export declare function sortUtc(utcDateTimes: string[], order?: "asc" | "desc"): string[];

package/dist/utc/calculate/sortUtc.js

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Sort an array of UTC datetime values in ascending or descending order.
+ *
+ * - Filters invalid values before sorting.
+ * - Supports "asc" (earliest first) or "desc" (latest first).
+ * - Returns [] if array is empty or has no valid values.
+ *
+ * @param utcDateTimes Array of ISO datetime strings (e.g. "2024-03-10T12:00:00Z")
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of UTC datetime strings
+ *
+ * @example sortUtc(["2024-03-12T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z"]) // ["2024-03-10T12:00:00Z", "2024-03-12T12:00:00Z", "2024-03-15T12:00:00Z"]
+ * @example sortUtc(["2024-03-12T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-15T12:00:00Z"], "desc") // ["2024-03-15T12:00:00Z", "2024-03-12T12:00:00Z", "2024-03-10T12:00:00Z"]
+ * @example sortUtc(["invalid", "2024-03-10T12:00:00Z", "also invalid"]) // ["2024-03-10T12:00:00Z"]
+ * @example sortUtc([]) // []
+ */
+export function sortUtc(utcDateTimes, order = "asc") {
+    if (!utcDateTimes.length)
+        return [];
+    const valid = utcDateTimes.filter(isValidUtc);
+    if (!valid.length)
+        return [];
+    try {
+        const comparables = valid.map((d) => Temporal.Instant.from(d));
+        comparables.sort(Temporal.Instant.compare);
+        if (order === "desc") {
+            return comparables.reverse().map((d) => d.toString());
+        }
+        return comparables.map((d) => d.toString());
+    }
+    catch {
+        return [];
+    }
+}

package/dist/utc/calculate/startOfQuarterForUtc.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Return the start of the quarter for a given UTC datetime string.
+ *
+ * - Calculates quarter start month: Q1=1, Q2=4, Q3=7, Q4=10.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g. "2024-03-15T12:00:00Z")
+ * @returns ISO UTC datetime string representing the start of the quarter, or "" on invalid input
+ *
+ * @example startOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-01-01T00:00:00Z"
+ * @example startOfQuarterForUtc("invalid") // ""
+ */
+export declare function startOfQuarterForUtc(value: string): string;

package/dist/utc/calculate/startOfQuarterForUtc.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return the start of the quarter for a given UTC datetime string.
+ *
+ * - Calculates quarter start month: Q1=1, Q2=4, Q3=7, Q4=10.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g. "2024-03-15T12:00:00Z")
+ * @returns ISO UTC datetime string representing the start of the quarter, or "" on invalid input
+ *
+ * @example startOfQuarterForUtc("2024-03-15T12:00:00Z") // "2024-01-01T00:00:00Z"
+ * @example startOfQuarterForUtc("invalid") // ""
+ */
+export function startOfQuarterForUtc(value) {
+    if (!isValidUtc(value)) {
+        return "";
+    }
+    try {
+        const instant = Temporal.Instant.from(value);
+        const zdt = instant.toZonedDateTimeISO("UTC");
+        const month = zdt.month;
+        const quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
+        const result = zdt
+            .with({ month: quarterStartMonth, day: 1, hour: 0, minute: 0, second: 0 })
+            .toInstant();
+        return result.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/utc/calculate/startOfUtc.d.ts

@@ -0,0 +1,22 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+/**
+ * Return the start of the specified date-time `unit` for a given UTC datetime string.
+ *
+ * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the start
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns UTC Instant string representing the start of the unit, or "" on invalid input
+ *
+ * @example startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"
+ * @example startOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-01T00:00:00Z"
+ * @example startOfUtc("invalid", "year") // ""
+ */
+export declare function startOfUtc(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/utc/calculate/startOfUtc.js

@@ -0,0 +1,21 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { startOrEndOfUtc } from "./startOrEndOfUtc.js";
+/**
+ * Return the start of the specified date-time `unit` for a given UTC datetime string.
+ *
+ * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the start
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns UTC Instant string representing the start of the unit, or "" on invalid input
+ *
+ * @example startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"
+ * @example startOfUtc("2024-03-15T14:30:45Z", "month") // "2024-03-01T00:00:00Z"
+ * @example startOfUtc("invalid", "year") // ""
+ */
+export function startOfUtc(value, unit, options) {
+    return startOrEndOfUtc(value, unit, options ?? {}, false);
+}

package/dist/utc/calculate/startOrEndOfUtc.d.ts

@@ -0,0 +1,6 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+export declare function startOrEndOfUtc(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, options: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}, isEnd: boolean): string;