@northguild/gmt 1.14.2

package/dist/unix/parse/parseUnitFromUnix.js

@@ -0,0 +1,77 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { convertUnixToZoned } from "../convert/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+/**
+ * Extract a unit from a unix epoch value.
+ *
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Converts to ZonedDateTime then extracts the unit.
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param unit unit to extract (e.g. "year", "month", "hour")
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @returns extracted unit value as string, or "" on invalid input
+ *
+ * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds" }) // "12"
+ * @example parseUnitFromUnix(1704067200000, "week") // "1"
+ * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday" }) // "1"
+ * @example parseUnitFromUnix(-86400, { epochUnit: "seconds" }, "year") // "1969"
+ */
+export function parseUnitFromUnix(value, unit, options) {
+    const numValue = typeof value === "string" ? Number(value) : value;
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (epochUnit === "seconds") {
+        if (!isValidUnixSeconds(numValue))
+            return "";
+    }
+    else {
+        if (!isValidUnixMilliseconds(numValue))
+            return "";
+    }
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    if (!timeZone)
+        return "";
+    const zoned = typeof options?.epochUnit === "undefined"
+        ? convertUnixToZoned(numValue, timeZone)
+        : convertUnixToZoned(numValue, timeZone, options.epochUnit);
+    if (!zoned)
+        return "";
+    const weekStartsOn = options?.weekStartsOn ?? "monday";
+    try {
+        const zdt = Temporal.ZonedDateTime.from(zoned);
+        switch (unit) {
+            case "year":
+                return zdt.year.toString();
+            case "month":
+                return zdt.month.toString().padStart(2, "0");
+            case "week": {
+                return (getWeekNumber(`${zdt.year}-${zdt.month.toString().padStart(2, "0")}-${zdt.day.toString().padStart(2, "0")}`, weekStartsOn) ?? 0).toString();
+            }
+            case "day":
+                return zdt.day.toString().padStart(2, "0");
+            case "dayOfWeek":
+                return zdt.dayOfWeek.toString();
+            case "hour":
+                return zdt.hour.toString().padStart(2, "0");
+            case "minute":
+                return zdt.minute.toString().padStart(2, "0");
+            case "second":
+                return zdt.second.toString().padStart(2, "0");
+            case "millisecond":
+                return zdt.millisecond.toString().padStart(3, "0");
+            case "microsecond":
+                return (zdt.microsecond ?? 0).toString().padStart(3, "0");
+            case "nanosecond":
+                return (zdt.nanosecond ?? 0).toString().padStart(9, "0");
+            default:
+                return "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

package/dist/unix/parse/parseWeekFromUnix.d.ts

@@ -0,0 +1,20 @@
+import { type UnixUnit } from "../validate/index.js";
+/**
+ * Return the week number from a unix epoch value.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromUnix(1704067200000) // 1
+ * @example parseWeekFromUnix(1704067200000, { weekStartsOn: "sunday" }) // 1
+ * @example parseWeekFromUnix(-86400, { epochUnit: "seconds" }) // 1
+ */
+export declare function parseWeekFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+    weekStartsOn?: "monday" | "sunday";
+}): number | null;

package/dist/unix/parse/parseWeekFromUnix.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
+import { getSystemTimeZone } from "../../zoned/get/index.js";
+import { convertUnixToZoned } from "../convert/index.js";
+import { isValidUnixMilliseconds, isValidUnixSeconds, } from "../validate/index.js";
+/**
+ * Return the week number from a unix epoch value.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromUnix(1704067200000) // 1
+ * @example parseWeekFromUnix(1704067200000, { weekStartsOn: "sunday" }) // 1
+ * @example parseWeekFromUnix(-86400, { epochUnit: "seconds" }) // 1
+ */
+export function parseWeekFromUnix(value, options) {
+    const numValue = typeof value === "string" ? Number(value) : value;
+    const epochUnit = options?.epochUnit ?? "milliseconds";
+    if (epochUnit === "seconds") {
+        if (!isValidUnixSeconds(numValue))
+            return null;
+    }
+    else {
+        if (!isValidUnixMilliseconds(numValue))
+            return null;
+    }
+    const timeZone = options?.timeZone ?? getSystemTimeZone();
+    if (!timeZone)
+        return null;
+    const zoned = typeof options?.epochUnit === "undefined"
+        ? convertUnixToZoned(numValue, timeZone)
+        : convertUnixToZoned(numValue, timeZone, options.epochUnit);
+    if (!zoned)
+        return null;
+    const weekStartsOn = options?.weekStartsOn ?? "monday";
+    try {
+        const zdt = Temporal.ZonedDateTime.from(zoned);
+        return getWeekNumber(`${zdt.year}-${zdt.month.toString().padStart(2, "0")}-${zdt.day.toString().padStart(2, "0")}`, weekStartsOn);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/unix/parse/parseYearFromUnix.d.ts

@@ -0,0 +1,19 @@
+import type { UnixUnit } from "../validate/index.js";
+/**
+ * Return the year from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "year".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Year (YYYY) or "" on invalid input
+ *
+ * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds" }) // "2024"
+ * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
+ */
+export declare function parseYearFromUnix(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): string;

package/dist/unix/parse/parseYearFromUnix.js

@@ -0,0 +1,18 @@
+import { parseUnitFromUnix } from "./parseUnitFromUnix.js";
+/**
+ * Return the year from a unix epoch value.
+ *
+ * - Delegates to {@link parseUnitFromUnix} with unit "year".
+ * - Returns "" for invalid input.
+ *
+ * @param value unix epoch in milliseconds or seconds (number or string)
+ * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @returns Year (YYYY) or "" on invalid input
+ *
+ * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds" }) // "2024"
+ * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
+ */
+export function parseYearFromUnix(value, options) {
+    return parseUnitFromUnix(value, "year", options);
+}

package/dist/unix/validate/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./isValidUnixMilliseconds.js";
+export * from "./isValidUnixRange.js";
+export * from "./isValidUnixSeconds.js";
+export * from "./isValidUnixUnit.js";

package/dist/unix/validate/index.js

@@ -0,0 +1,4 @@
+export * from "./isValidUnixMilliseconds.js";
+export * from "./isValidUnixRange.js";
+export * from "./isValidUnixSeconds.js";
+export * from "./isValidUnixUnit.js";

package/dist/unix/validate/isValidUnixMilliseconds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return true when `timestamp` is a valid Unix milliseconds value.
+ *
+ * - Must be an integer (positive or negative, for dates before/after 1970).
+ * - Returns false for non-numbers or non-integers.
+ *
+ * @param timestamp number candidate
+ * @returns boolean indicating whether the timestamp is a valid Unix milliseconds value
+ *
+ * @example isValidUnixMilliseconds(1700000000000) // true
+ * @example isValidUnixMilliseconds(-86400000) // true (1969-12-31)
+ * @example isValidUnixMilliseconds(1.5) // false
+ */
+export declare function isValidUnixMilliseconds(timestamp: unknown): boolean;

package/dist/unix/validate/isValidUnixMilliseconds.js

@@ -0,0 +1,19 @@
+/**
+ * Return true when `timestamp` is a valid Unix milliseconds value.
+ *
+ * - Must be an integer (positive or negative, for dates before/after 1970).
+ * - Returns false for non-numbers or non-integers.
+ *
+ * @param timestamp number candidate
+ * @returns boolean indicating whether the timestamp is a valid Unix milliseconds value
+ *
+ * @example isValidUnixMilliseconds(1700000000000) // true
+ * @example isValidUnixMilliseconds(-86400000) // true (1969-12-31)
+ * @example isValidUnixMilliseconds(1.5) // false
+ */
+export function isValidUnixMilliseconds(timestamp) {
+    if (typeof timestamp === "number") {
+        return Number.isInteger(timestamp);
+    }
+    return false;
+}

package/dist/unix/validate/isValidUnixRange.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Return true if `value1` and `value2` form a valid Unix range — both finite numbers
+ * and `value1 <= value2`.
+ *
+ * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
+ * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
+ * - Non-finite values (NaN, Infinity) return `false`.
+ *
+ * @param value1 first Unix epoch value (seconds or milliseconds)
+ * @param value2 second Unix epoch value (seconds or milliseconds)
+ * @param options optional allowEqual flag
+ * @returns boolean indicating whether the Unix range is valid
+ *
+ * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true
+ * @example isValidUnixRange({ value1: 1700000000, value2: 0 }) // false
+ * @example isValidUnixRange({ value1: 1000, value2: 1000, options: { allowEqual: true } }) // true
+ */
+export declare function isValidUnixRange({ value1, value2, options, }: {
+    value1: number | string;
+    value2: number | string;
+    options?: {
+        allowEqual?: boolean;
+    };
+}): boolean;

package/dist/unix/validate/isValidUnixRange.js

@@ -0,0 +1,34 @@
+/**
+ * Return true if `value1` and `value2` form a valid Unix range — both finite numbers
+ * and `value1 <= value2`.
+ *
+ * - Both inputs must be numbers (or numeric strings that coerce to finite numbers).
+ * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
+ * - Non-finite values (NaN, Infinity) return `false`.
+ *
+ * @param value1 first Unix epoch value (seconds or milliseconds)
+ * @param value2 second Unix epoch value (seconds or milliseconds)
+ * @param options optional allowEqual flag
+ * @returns boolean indicating whether the Unix range is valid
+ *
+ * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true
+ * @example isValidUnixRange({ value1: 1700000000, value2: 0 }) // false
+ * @example isValidUnixRange({ value1: 1000, value2: 1000, options: { allowEqual: true } }) // true
+ */
+export function isValidUnixRange({ value1, value2, options, }) {
+    if (typeof value1 !== "number" && typeof value1 !== "string") {
+        return false;
+    }
+    if (typeof value2 !== "number" && typeof value2 !== "string") {
+        return false;
+    }
+    const n1 = typeof value1 === "number" ? value1 : Number(value1);
+    const n2 = typeof value2 === "number" ? value2 : Number(value2);
+    if (!Number.isFinite(n1) || !Number.isFinite(n2)) {
+        return false;
+    }
+    if (options?.allowEqual) {
+        return n1 <= n2;
+    }
+    return n1 < n2;
+}

package/dist/unix/validate/isValidUnixSeconds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return true when `timestamp` is a valid Unix seconds value.
+ *
+ * - Must be an integer (positive or negative, for dates before/after 1970).
+ * - Returns false for non-numbers or non-integers.
+ *
+ * @param timestamp number candidate
+ * @returns boolean indicating whether the timestamp is a valid Unix seconds value
+ *
+ * @example isValidUnixSeconds(1700000000) // true
+ * @example isValidUnixSeconds(-86400) // true (1969-12-31)
+ * @example isValidUnixSeconds(1.5) // false
+ */
+export declare function isValidUnixSeconds(timestamp: unknown): boolean;

package/dist/unix/validate/isValidUnixSeconds.js

@@ -0,0 +1,19 @@
+/**
+ * Return true when `timestamp` is a valid Unix seconds value.
+ *
+ * - Must be an integer (positive or negative, for dates before/after 1970).
+ * - Returns false for non-numbers or non-integers.
+ *
+ * @param timestamp number candidate
+ * @returns boolean indicating whether the timestamp is a valid Unix seconds value
+ *
+ * @example isValidUnixSeconds(1700000000) // true
+ * @example isValidUnixSeconds(-86400) // true (1969-12-31)
+ * @example isValidUnixSeconds(1.5) // false
+ */
+export function isValidUnixSeconds(timestamp) {
+    if (typeof timestamp === "number") {
+        return Number.isInteger(timestamp);
+    }
+    return false;
+}

package/dist/unix/validate/isValidUnixUnit.d.ts

@@ -0,0 +1,18 @@
+export type UnixUnit = "seconds" | "milliseconds";
+/**
+ * Return true when `unit` is a valid UnixUnit.
+ *
+ * - Valid units are: "seconds", "milliseconds".
+ * - Accepts any input type and returns false for non-string values.
+ * - Uses type assertion to narrow the type.
+ *
+ * @param unit candidate value of any type
+ * @returns boolean indicating whether the unit is a valid UnixUnit
+ *
+ * @example isValidUnixUnit("seconds") // true
+ * @example isValidUnixUnit("milliseconds") // true
+ * @example isValidUnixUnit("invalid") // false
+ * @example isValidUnixUnit(123) // false
+ * @example isValidUnixUnit(null) // false
+ */
+export declare function isValidUnixUnit(unit: unknown): unit is UnixUnit;

package/dist/unix/validate/isValidUnixUnit.js

@@ -0,0 +1,22 @@
+/**
+ * Return true when `unit` is a valid UnixUnit.
+ *
+ * - Valid units are: "seconds", "milliseconds".
+ * - Accepts any input type and returns false for non-string values.
+ * - Uses type assertion to narrow the type.
+ *
+ * @param unit candidate value of any type
+ * @returns boolean indicating whether the unit is a valid UnixUnit
+ *
+ * @example isValidUnixUnit("seconds") // true
+ * @example isValidUnixUnit("milliseconds") // true
+ * @example isValidUnixUnit("invalid") // false
+ * @example isValidUnixUnit(123) // false
+ * @example isValidUnixUnit(null) // false
+ */
+export function isValidUnixUnit(unit) {
+    if (typeof unit !== "string") {
+        return false;
+    }
+    return unit === "seconds" || unit === "milliseconds";
+}

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

@@ -0,0 +1,23 @@
+import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Add a temporal amount to a UTC datetime string and return a new UTC Instant string.
+ *
+ * - Uses Temporal.Instant.from to parse, adds duration, returns new Instant.
+ * - Validates duration units and values.
+ * - Returns "" for invalid input.
+ *
+ * `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 UTC datetime string (e.g. "2024-03-10T12:00:00Z")
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns UTC Instant string after addition, or "" on invalid input
+ *
+ * @example addUtc("2024-03-10T12:00:00Z", { days: 5 }) // "2024-03-15T12:00:00Z"
+ * @example addUtc("2024-03-10T12:00:00Z", { months: 1, years: 1 }) // "2025-04-10T12:00:00Z"
+ * @example addUtc("invalid", { days: 5 }) // ""
+ */
+export declare function addUtc(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/utc/calculate/addUtc.js

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Add a temporal amount to a UTC datetime string and return a new UTC Instant string.
+ *
+ * - Uses Temporal.Instant.from to parse, adds duration, returns new Instant.
+ * - Validates duration units and values.
+ * - Returns "" for invalid input.
+ *
+ * `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 UTC datetime string (e.g. "2024-03-10T12:00:00Z")
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns UTC Instant string after addition, or "" on invalid input
+ *
+ * @example addUtc("2024-03-10T12:00:00Z", { days: 5 }) // "2024-03-15T12:00:00Z"
+ * @example addUtc("2024-03-10T12:00:00Z", { months: 1, years: 1 }) // "2025-04-10T12:00:00Z"
+ * @example addUtc("invalid", { days: 5 }) // ""
+ */
+export function addUtc(value, units, options) {
+    const validUtc = isValidUtc(value);
+    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validUtc || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const instant = Temporal.Instant.from(value);
+        const zoned = instant.toZonedDateTimeISO("UTC");
+        const result = zoned.add(units, {
+            overflow: resolveOverflow(options?.overflow),
+        });
+        return result.toInstant().toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,27 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js";
+/**
+ * Return the difference between two UTC datetimes measured in the given date-time unit.
+ *
+ * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Supports single unit or array of units.
+ * - Returns null for invalid input.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest hour before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @param value1 UTC ISO datetime string (start)
+ * @param value2 UTC ISO datetime string (end)
+ * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hour") // 24
+ * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["year", "month"]) // { year: 1, month: 1 }
+ * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hour") // null
+ */
+export declare function diffUtc(value1: string, value2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/utc/calculate/diffUtc.js

@@ -0,0 +1,61 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Return the difference between two UTC datetimes measured in the given date-time unit.
+ *
+ * - Uses Temporal.Instant.until() to calculate the difference.
+ * - Supports single unit or array of units.
+ * - Returns null for invalid input.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest hour before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @param value1 UTC ISO datetime string (start)
+ * @param value2 UTC ISO datetime string (end)
+ * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hour") // 24
+ * @example diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["year", "month"]) // { year: 1, month: 1 }
+ * @example diffUtc("invalid", "2024-03-11T12:00:00Z", "hour") // null
+ */
+export function diffUtc(value1, value2, units, options) {
+    const validUtc1 = isValidUtc(value1);
+    const validUtc2 = isValidUtc(value2);
+    const isSingleUnit = !Array.isArray(units);
+    const validUnits = isSingleUnit
+        ? isValidDateTimeDurationUnit(units)
+        : units.every(isValidDateTimeDurationUnit);
+    if (!validUtc1 || !validUtc2 || !validUnits) {
+        return null;
+    }
+    try {
+        const instant1 = Temporal.Instant.from(value1);
+        const instant2 = Temporal.Instant.from(value2);
+        const zdt1 = instant1.toZonedDateTimeISO("UTC");
+        const zdt2 = instant2.toZonedDateTimeISO("UTC");
+        const duration = zdt1.until(zdt2, {
+            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
+            smallestUnit: options?.smallestUnit,
+            roundingIncrement: options?.roundingIncrement,
+            roundingMode: options?.roundingMode,
+        });
+        if (isSingleUnit) {
+            return duration[units] ?? 0;
+        }
+        return units.reduce((result, unit) => {
+            result[unit] = duration[unit] ?? 0;
+            return result;
+        }, {});
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.js";
+/**
+ * Return the difference between two UTC datetimes as an ISO 8601 duration string,
+ * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
+ *
+ * - Uses Temporal.Instant.until() with `largestUnit` set to `unit`, then `.toString()`.
+ * - Unlike `diffUtc`, `unit` is a single unit (not an array) — an ISO duration string
+ *   already expresses a full multi-unit breakdown via `largestUnit` alone, so there's no
+ *   array-of-units overload here.
+ * - Returns `""` for invalid input (negative diffs are valid and render with a leading `-`).
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffUtc`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @param value1 UTC ISO datetime string (start)
+ * @param value2 UTC ISO datetime string (end)
+ * @param unit DateTimeDurationUnit to use as the duration's largestUnit
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffUtcAsDuration("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // "PT24H"
+ * @example diffUtcAsDuration("2024-03-11T12:00:00Z", "2024-03-10T12:00:00Z", "hours") // "-PT24H"
+ * @example diffUtcAsDuration("invalid", "2024-03-11T12:00:00Z", "hours") // ""
+ */
+export declare function diffUtcAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/utc/calculate/diffUtcAsDuration.js

@@ -0,0 +1,50 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { durationUntilString } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Return the difference between two UTC datetimes as an ISO 8601 duration string,
+ * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
+ *
+ * - Uses Temporal.Instant.until() with `largestUnit` set to `unit`, then `.toString()`.
+ * - Unlike `diffUtc`, `unit` is a single unit (not an array) — an ISO duration string
+ *   already expresses a full multi-unit breakdown via `largestUnit` alone, so there's no
+ *   array-of-units overload here.
+ * - Returns `""` for invalid input (negative diffs are valid and render with a leading `-`).
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffUtc`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @param value1 UTC ISO datetime string (start)
+ * @param value2 UTC ISO datetime string (end)
+ * @param unit DateTimeDurationUnit to use as the duration's largestUnit
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffUtcAsDuration("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // "PT24H"
+ * @example diffUtcAsDuration("2024-03-11T12:00:00Z", "2024-03-10T12:00:00Z", "hours") // "-PT24H"
+ * @example diffUtcAsDuration("invalid", "2024-03-11T12:00:00Z", "hours") // ""
+ */
+export function diffUtcAsDuration(value1, value2, unit, options) {
+    const validUtc1 = isValidUtc(value1);
+    const validUtc2 = isValidUtc(value2);
+    const validUnit = isValidDateTimeDurationUnit(unit);
+    if (!validUtc1 || !validUtc2 || !validUnit) {
+        return "";
+    }
+    try {
+        const instant1 = Temporal.Instant.from(value1);
+        const instant2 = Temporal.Instant.from(value2);
+        const zdt1 = instant1.toZonedDateTimeISO("UTC");
+        const zdt2 = instant2.toZonedDateTimeISO("UTC");
+        return durationUntilString(zdt1, zdt2, unit, options);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function endOfQuarterForUtc(value: string): string;