@northguild/gmt 1.14.2

package/dist/duration/calculate/absDuration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Return the absolute value of an ISO 8601 duration string.
+ *
+ * - Uses Temporal.Duration.from and .abs, then .toString() to re-emit.
+ * - Like `negateDuration`, this only touches signs, so it never needs `relativeTo` and works
+ *   on calendar-unit durations.
+ * - An already-positive duration is returned re-emitted, not rejected — but re-emitted means
+ *   canonicalized, so "P0D" comes back as "PT0S".
+ * - Returns "" when `value` is not a valid ISO 8601 duration string.
+ *
+ * @param value ISO 8601 duration string
+ * @returns ISO 8601 duration string with a positive sign, or "" on invalid input
+ *
+ * @example absDuration("-P1DT2H") // "P1DT2H"
+ * @example absDuration("P1DT2H") // "P1DT2H"
+ * @example absDuration("-P1Y2M") // "P1Y2M" (no relativeTo needed)
+ * @example absDuration("PT0S") // "PT0S"
+ * @example absDuration("not a duration") // ""
+ */
+export declare function absDuration(value: string): string;

package/dist/duration/calculate/absDuration.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Return the absolute value of an ISO 8601 duration string.
+ *
+ * - Uses Temporal.Duration.from and .abs, then .toString() to re-emit.
+ * - Like `negateDuration`, this only touches signs, so it never needs `relativeTo` and works
+ *   on calendar-unit durations.
+ * - An already-positive duration is returned re-emitted, not rejected — but re-emitted means
+ *   canonicalized, so "P0D" comes back as "PT0S".
+ * - Returns "" when `value` is not a valid ISO 8601 duration string.
+ *
+ * @param value ISO 8601 duration string
+ * @returns ISO 8601 duration string with a positive sign, or "" on invalid input
+ *
+ * @example absDuration("-P1DT2H") // "P1DT2H"
+ * @example absDuration("P1DT2H") // "P1DT2H"
+ * @example absDuration("-P1Y2M") // "P1Y2M" (no relativeTo needed)
+ * @example absDuration("PT0S") // "PT0S"
+ * @example absDuration("not a duration") // ""
+ */
+export function absDuration(value) {
+    if (!isValidDuration(value)) {
+        return "";
+    }
+    try {
+        return Temporal.Duration.from(value).abs().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/duration/calculate/addDuration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Combine two ISO 8601 duration strings by addition.
+ *
+ * - Uses Temporal.Duration.from and .add to combine, then .toString() to re-emit.
+ * - Temporal.Duration.prototype.add has no `relativeTo` option, so combining any pair
+ *   where either operand has a nonzero years/months/weeks component throws and
+ *   results in "" — calendar-unit duration arithmetic needs a reference point that
+ *   this function does not accept.
+ * - Returns "" if either operand is not a valid ISO 8601 duration string.
+ *
+ * @param a ISO 8601 duration string
+ * @param b ISO 8601 duration string
+ * @returns ISO 8601 duration string representing a + b, or "" on invalid input
+ *
+ * @example addDuration("P1D", "PT2H") // "P1DT2H"
+ * @example addDuration("PT1H", "-PT2H") // "-PT1H"
+ * @example addDuration("P1Y", "P1M") // "" (calendar units need relativeTo, unsupported)
+ * @example addDuration("P1D", "not a duration") // ""
+ */
+export declare function addDuration(a: string, b: string): string;

package/dist/duration/calculate/addDuration.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Combine two ISO 8601 duration strings by addition.
+ *
+ * - Uses Temporal.Duration.from and .add to combine, then .toString() to re-emit.
+ * - Temporal.Duration.prototype.add has no `relativeTo` option, so combining any pair
+ *   where either operand has a nonzero years/months/weeks component throws and
+ *   results in "" — calendar-unit duration arithmetic needs a reference point that
+ *   this function does not accept.
+ * - Returns "" if either operand is not a valid ISO 8601 duration string.
+ *
+ * @param a ISO 8601 duration string
+ * @param b ISO 8601 duration string
+ * @returns ISO 8601 duration string representing a + b, or "" on invalid input
+ *
+ * @example addDuration("P1D", "PT2H") // "P1DT2H"
+ * @example addDuration("PT1H", "-PT2H") // "-PT1H"
+ * @example addDuration("P1Y", "P1M") // "" (calendar units need relativeTo, unsupported)
+ * @example addDuration("P1D", "not a duration") // ""
+ */
+export function addDuration(a, b) {
+    if (!isValidDuration(a) || !isValidDuration(b)) {
+        return "";
+    }
+    try {
+        return Temporal.Duration.from(a).add(b).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/duration/calculate/durationAs.d.ts

@@ -0,0 +1,38 @@
+import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index.js";
+/**
+ * Express an ISO 8601 duration as a single fractional total in one unit.
+ *
+ * - Uses Temporal.Duration.from and .total — the whole duration is converted, so
+ *   durationAs("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
+ * - The result is fractional, not rounded: durationAs("P1DT2H30M", "days") is
+ *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead.
+ * - `relativeTo` is required whenever a calendar unit (year/month/week) is involved, in
+ *   *either* direction — as the requested `unit`, or because the input duration already has
+ *   a nonzero year/month/week component. Without it, returns null. This is the same
+ *   documented gap `normalizeDuration` (A3) carries; `addDuration`/`subtractDuration` (A2)
+ *   have it worse still, since Temporal gives them no `relativeTo` option at all.
+ * - The requested-unit half of that rule bites even on day/time-only input: "P1DT2H30M" has
+ *   no calendar component, yet durationAs("P1DT2H30M", "weeks") is still null — a week is a
+ *   calendar quantity to Temporal regardless of what it is being measured from.
+ * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
+ *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
+ * - Returns null on a non-duration `value`, an invalid `unit`, or an invalid `relativeTo`.
+ *
+ * @param value ISO 8601 duration string
+ * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
+ * @returns the fractional total in `unit`, or null on invalid input
+ *
+ * @example durationAs("P1DT2H30M", "hours") // 26.5
+ * @example durationAs("P1DT2H30M", "minutes") // 1590
+ * @example durationAs("PT36H", "days") // 1.5
+ * @example durationAs("-PT90M", "hours") // -1.5
+ * @example durationAs("P1M", "days") // null (calendar unit needs relativeTo)
+ * @example durationAs("P1M", "days", { relativeTo: "2024-02-01" }) // 29
+ * @example durationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
+ * @example durationAs("not a duration", "hours") // null
+ * @example durationAs("P1Y", "days", { relativeTo: "5784-06-15[u-ca=hebrew]" }) // 385 (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ */
+export declare function durationAs(value: string, unit: DateTimeDurationUnit, options?: {
+    relativeTo?: DurationRelativeTo;
+}): number | null;

package/dist/duration/calculate/durationAs.js

@@ -0,0 +1,52 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveDurationRelativeTo } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Express an ISO 8601 duration as a single fractional total in one unit.
+ *
+ * - Uses Temporal.Duration.from and .total — the whole duration is converted, so
+ *   durationAs("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
+ * - The result is fractional, not rounded: durationAs("P1DT2H30M", "days") is
+ *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead.
+ * - `relativeTo` is required whenever a calendar unit (year/month/week) is involved, in
+ *   *either* direction — as the requested `unit`, or because the input duration already has
+ *   a nonzero year/month/week component. Without it, returns null. This is the same
+ *   documented gap `normalizeDuration` (A3) carries; `addDuration`/`subtractDuration` (A2)
+ *   have it worse still, since Temporal gives them no `relativeTo` option at all.
+ * - The requested-unit half of that rule bites even on day/time-only input: "P1DT2H30M" has
+ *   no calendar component, yet durationAs("P1DT2H30M", "weeks") is still null — a week is a
+ *   calendar quantity to Temporal regardless of what it is being measured from.
+ * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
+ *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
+ * - Returns null on a non-duration `value`, an invalid `unit`, or an invalid `relativeTo`.
+ *
+ * @param value ISO 8601 duration string
+ * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
+ * @returns the fractional total in `unit`, or null on invalid input
+ *
+ * @example durationAs("P1DT2H30M", "hours") // 26.5
+ * @example durationAs("P1DT2H30M", "minutes") // 1590
+ * @example durationAs("PT36H", "days") // 1.5
+ * @example durationAs("-PT90M", "hours") // -1.5
+ * @example durationAs("P1M", "days") // null (calendar unit needs relativeTo)
+ * @example durationAs("P1M", "days", { relativeTo: "2024-02-01" }) // 29
+ * @example durationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
+ * @example durationAs("not a duration", "hours") // null
+ * @example durationAs("P1Y", "days", { relativeTo: "5784-06-15[u-ca=hebrew]" }) // 385 (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ */
+export function durationAs(value, unit, options) {
+    if (!isValidDuration(value) || !isValidDateTimeDurationUnit(unit)) {
+        return null;
+    }
+    try {
+        return Temporal.Duration.from(value).total({
+            unit,
+            relativeTo: resolveDurationRelativeTo(options?.relativeTo),
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/duration/calculate/getDurationSign.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Report whether an ISO 8601 duration is negative, zero-length, or positive.
+ *
+ * - Uses Temporal.Duration.from and reads .sign: -1, 0, or 1.
+ * - Zero is its own result, not folded into the positive case — "PT0S" is 0, and so is
+ *   "-PT0S", since a negated zero is still zero.
+ * - Needs no `relativeTo`: a duration's sign is carried on its components, not derived from
+ *   how long they measure, so calendar-unit durations answer fine.
+ * - Returns null when `value` is not a valid ISO 8601 duration string — distinct from the 0
+ *   a valid zero-length duration returns.
+ *
+ * @param value ISO 8601 duration string
+ * @returns -1 for a negative duration, 0 for zero-length, 1 for positive, or null on invalid input
+ *
+ * @example getDurationSign("P1DT2H") // 1
+ * @example getDurationSign("-P1DT2H") // -1
+ * @example getDurationSign("PT0S") // 0
+ * @example getDurationSign("-PT0S") // 0
+ * @example getDurationSign("-P1Y") // -1 (no relativeTo needed)
+ * @example getDurationSign("not a duration") // null
+ */
+export declare function getDurationSign(value: string): number | null;

package/dist/duration/calculate/getDurationSign.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Report whether an ISO 8601 duration is negative, zero-length, or positive.
+ *
+ * - Uses Temporal.Duration.from and reads .sign: -1, 0, or 1.
+ * - Zero is its own result, not folded into the positive case — "PT0S" is 0, and so is
+ *   "-PT0S", since a negated zero is still zero.
+ * - Needs no `relativeTo`: a duration's sign is carried on its components, not derived from
+ *   how long they measure, so calendar-unit durations answer fine.
+ * - Returns null when `value` is not a valid ISO 8601 duration string — distinct from the 0
+ *   a valid zero-length duration returns.
+ *
+ * @param value ISO 8601 duration string
+ * @returns -1 for a negative duration, 0 for zero-length, 1 for positive, or null on invalid input
+ *
+ * @example getDurationSign("P1DT2H") // 1
+ * @example getDurationSign("-P1DT2H") // -1
+ * @example getDurationSign("PT0S") // 0
+ * @example getDurationSign("-PT0S") // 0
+ * @example getDurationSign("-P1Y") // -1 (no relativeTo needed)
+ * @example getDurationSign("not a duration") // null
+ */
+export function getDurationSign(value) {
+    if (!isValidDuration(value)) {
+        return null;
+    }
+    try {
+        return Temporal.Duration.from(value).sign;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/duration/calculate/getDurationUnit.d.ts

@@ -0,0 +1,31 @@
+import type { DateTimeDurationUnit } from "../../types/index.js";
+/**
+ * Read a single component out of an ISO 8601 duration string.
+ *
+ * - Uses Temporal.Duration.from and reads the named field directly — this is the value as
+ *   *stored*, not a converted total: getDurationUnit("PT90M", "hours") is 0, because "PT90M"
+ *   holds 90 in its minutes field and nothing in its hours field. Use `durationAs` for a
+ *   converted total.
+ * - Never needs `relativeTo`: reading a field is not a unit conversion, so calendar units
+ *   (years/months/weeks) work here even though they require an anchor in `durationAs`.
+ * - Temporal balances fractional units at parse time, so getDurationUnit("PT1.5H", "minutes")
+ *   is 30 — the input's own precision, not the caller's spelling of it, decides the fields.
+ * - A negative duration stores *every* field as negative, so this returns a negative number
+ *   for each nonzero component of "-P1DT2H", not just the leading one.
+ * - Returns null when `value` is not a valid duration string or `unit` is not a valid
+ *   DateTimeDurationUnit.
+ *
+ * @param value ISO 8601 duration string
+ * @param unit DateTimeDurationUnit to read ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @returns the component's value, or null on invalid input
+ *
+ * @example getDurationUnit("P1DT2H30M", "hours") // 2
+ * @example getDurationUnit("P1DT2H30M", "minutes") // 30
+ * @example getDurationUnit("PT90M", "hours") // 0 (stored as minutes, not converted)
+ * @example getDurationUnit("-P1DT2H", "hours") // -2
+ * @example getDurationUnit("P1M", "months") // 1 (no relativeTo needed to read a field)
+ * @example getDurationUnit("PT0S", "days") // 0
+ * @example getDurationUnit("not a duration", "hours") // null
+ * @example getDurationUnit("P1D", "fortnights") // null
+ */
+export declare function getDurationUnit(value: string, unit: DateTimeDurationUnit): number | null;

package/dist/duration/calculate/getDurationUnit.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Read a single component out of an ISO 8601 duration string.
+ *
+ * - Uses Temporal.Duration.from and reads the named field directly — this is the value as
+ *   *stored*, not a converted total: getDurationUnit("PT90M", "hours") is 0, because "PT90M"
+ *   holds 90 in its minutes field and nothing in its hours field. Use `durationAs` for a
+ *   converted total.
+ * - Never needs `relativeTo`: reading a field is not a unit conversion, so calendar units
+ *   (years/months/weeks) work here even though they require an anchor in `durationAs`.
+ * - Temporal balances fractional units at parse time, so getDurationUnit("PT1.5H", "minutes")
+ *   is 30 — the input's own precision, not the caller's spelling of it, decides the fields.
+ * - A negative duration stores *every* field as negative, so this returns a negative number
+ *   for each nonzero component of "-P1DT2H", not just the leading one.
+ * - Returns null when `value` is not a valid duration string or `unit` is not a valid
+ *   DateTimeDurationUnit.
+ *
+ * @param value ISO 8601 duration string
+ * @param unit DateTimeDurationUnit to read ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @returns the component's value, or null on invalid input
+ *
+ * @example getDurationUnit("P1DT2H30M", "hours") // 2
+ * @example getDurationUnit("P1DT2H30M", "minutes") // 30
+ * @example getDurationUnit("PT90M", "hours") // 0 (stored as minutes, not converted)
+ * @example getDurationUnit("-P1DT2H", "hours") // -2
+ * @example getDurationUnit("P1M", "months") // 1 (no relativeTo needed to read a field)
+ * @example getDurationUnit("PT0S", "days") // 0
+ * @example getDurationUnit("not a duration", "hours") // null
+ * @example getDurationUnit("P1D", "fortnights") // null
+ */
+export function getDurationUnit(value, unit) {
+    if (!isValidDuration(value) || !isValidDateTimeDurationUnit(unit)) {
+        return null;
+    }
+    try {
+        return Temporal.Duration.from(value)[unit];
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,7 @@
+export * from "./absDuration.js";
+export * from "./addDuration.js";
+export * from "./durationAs.js";
+export * from "./getDurationSign.js";
+export * from "./getDurationUnit.js";
+export * from "./negateDuration.js";
+export * from "./subtractDuration.js";

package/dist/duration/calculate/index.js

@@ -0,0 +1,7 @@
+export * from "./absDuration.js";
+export * from "./addDuration.js";
+export * from "./durationAs.js";
+export * from "./getDurationSign.js";
+export * from "./getDurationUnit.js";
+export * from "./negateDuration.js";
+export * from "./subtractDuration.js";

package/dist/duration/calculate/negateDuration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Flip the sign of an ISO 8601 duration string.
+ *
+ * - Uses Temporal.Duration.from and .negated, then .toString() to re-emit.
+ * - Negating is a pure sign flip on every component, so it never needs `relativeTo` —
+ *   calendar-unit durations round-trip through it fine, unlike `addDuration`/`durationAs`.
+ * - A zero-length duration has no sign to flip and comes back as "PT0S", the canonical
+ *   spelling Temporal emits for every zero duration (so "P0D" also renders "PT0S").
+ * - Returns "" when `value` is not a valid ISO 8601 duration string.
+ *
+ * @param value ISO 8601 duration string
+ * @returns ISO 8601 duration string with the opposite sign, or "" on invalid input
+ *
+ * @example negateDuration("P1DT2H") // "-P1DT2H"
+ * @example negateDuration("-P1DT2H") // "P1DT2H"
+ * @example negateDuration("P1Y2M") // "-P1Y2M" (no relativeTo needed)
+ * @example negateDuration("PT0S") // "PT0S"
+ * @example negateDuration("not a duration") // ""
+ */
+export declare function negateDuration(value: string): string;

package/dist/duration/calculate/negateDuration.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Flip the sign of an ISO 8601 duration string.
+ *
+ * - Uses Temporal.Duration.from and .negated, then .toString() to re-emit.
+ * - Negating is a pure sign flip on every component, so it never needs `relativeTo` —
+ *   calendar-unit durations round-trip through it fine, unlike `addDuration`/`durationAs`.
+ * - A zero-length duration has no sign to flip and comes back as "PT0S", the canonical
+ *   spelling Temporal emits for every zero duration (so "P0D" also renders "PT0S").
+ * - Returns "" when `value` is not a valid ISO 8601 duration string.
+ *
+ * @param value ISO 8601 duration string
+ * @returns ISO 8601 duration string with the opposite sign, or "" on invalid input
+ *
+ * @example negateDuration("P1DT2H") // "-P1DT2H"
+ * @example negateDuration("-P1DT2H") // "P1DT2H"
+ * @example negateDuration("P1Y2M") // "-P1Y2M" (no relativeTo needed)
+ * @example negateDuration("PT0S") // "PT0S"
+ * @example negateDuration("not a duration") // ""
+ */
+export function negateDuration(value) {
+    if (!isValidDuration(value)) {
+        return "";
+    }
+    try {
+        return Temporal.Duration.from(value).negated().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/duration/calculate/subtractDuration.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Combine two ISO 8601 duration strings by subtraction.
+ *
+ * - Uses Temporal.Duration.from and .subtract to combine, then .toString() to re-emit.
+ * - Temporal.Duration.prototype.subtract has no `relativeTo` option, so combining any pair
+ *   where either operand has a nonzero years/months/weeks component throws and
+ *   results in "" — calendar-unit duration arithmetic needs a reference point that
+ *   this function does not accept.
+ * - The result may be negative (e.g. subtracting a larger duration from a smaller one).
+ * - Returns "" if either operand is not a valid ISO 8601 duration string.
+ *
+ * @param a ISO 8601 duration string
+ * @param b ISO 8601 duration string
+ * @returns ISO 8601 duration string representing a - b, or "" on invalid input
+ *
+ * @example subtractDuration("P1D", "PT2H") // "PT22H"
+ * @example subtractDuration("PT1H", "PT2H") // "-PT1H"
+ * @example subtractDuration("P1Y", "P1M") // "" (calendar units need relativeTo, unsupported)
+ * @example subtractDuration("P1D", "not a duration") // ""
+ */
+export declare function subtractDuration(a: string, b: string): string;

package/dist/duration/calculate/subtractDuration.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Combine two ISO 8601 duration strings by subtraction.
+ *
+ * - Uses Temporal.Duration.from and .subtract to combine, then .toString() to re-emit.
+ * - Temporal.Duration.prototype.subtract has no `relativeTo` option, so combining any pair
+ *   where either operand has a nonzero years/months/weeks component throws and
+ *   results in "" — calendar-unit duration arithmetic needs a reference point that
+ *   this function does not accept.
+ * - The result may be negative (e.g. subtracting a larger duration from a smaller one).
+ * - Returns "" if either operand is not a valid ISO 8601 duration string.
+ *
+ * @param a ISO 8601 duration string
+ * @param b ISO 8601 duration string
+ * @returns ISO 8601 duration string representing a - b, or "" on invalid input
+ *
+ * @example subtractDuration("P1D", "PT2H") // "PT22H"
+ * @example subtractDuration("PT1H", "PT2H") // "-PT1H"
+ * @example subtractDuration("P1Y", "P1M") // "" (calendar units need relativeTo, unsupported)
+ * @example subtractDuration("P1D", "not a duration") // ""
+ */
+export function subtractDuration(a, b) {
+    if (!isValidDuration(a) || !isValidDuration(b)) {
+        return "";
+    }
+    try {
+        return Temporal.Duration.from(a).subtract(b).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/duration/compare/compareDurations.d.ts

@@ -0,0 +1,37 @@
+import type { DurationRelativeTo } from "../../types/index.js";
+/**
+ * Compare two ISO 8601 duration strings by length.
+ *
+ * - Uses Temporal.Duration.compare: -1 when `a` is shorter, 0 when equal, 1 when `a` is longer.
+ * - Equality is by length, not by spelling — "PT60M" and "PT1H" compare 0, as do "P1D" and
+ *   "PT24H" absent a `relativeTo`.
+ * - `relativeTo` is required whenever a calendar unit (year/month/week) appears on either
+ *   side; without it, returns null. Note the asymmetry with `addDuration`/`subtractDuration`
+ *   (A2): Temporal.Duration.compare *does* accept `relativeTo`, while .add/.subtract do not,
+ *   so calendar-unit durations are comparable here even though they cannot be combined there.
+ *   `durationAs` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
+ * - The anchor genuinely decides the answer rather than merely unblocking it: "P1M" is longer
+ *   than "P30D" relative to January (31 days) and shorter relative to February 2024 (29).
+ * - It matters for non-calendar units too when it names a zoned instant — across a DST
+ *   spring-forward, "P1D" is 23 real hours and so compares shorter than "PT24H".
+ * - Returns null if either operand is not a valid ISO 8601 duration string, or `relativeTo`
+ *   is invalid.
+ *
+ * @param a ISO 8601 duration string
+ * @param b ISO 8601 duration string
+ * @param options optional: { relativeTo } — anchor date/instant, required when either side has a calendar unit
+ * @returns -1, 0, or 1, or null on invalid input
+ *
+ * @example compareDurations("PT1H", "PT30M") // 1
+ * @example compareDurations("PT60M", "PT1H") // 0
+ * @example compareDurations("-PT1H", "PT1H") // -1
+ * @example compareDurations("P1M", "P30D") // null (calendar unit needs relativeTo)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" }) // 1
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-01" }) // -1
+ * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // -1 (spring-forward)
+ * @example compareDurations("not a duration", "PT1H") // null
+ * @example compareDurations("P1M", "P30D", { relativeTo: "5785-04-15[u-ca=hebrew]" }) // -1 (Tevet, a 29-day Hebrew month — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ */
+export declare function compareDurations(a: string, b: string, options?: {
+    relativeTo?: DurationRelativeTo;
+}): number | null;

package/dist/duration/compare/compareDurations.js

@@ -0,0 +1,49 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveDurationRelativeTo } from "../../internal/index.js";
+import { isValidDuration } from "../validate/isValidDuration.js";
+/**
+ * Compare two ISO 8601 duration strings by length.
+ *
+ * - Uses Temporal.Duration.compare: -1 when `a` is shorter, 0 when equal, 1 when `a` is longer.
+ * - Equality is by length, not by spelling — "PT60M" and "PT1H" compare 0, as do "P1D" and
+ *   "PT24H" absent a `relativeTo`.
+ * - `relativeTo` is required whenever a calendar unit (year/month/week) appears on either
+ *   side; without it, returns null. Note the asymmetry with `addDuration`/`subtractDuration`
+ *   (A2): Temporal.Duration.compare *does* accept `relativeTo`, while .add/.subtract do not,
+ *   so calendar-unit durations are comparable here even though they cannot be combined there.
+ *   `durationAs` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
+ * - The anchor genuinely decides the answer rather than merely unblocking it: "P1M" is longer
+ *   than "P30D" relative to January (31 days) and shorter relative to February 2024 (29).
+ * - It matters for non-calendar units too when it names a zoned instant — across a DST
+ *   spring-forward, "P1D" is 23 real hours and so compares shorter than "PT24H".
+ * - Returns null if either operand is not a valid ISO 8601 duration string, or `relativeTo`
+ *   is invalid.
+ *
+ * @param a ISO 8601 duration string
+ * @param b ISO 8601 duration string
+ * @param options optional: { relativeTo } — anchor date/instant, required when either side has a calendar unit
+ * @returns -1, 0, or 1, or null on invalid input
+ *
+ * @example compareDurations("PT1H", "PT30M") // 1
+ * @example compareDurations("PT60M", "PT1H") // 0
+ * @example compareDurations("-PT1H", "PT1H") // -1
+ * @example compareDurations("P1M", "P30D") // null (calendar unit needs relativeTo)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" }) // 1
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-01" }) // -1
+ * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // -1 (spring-forward)
+ * @example compareDurations("not a duration", "PT1H") // null
+ * @example compareDurations("P1M", "P30D", { relativeTo: "5785-04-15[u-ca=hebrew]" }) // -1 (Tevet, a 29-day Hebrew month — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ */
+export function compareDurations(a, b, options) {
+    if (!isValidDuration(a) || !isValidDuration(b)) {
+        return null;
+    }
+    try {
+        return Temporal.Duration.compare(a, b, {
+            relativeTo: resolveDurationRelativeTo(options?.relativeTo),
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/duration/compare/index.d.ts

@@ -0,0 +1 @@
+export * from "./compareDurations.js";

package/dist/duration/compare/index.js

@@ -0,0 +1 @@
+export * from "./compareDurations.js";

package/dist/duration/format/formatDuration.d.ts

@@ -0,0 +1,37 @@
+export interface FormatDurationOptions {
+    style?: "long" | "short" | "narrow";
+    zero?: boolean;
+}
+/**
+ * Render an ISO 8601 duration string as a locale-aware, human-readable string.
+ *
+ * - Uses Temporal.Duration.from to parse, then Intl.NumberFormat({ style: "unit" })
+ *   to render each nonzero year/month/week/day/hour/minute/second component with
+ *   correct per-locale unit labels and pluralization, joined via Intl.ListFormat.
+ * - Sub-second components (milliseconds/microseconds/nanoseconds) are folded into
+ *   the seconds component as a fractional value (e.g. "PT1.5S" -> one "1.5 seconds"
+ *   component), since Intl.NumberFormat's "second" unit accepts fractional input.
+ * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day, 30
+ *   minutes"). Pass { zero: true } to include them.
+ * - A zero-length duration (e.g. "PT0S") always renders its seconds component
+ *   ("0 seconds") even with the default zero-omitting behavior, since omitting
+ *   every component would otherwise produce "".
+ * - Negative durations render each component with a leading "-" (Temporal stores
+ *   every field of a negative duration as a negative number).
+ * - Returns "" for invalid input: non-string value or invalid duration string.
+ *
+ * @param value ISO 8601 duration string
+ * @param locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted
+ * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
+ * @returns human-readable rendering of the duration, or "" on invalid input
+ *
+ * @example formatDuration("P1DT2H30M", "en-US") // "1 day, 2 hours, and 30 minutes"
+ * @example formatDuration("PT90M", "en-US", { style: "short" }) // "90 min"
+ * @example formatDuration("PT90M", "en-US", { style: "narrow" }) // "90m"
+ * @example formatDuration("P1DT0H30M", "en-US") // "1 day and 30 minutes"
+ * @example formatDuration("PT0S", "en-US") // "0 seconds"
+ * @example formatDuration("-P1DT2H", "en-US") // "-1 day and -2 hours"
+ * @example formatDuration("P1DT2H30M", "de-DE") // "1 Tag, 2 Stunden und 30 Minuten"
+ * @example formatDuration("invalid") // ""
+ */
+export declare function formatDuration(value: string, locale?: string, options?: FormatDurationOptions): string;