@northguild/gmt 1.15.0 → 1.17.0

package/dist/duration/compare/compareDurations.js

@@ -1,6 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { resolveDurationRelativeTo } from "../../internal/index.js";
+import { durationCompare, resolveDurationRelativeTo } from "../../internal/index.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two ISO 8601 duration strings by length.
  *
@@ -8,7 +8,8 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  * - 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`
+ *   side and the two durations differ; without it, returns null. Field-identical durations
+ *   compare 0 without it ("P1Y" vs "P1Y"), since Temporal checks identity first. 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.
@@ -16,6 +17,23 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  *   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".
+ * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
+ *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
+ *   nonexistent one the later instant, and an offset that does not match the zone returns null.
+ *   Pass an explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return null.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
  * - Returns null if either operand is not a valid ISO 8601 duration string, or `relativeTo`
  *   is invalid.
  *
@@ -30,18 +48,24 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  * @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("P1M", "P30D", { relativeTo: "2024-02-01 00:00" }) // null (space separator)
  * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // -1 (spring-forward)
+ * @example compareDurations("P1Y", "P1Y") // 0
+ * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 1
  * @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)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2025-01-15[u-ca=hebrew]" }) // -1 (Tevet 5785, a 29-day Hebrew month)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-10[!u-ca=hebrew]" }) // 0 (1 Adar I 5784, a 30-day month; the critical flag is accepted)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 0 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export function compareDurations(a, b, options) {
+    if (!isOptionsArgument(options)) {
+        return null;
+    }
     if (!isValidDuration(a) || !isValidDuration(b)) {
         return null;
     }
     try {
-        return Temporal.Duration.compare(a, b, {
-            relativeTo: resolveDurationRelativeTo(options?.relativeTo),
-        });
+        return durationCompare(a, b, resolveDurationRelativeTo(options?.relativeTo));
     }
     catch {
         return null;

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

@@ -9,9 +9,14 @@ export interface FormatDurationOptions {
  *   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
+ *   the seconds component as an exact fractional value (e.g. "PT1.5S" -> one "1.5 seconds"
+ *   component). Every digit the duration holds is rendered, up to 9 fraction digits and
+ *   seconds up to 2^53 - 1: nothing is rounded, so a non-zero duration never prints
+ *   "0 seconds" and "PT9007199254740991.999999999S" renders exactly.
+ * - To render fewer fraction digits, round the string first with parseDuration, e.g.
+ *   { smallestUnit: "millisecond", roundingMode: "halfExpand" } for the 3-digit output this
+ *   function produced before (parseDuration's default roundingMode "trunc" drops the digits).
+ * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day and 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
@@ -21,7 +26,7 @@ export interface FormatDurationOptions {
  * - 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 locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted, or a preference list of tags (ECMA-402)
  * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
  * @returns human-readable rendering of the duration, or "" on invalid input
  *
@@ -32,6 +37,10 @@ export interface FormatDurationOptions {
  * @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("PT0.000000001S", "en-US") // "0.000000001 seconds"
+ * @example formatDuration("PT1.123456789S", "en-US") // "1.123456789 seconds"
+ * @example formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-US") // "1.123 seconds"
  * @example formatDuration("invalid") // ""
+ * @example formatDuration("P1DT2H30M", ["es-ES", "en-US"]) // "1 día, 2 horas y 30 minutos"
  */
-export declare function formatDuration(value: string, locale?: string, options?: FormatDurationOptions): string;
+export declare function formatDuration(value: string, locale?: string | string[], options?: FormatDurationOptions): string;

package/dist/duration/format/formatDuration.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isOptionsArgument } from "../../internal/isObject.js";
 const UNIT_TO_INTL = {
     years: "year",
     months: "month",
@@ -17,6 +18,32 @@ const UNITS_IN_ORDER = [
     "minutes",
     "seconds",
 ];
+const NANOSECONDS_PER_SECOND = 1000000000n;
+function isZeroAmount(amount) {
+    return amount === 0 || amount === "0";
+}
+/**
+ * The duration's seconds plus its sub-second fields as an exact decimal string.
+ *
+ * Summed in bigint nanoseconds, not float seconds: Temporal allows seconds up to 2^53 - 1 with 9
+ * fraction digits (IsValidDuration), which a float cannot hold. ECMA-402 Intl.NumberFormat accepts
+ * a decimal string and formats it without converting to a Number (ToIntlMathematicalValue).
+ * Returns "0", never "-0", for a zero amount, so a negative duration's zero seconds renders as 0.
+ */
+function exactSeconds(duration) {
+    const total = BigInt(duration.seconds) * NANOSECONDS_PER_SECOND +
+        BigInt(duration.milliseconds) * 1000000n +
+        BigInt(duration.microseconds) * 1000n +
+        BigInt(duration.nanoseconds);
+    const magnitude = total < 0n ? -total : total;
+    const whole = magnitude / NANOSECONDS_PER_SECOND;
+    const fraction = (magnitude % NANOSECONDS_PER_SECOND)
+        .toString()
+        .padStart(9, "0")
+        .replace(/0+$/, "");
+    const sign = total < 0n ? "-" : "";
+    return `${sign}${whole}${fraction === "" ? "" : `.${fraction}`}`;
+}
 /**
  * Render an ISO 8601 duration string as a locale-aware, human-readable string.
  *
@@ -24,9 +51,14 @@ const UNITS_IN_ORDER = [
  *   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
+ *   the seconds component as an exact fractional value (e.g. "PT1.5S" -> one "1.5 seconds"
+ *   component). Every digit the duration holds is rendered, up to 9 fraction digits and
+ *   seconds up to 2^53 - 1: nothing is rounded, so a non-zero duration never prints
+ *   "0 seconds" and "PT9007199254740991.999999999S" renders exactly.
+ * - To render fewer fraction digits, round the string first with parseDuration, e.g.
+ *   { smallestUnit: "millisecond", roundingMode: "halfExpand" } for the 3-digit output this
+ *   function produced before (parseDuration's default roundingMode "trunc" drops the digits).
+ * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day and 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
@@ -36,7 +68,7 @@ const UNITS_IN_ORDER = [
  * - 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 locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted, or a preference list of tags (ECMA-402)
  * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
  * @returns human-readable rendering of the duration, or "" on invalid input
  *
@@ -47,20 +79,23 @@ const UNITS_IN_ORDER = [
  * @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("PT0.000000001S", "en-US") // "0.000000001 seconds"
+ * @example formatDuration("PT1.123456789S", "en-US") // "1.123456789 seconds"
+ * @example formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-US") // "1.123 seconds"
  * @example formatDuration("invalid") // ""
+ * @example formatDuration("P1DT2H30M", ["es-ES", "en-US"]) // "1 día, 2 horas y 30 minutos"
  */
 export function formatDuration(value, locale, options = {}) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (typeof value !== "string") {
         return "";
     }
     try {
         const duration = Temporal.Duration.from(value);
-        const style = options.style ?? "long";
+        const style = options.style === undefined ? "long" : options.style;
         const includeZero = options.zero ?? false;
-        const seconds = duration.seconds +
-            duration.milliseconds / 1e3 +
-            duration.microseconds / 1e6 +
-            duration.nanoseconds / 1e9;
         const amounts = {
             years: duration.years,
             months: duration.months,
@@ -68,12 +103,13 @@ export function formatDuration(value, locale, options = {}) {
             days: duration.days,
             hours: duration.hours,
             minutes: duration.minutes,
-            seconds,
+            seconds: exactSeconds(duration),
         };
-        const parts = UNITS_IN_ORDER.filter((unit) => includeZero || amounts[unit] !== 0).map((unit) => new Intl.NumberFormat(locale, {
+        const parts = UNITS_IN_ORDER.filter((unit) => includeZero || !isZeroAmount(amounts[unit])).map((unit) => new Intl.NumberFormat(locale, {
             style: "unit",
             unit: UNIT_TO_INTL[unit],
             unitDisplay: style,
+            maximumFractionDigits: 9,
         }).format(amounts[unit]));
         if (parts.length === 0) {
             parts.push(new Intl.NumberFormat(locale, {

package/dist/duration/index.d.ts

@@ -1,3 +1,4 @@
+export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./format/index.js";

package/dist/duration/index.js

@@ -1,3 +1,5 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./format/index.js";

package/dist/duration/normalize/normalizeDuration.d.ts

@@ -4,15 +4,36 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * Roll an ISO 8601 duration string's small units into larger ones.
  *
  * - Uses Temporal.Duration.from and .round to rebalance, then .toString() to re-emit.
- * - Defaults to { largestUnit: "auto" } when no options are given, which reformats a
- *   day/time-only duration without promoting units (e.g. "PT90M" stays "PT90M" — pass
- *   an explicit largestUnit to promote).
+ * - Defaults to { largestUnit: "auto" }, which resolves to the larger of smallestUnit and the
+ *   duration's own largest non-zero unit, then balances up to it. Units are promoted only up to
+ *   a unit already present: "PT90M" stays "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M"
+ *   becomes "PT2H30M". Pass an explicit largestUnit to promote further.
  * - relativeTo is required whenever a calendar unit (year/month/week) is involved,
  *   either as the requested largestUnit or because the input duration already has a
  *   nonzero year/month/week component (this applies even under the "auto" default).
  *   Without relativeTo in either case, returns "".
- * - roundingIncrement must evenly divide 60 for minute/second (24 for hour);
- *   unconstrained for day/week/month/year. An invalid increment returns "".
+ * - roundingIncrement must evenly divide, and be less than, 24 for hour, 60 for minute/second
+ *   and 1000 for millisecond/microsecond/nanosecond (so 60 and 24 themselves are rejected).
+ *   For year/month/week/day it has no maximum, but an increment above 1 is rejected unless
+ *   largestUnit is that same unit ("auto" resolves to the largest unit present). An invalid
+ *   increment returns "".
+ * - A zoned relativeTo string resolves its wall time with disambiguation "compatible" and offset
+ *   "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a nonexistent
+ *   one the later instant, and an offset that does not match the zone returns "". Pass an
+ *   explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return `""`.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
  * - Returns "" for invalid input: non-string value, invalid duration string, or
  *   invalid relativeTo.
  *
@@ -24,8 +45,14 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example normalizeDuration("PT90M30S", { smallestUnit: "minute" }) // "PT91M"
  * @example normalizeDuration("P45D", { largestUnit: "month" }) // "" (relativeTo required)
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-01-01" }) // "P1M14D"
+ * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "20240101" }) // "" (basic format)
+ * @example normalizeDuration("P1DT25H") // "P2DT1H"
+ * @example normalizeDuration("PT2H", { smallestUnit: "minute", roundingIncrement: 60 }) // ""
+ * @example normalizeDuration("PT25H", { largestUnit: "day", relativeTo: "2024-11-03T01:30[America/New_York]" }) // "P1D"
  * @example normalizeDuration("invalid") // ""
- * @example normalizeDuration("P400D", { largestUnit: "year", relativeTo: "5784-06-15[u-ca=hebrew]" }) // "P1Y15D" (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ * @example normalizeDuration("P400D", { largestUnit: "year", relativeTo: "2024-02-24[u-ca=hebrew]" }) // "P1Y15D" (Hebrew leap year 5784)
+ * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10[!u-ca=hebrew]" }) // "P1M15D" (1 Adar I 5784; the critical flag is accepted)
+ * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // "P1M15D" (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export declare function normalizeDuration(value: string, options?: {
     largestUnit?: Temporal.LargestUnit<Temporal.DateTimeUnit>;

package/dist/duration/normalize/normalizeDuration.js

@@ -1,18 +1,40 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveDurationRelativeTo } from "../../internal/index.js";
+import { durationRound, resolveDurationRelativeTo } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Roll an ISO 8601 duration string's small units into larger ones.
  *
  * - Uses Temporal.Duration.from and .round to rebalance, then .toString() to re-emit.
- * - Defaults to { largestUnit: "auto" } when no options are given, which reformats a
- *   day/time-only duration without promoting units (e.g. "PT90M" stays "PT90M" — pass
- *   an explicit largestUnit to promote).
+ * - Defaults to { largestUnit: "auto" }, which resolves to the larger of smallestUnit and the
+ *   duration's own largest non-zero unit, then balances up to it. Units are promoted only up to
+ *   a unit already present: "PT90M" stays "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M"
+ *   becomes "PT2H30M". Pass an explicit largestUnit to promote further.
  * - relativeTo is required whenever a calendar unit (year/month/week) is involved,
  *   either as the requested largestUnit or because the input duration already has a
  *   nonzero year/month/week component (this applies even under the "auto" default).
  *   Without relativeTo in either case, returns "".
- * - roundingIncrement must evenly divide 60 for minute/second (24 for hour);
- *   unconstrained for day/week/month/year. An invalid increment returns "".
+ * - roundingIncrement must evenly divide, and be less than, 24 for hour, 60 for minute/second
+ *   and 1000 for millisecond/microsecond/nanosecond (so 60 and 24 themselves are rejected).
+ *   For year/month/week/day it has no maximum, but an increment above 1 is rejected unless
+ *   largestUnit is that same unit ("auto" resolves to the largest unit present). An invalid
+ *   increment returns "".
+ * - A zoned relativeTo string resolves its wall time with disambiguation "compatible" and offset
+ *   "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a nonexistent
+ *   one the later instant, and an offset that does not match the zone returns "". Pass an
+ *   explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return `""`.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
  * - Returns "" for invalid input: non-string value, invalid duration string, or
  *   invalid relativeTo.
  *
@@ -24,24 +46,31 @@ import { resolveDurationRelativeTo } from "../../internal/index.js";
  * @example normalizeDuration("PT90M30S", { smallestUnit: "minute" }) // "PT91M"
  * @example normalizeDuration("P45D", { largestUnit: "month" }) // "" (relativeTo required)
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-01-01" }) // "P1M14D"
+ * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "20240101" }) // "" (basic format)
+ * @example normalizeDuration("P1DT25H") // "P2DT1H"
+ * @example normalizeDuration("PT2H", { smallestUnit: "minute", roundingIncrement: 60 }) // ""
+ * @example normalizeDuration("PT25H", { largestUnit: "day", relativeTo: "2024-11-03T01:30[America/New_York]" }) // "P1D"
  * @example normalizeDuration("invalid") // ""
- * @example normalizeDuration("P400D", { largestUnit: "year", relativeTo: "5784-06-15[u-ca=hebrew]" }) // "P1Y15D" (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ * @example normalizeDuration("P400D", { largestUnit: "year", relativeTo: "2024-02-24[u-ca=hebrew]" }) // "P1Y15D" (Hebrew leap year 5784)
+ * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10[!u-ca=hebrew]" }) // "P1M15D" (1 Adar I 5784; the critical flag is accepted)
+ * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // "P1M15D" (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export function normalizeDuration(value, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (typeof value !== "string") {
         return "";
     }
     try {
         const duration = Temporal.Duration.from(value);
-        return duration
-            .round({
-            largestUnit: options?.largestUnit ?? "auto",
+        return durationRound(duration, {
+            largestUnit: options?.largestUnit === undefined ? "auto" : options.largestUnit,
             smallestUnit: options?.smallestUnit,
             roundingIncrement: options?.roundingIncrement,
             roundingMode: options?.roundingMode,
             relativeTo: resolveDurationRelativeTo(options?.relativeTo),
-        })
-            .toString();
+        }).toString();
     }
     catch {
         return "";

package/dist/duration/parse/parseDuration.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Parse and re-normalize an ISO 8601 duration string.
  *
@@ -18,6 +19,9 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseDuration("invalid") // ""
  */
 export function parseDuration(value, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (typeof value !== "string") {
         return "";
     }

package/dist/index.d.ts

@@ -1,7 +1,14 @@
 export * from "@js-temporal/polyfill";
+export * from "./calendar/index.js";
 export * from "./duration/index.js";
+export * from "./instant/index.js";
+export * from "./intermodal/index.js";
+export * from "./interval/index.js";
 export * from "./plain/index.js";
+export * from "./precision/index.js";
 export * from "./regex/index.js";
+export * from "./span/index.js";
+export * from "./transport/index.js";
 export * from "./types/index.js";
 export * from "./unix/index.js";
 export * from "./utc/index.js";

package/dist/index.js

@@ -1,7 +1,14 @@
 export * from "@js-temporal/polyfill";
+export * from "./calendar/index.js";
 export * from "./duration/index.js";
+export * from "./instant/index.js";
+export * from "./intermodal/index.js";
+export * from "./interval/index.js";
 export * from "./plain/index.js";
+export * from "./precision/index.js";
 export * from "./regex/index.js";
+export * from "./span/index.js";
+export * from "./transport/index.js";
 export * from "./types/index.js";
 export * from "./unix/index.js";
 export * from "./utc/index.js";

package/dist/instant/convert/classifyLocal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a zoneless wall time turns out to be once a zone is attached to it.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `unique` | One instant. The ordinary case, and every case in a zone with no DST. |
+ * | `ambiguous` | Two instants an offset shift apart — a fall-back hour the clock ran through twice. |
+ * | `nonexistent` | No instant. A spring-forward hour the clock skipped, or a calendar day a zone deleted crossing the date line. |
+ *
+ * @example
+ * import { LocalTimeClassification } from "@northguild/gmt/instant";
+ * const kind: LocalTimeClassification = "ambiguous";
+ */
+export type LocalTimeClassification = "unique" | "ambiguous" | "nonexistent";
+/**
+ * Report whether a zoneless local wall time is unique, ambiguous or nonexistent in a zone —
+ * before any policy resolves it.
+ *
+ * Ambiguous and nonexistent wall times are the single most common datetime bug there is:
+ * 01:30 happens twice on a fall-back day and never on a spring-forward one. `resolveLocal`
+ * will pick one for you; this exists so a demurrage clock, a medication window or a duty
+ * limit can refuse instead, or route the case to a human, rather than silently accepting
+ * whichever instant a default handed it.
+ *
+ * - Reads the zone's own transition table via `Temporal`, so it is right for every IANA zone
+ *   and every year, including 30- and 45-minute shifts and zones that skipped a whole
+ *   calendar day changing sides of the date line.
+ * - `localDateTime` is a PlainDateTime string, as `isValidDateTime` accepts: `<date>T<time>`
+ *   with no offset (a string with an offset has no ambiguity left to report). Its RFC 9557
+ *   annotations are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
+ *   is ignored and `timeZone` alone is the zone.
+ * - Returns null on invalid input — never `"unique"`, which would read as a verdict.
+ *
+ * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
+ * @param timeZone IANA timeZone identifier the wall time is read in
+ * @returns "unique" | "ambiguous" | "nonexistent", or null on invalid input
+ *
+ * @example classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"
+ * @example classifyLocal("2024-11-03T01:30:00", "America/New_York") // "ambiguous" (fall-back overlap)
+ * @example classifyLocal("2024-03-10T02:30:00", "America/New_York") // "nonexistent" (spring-forward gap)
+ * @example classifyLocal("2024-04-07T01:45:00", "Australia/Lord_Howe") // "ambiguous" (a 30-minute overlap)
+ * @example classifyLocal("2024-09-29T03:15:00", "Pacific/Chatham") // "nonexistent" (a 45-minute-offset zone's gap)
+ * @example classifyLocal("2011-12-30T12:00:00", "Pacific/Apia") // "nonexistent" (the day Samoa skipped crossing the date line)
+ * @example classifyLocal("2024-11-03T01:30:00", "UTC") // "unique" (UTC has no transitions)
+ * @example classifyLocal("2024-11-03T01:30:00-04:00", "America/New_York") // null (not a zoneless wall time)
+ * @example classifyLocal("2024-11-03T01:30:00", "Invalid/Zone") // null
+ */
+export declare function classifyLocal(localDateTime: string, timeZone: string): LocalTimeClassification | null;

package/dist/instant/convert/classifyLocal.js

@@ -0,0 +1,60 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../../plain/validate/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { plainToZoned } from "../../internal/index.js";
+/**
+ * Report whether a zoneless local wall time is unique, ambiguous or nonexistent in a zone —
+ * before any policy resolves it.
+ *
+ * Ambiguous and nonexistent wall times are the single most common datetime bug there is:
+ * 01:30 happens twice on a fall-back day and never on a spring-forward one. `resolveLocal`
+ * will pick one for you; this exists so a demurrage clock, a medication window or a duty
+ * limit can refuse instead, or route the case to a human, rather than silently accepting
+ * whichever instant a default handed it.
+ *
+ * - Reads the zone's own transition table via `Temporal`, so it is right for every IANA zone
+ *   and every year, including 30- and 45-minute shifts and zones that skipped a whole
+ *   calendar day changing sides of the date line.
+ * - `localDateTime` is a PlainDateTime string, as `isValidDateTime` accepts: `<date>T<time>`
+ *   with no offset (a string with an offset has no ambiguity left to report). Its RFC 9557
+ *   annotations are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
+ *   is ignored and `timeZone` alone is the zone.
+ * - Returns null on invalid input — never `"unique"`, which would read as a verdict.
+ *
+ * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
+ * @param timeZone IANA timeZone identifier the wall time is read in
+ * @returns "unique" | "ambiguous" | "nonexistent", or null on invalid input
+ *
+ * @example classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"
+ * @example classifyLocal("2024-11-03T01:30:00", "America/New_York") // "ambiguous" (fall-back overlap)
+ * @example classifyLocal("2024-03-10T02:30:00", "America/New_York") // "nonexistent" (spring-forward gap)
+ * @example classifyLocal("2024-04-07T01:45:00", "Australia/Lord_Howe") // "ambiguous" (a 30-minute overlap)
+ * @example classifyLocal("2024-09-29T03:15:00", "Pacific/Chatham") // "nonexistent" (a 45-minute-offset zone's gap)
+ * @example classifyLocal("2011-12-30T12:00:00", "Pacific/Apia") // "nonexistent" (the day Samoa skipped crossing the date line)
+ * @example classifyLocal("2024-11-03T01:30:00", "UTC") // "unique" (UTC has no transitions)
+ * @example classifyLocal("2024-11-03T01:30:00-04:00", "America/New_York") // null (not a zoneless wall time)
+ * @example classifyLocal("2024-11-03T01:30:00", "Invalid/Zone") // null
+ */
+export function classifyLocal(localDateTime, timeZone) {
+    if (!isValidDateTime(localDateTime) || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    try {
+        const wallClock = Temporal.PlainDateTime.from(localDateTime);
+        const earliest = plainToZoned(wallClock, timeZone, "earlier");
+        const latest = plainToZoned(wallClock, timeZone, "later");
+        if (earliest.epochNanoseconds === latest.epochNanoseconds) {
+            return "unique";
+        }
+        // Two instants, so the wall time is either repeated or skipped. Temporal separates them
+        // the same way for both, and only the wall clock it lands on tells them apart: for an
+        // overlap both instants read back as the requested time, and for a gap neither does —
+        // "earlier"/"later" resolve a gap by moving off the requested time entirely.
+        return earliest.toPlainDateTime().equals(wallClock)
+            ? "ambiguous"
+            : "nonexistent";
+    }
+    catch {
+        return null;
+    }
+}

package/dist/instant/convert/fromOffsetInstant.d.ts

@@ -0,0 +1,47 @@
+import type { OffsetInstant } from "./toOffsetInstant.js";
+/**
+ * Render an instant-plus-offset pair back to the local time it describes.
+ *
+ * The inverse of `toOffsetInstant`: `toOffsetInstant(fromOffsetInstant(pair))` returns
+ * `pair`, for zones with and without DST.
+ *
+ * - Without `timeZone`, returns `<date>T<time>±HH:MM` — the wall clock the event carried and
+ *   the offset it carried it in, which is all an offset-only pair knows.
+ * - With `timeZone`, returns the bracketed zoned string `<date>T<time>±HH:MM[Zone]`, so the
+ *   zone survives the round trip instead of being silently dropped.
+ * - A `timeZone` whose offset at `instant` is not `offset` returns `""`. The pair is stating
+ *   two things that cannot both be true, and the whole point of carrying both fields is that
+ *   a contradiction between them is visible.
+ * - `timeZone` accepts every identifier Temporal does, as `toOffsetInstant`'s bracket does —
+ *   including the single-component IANA names (`EST5EDT`, `Zulu`). A `timeZone` that is really
+ *   an offset (`"-04:00"`, or the `"-0400"`/`"+05"` spellings Temporal canonicalises to one)
+ *   returns `""`: it names no place, and no pair `toOffsetInstant` produces carries one.
+ * - `offset` is canonicalised, so `"+05:45:00"` renders as `+05:45` and `"-00:00"` as
+ *   `+00:00`. `Z` is not an accepted offset — for an event that happened at UTC the pair's
+ *   offset is `+00:00`. RFC 9557 §2.2 gives `Z` and `-00:00` a different meaning from `+00:00`
+ *   ("UTC known, local offset unknown"); a pair cannot carry that, so all three render as
+ *   `+00:00`.
+ * - With a `timeZone`, a sub-minute offset is *written* rounded to the minute, because RFC
+ *   9557 has no field for the seconds — `Africa/Monrovia`'s `-00:44:30` renders as `-00:45`.
+ *   The bracketed zone is what resolves it, so the instant stays exact and the round trip
+ *   returns `-00:44:30`. Without a `timeZone` there is no zone to resolve against, so the
+ *   full `±HH:MM:SS` is written instead; that is ISO 8601, not RFC 9557.
+ * - Returns `""` on invalid input.
+ *
+ * @param value `{ instant, offset, timeZone? }` pair, as produced by `toOffsetInstant`
+ * @returns local ISO 8601 string carrying the pair's own offset, or "" on invalid input
+ *
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00" }) // "2024-07-15T12:00:00-04:00"
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }) // "2024-07-15T12:00:00-04:00[America/New_York]"
+ * @example fromOffsetInstant({ instant: "2024-11-03T05:30:00Z", offset: "-04:00", timeZone: "America/New_York" }) // "2024-11-03T01:30:00-04:00[America/New_York]" — the first 01:30 of the fall-back night
+ * @example fromOffsetInstant({ instant: "2024-11-03T06:30:00Z", offset: "-05:00", timeZone: "America/New_York" }) // "2024-11-03T01:30:00-05:00[America/New_York]" — the second, an hour later
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "+00:00" }) // "2024-07-15T16:00:00+00:00"
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-00:00" }) // "2024-07-15T16:00:00+00:00" (RFC 9557's "offset unknown" is not kept)
+ * @example fromOffsetInstant({ instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" }) // "1969-12-31T23:15:30-00:45[Africa/Monrovia]" — RFC 9557 rounds the written offset; the zone keeps the instant exact
+ * @example fromOffsetInstant({ instant: "1970-01-01T00:00:00Z", offset: "-00:44:30" }) // "1969-12-31T23:15:30-00:44:30" — no zone to round against, so the seconds are written
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-05:00", timeZone: "America/New_York" }) // "" (offset contradicts the zone)
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "-04:00" }) // "" (an offset is not a zone)
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "Z" }) // "" (a designator, not an offset)
+ * @example fromOffsetInstant({ instant: "not an instant", offset: "-04:00" }) // ""
+ */
+export declare function fromOffsetInstant(value: OffsetInstant): string;