@northguild/gmt 1.15.0 → 1.16.0

package/dist/utc/format/formatRelativeUtc.js

@@ -1,76 +1,68 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { resolveRelativeRounding } from "../../internal/resolveRelativeRounding.js";
-import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
+import { toInstantFromUtc, toReferenceInstantFromUtc, } from "../../internal/toInstantFromUtc.js";
+import { durationTotal } from "../../internal/zonedWallClockDifference.js";
 import { isValidUtc } from "../validate/index.js";
-const AUTO_UNITS = [
-    { unit: "second", maxSeconds: 60 },
-    { unit: "minute", maxSeconds: 3_600 },
-    { unit: "hour", maxSeconds: 86_400 },
-    { unit: "day", maxSeconds: Infinity },
-];
 /**
  * Format the relative time between a UTC ISO string and a reference instant.
  *
- * - Auto-picks the display unit (second through year) based on the distance, unless
- *   `largestUnit` forces one.
+ * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
+ *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
+ *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
+ *   "3 years ago".
+ * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
+ *   Pass `largestUnit: "day"` to keep a day count.
  * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `timeZone` anchors a calendar unit (week, month or year, auto-picked or forced). Omitted, it is
+ *   `"UTC"`; pass `"local"` for the system time zone. An unknown zone returns `""` whatever the unit
+ *   (ECMA-402 throws RangeError for it).
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
  *
  * @param value UTC ISO string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { style, numeric, largestUnit, roundingMethod, reference, timeZone }
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUtc("2024-03-17T14:30:45+00:00[UTC]", "en-US") // "2 years ago"
- * @example formatRelativeUtc(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
+ * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"
+ * @example formatRelativeUtc("2026-01-15T00:00:00Z", "en-US", { reference: "2026-01-15T10:30:00Z", roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUtc("2026-01-15T00:00:00Z", "en-US", { reference: "2026-01-15T00:30:00Z", timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", null as never) // ""
  * @example formatRelativeUtc("not-a-date") // ""
+ * @example formatRelativeUtc("2024-03-15T11:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00Z" }) // "il y a 30 minutes"
  */
 export function formatRelativeUtc(value, locale, options = {}) {
-    if (!isValidUtc(value))
-        return "";
-    if (options.reference !== undefined && !isValidUtc(options.reference))
-        return "";
-    const target = toInstantFromUtc(value);
-    if (target === null)
-        return "";
-    let reference;
-    if (options.reference) {
-        const ref = toInstantFromUtc(options.reference);
-        if (ref === null)
+    try {
+        // Temporal GetOptionsObject: undefined is defaults (the parameter default); anything else that is
+        // not an object, including null, is a TypeError.
+        if (options === null || typeof options !== "object")
             return "";
-        reference = ref;
-    }
-    else {
-        try {
-            reference = Temporal.Now.instant();
-        }
-        catch {
+        if (!isValidUtc(value))
+            return "";
+        const tz = normalizeTimeZone(options.timeZone);
+        if (!tz)
+            return "";
+        if (options.reference !== undefined && !isValidUtc(options.reference))
+            return "";
+        const target = toInstantFromUtc(value);
+        if (target === null)
+            return "";
+        const reference = toReferenceInstantFromUtc(options.reference);
+        if (reference === null)
             return "";
-        }
-    }
-    try {
-        const diff = target.since(reference);
-        const absSeconds = Math.abs(diff.total("second"));
-        const unit = options.largestUnit ??
-            AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ??
-            "day";
-        let amount;
         try {
-            amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+            const diff = target.since(reference);
+            // Only a calendrical unit (month, year) reads the anchor, so the zone is applied lazily.
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, reference.toZonedDateTimeISO(tz)));
         }
         catch {
-            // month/year are calendrical and need a relativeTo anchor.
-            // Defer timezone normalization until we know we need it.
-            const tz = normalizeTimeZone(options.timeZone);
-            amount = resolveRelativeRounding(diff.total({ unit, relativeTo: reference.toZonedDateTimeISO(tz) }), options.roundingMethod);
+            return "";
         }
-        return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-            numeric: options.numeric ?? "auto",
-            style: options.style ?? "long",
-        }).format(amount, unit));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/format/formatUtc.d.ts

@@ -7,7 +7,7 @@
  *
  * | Member | Type | Default | Description |
  * | --- | --- | --- | --- |
- * | `timeZone` | `string` | `"UTC"` | IANA zone for rendering; invalid/omitted falls back to UTC via `normalizeTimeZone`. |
+ * | `timeZone` | `string` | `"UTC"` | IANA zone for rendering; omitted is UTC, `"local"` is the system zone, and an unknown zone makes `formatUtc` return `""`. |
  * | `includeTimeZoneName` | `boolean` | `false` | Appends the localized zone name (style via `Intl`) when true. |
  *
  * @example
@@ -24,15 +24,32 @@ export interface FormatUtcOptions extends Intl.DateTimeFormatOptions {
  * - Returns `""` if the input is not a valid UTC string.
  * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
  * - `includeTimeZoneName` appends the localized timezone name when true.
+ * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
+ *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
+ *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
+ *   and `era` alone still gets the date and time defaults.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
+ *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
+ *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
  *
  * @param value UTC ISO string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { timeZone, includeTimeZoneName }
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
  * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York" }) // "3/16/2026, 2:30:00 PM"
  * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", includeTimeZoneName: true }) // "3/16/2026, 2:30:00 PM EDT"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZoneName: "short" }) // "2/3/2024, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZone: "Europe/Londn" }) // "" (unknown zone)
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  * @example formatUtc("not-a-date") // ""
+ * @example formatUtc("2024-02-03T14:30:45Z", ["fr-FR", "en-US"], { dateStyle: "long" }) // "3 février 2024"
  */
-export declare function formatUtc(value: string, locale?: string, options?: FormatUtcOptions): string;
+export declare function formatUtc(value: string, locale?: string | string[], options?: FormatUtcOptions): string;

package/dist/utc/format/formatUtc.js

@@ -1,3 +1,5 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
+import { formatWallClockOrZoned } from "../../internal/instantFormatOptions.js";
 import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { toInstantFromUtc } from "../../internal/toInstantFromUtc.js";
@@ -8,33 +10,60 @@ import { isValidUtc } from "../validate/index.js";
  * - Returns `""` if the input is not a valid UTC string.
  * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
  * - `includeTimeZoneName` appends the localized timezone name when true.
+ * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
+ *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
+ *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
+ *   and `era` alone still gets the date and time defaults.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
+ *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
+ *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
  *
  * @param value UTC ISO string to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { timeZone, includeTimeZoneName }
  * @returns the formatted date/time string, or "" on invalid input
  *
  * @example formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"
  * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York" }) // "3/16/2026, 2:30:00 PM"
  * @example formatUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", includeTimeZoneName: true }) // "3/16/2026, 2:30:00 PM EDT"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUtc("2024-02-03T14:30:45Z", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZoneName: "short" }) // "2/3/2024, 2:30:45 PM"
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", { timeZone: "Europe/Londn" }) // "" (unknown zone)
+ * @example formatUtc("2024-02-03T14:30:45Z", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  * @example formatUtc("not-a-date") // ""
+ * @example formatUtc("2024-02-03T14:30:45Z", ["fr-FR", "en-US"], { dateStyle: "long" }) // "3 février 2024"
  */
 export function formatUtc(value, locale, options) {
-    if (!isValidUtc(value))
-        return "";
-    const { timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
-    const instant = toInstantFromUtc(value);
-    if (instant === null)
-        return "";
     try {
+        // ECMA-402 CoerceOptionsToObject: undefined is defaults; null is a TypeError.
+        if (options === null)
+            return "";
+        if (!isValidUtc(value))
+            return "";
+        const { timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        const instant = toInstantFromUtc(value);
+        if (instant === null)
+            return "";
+        // ECMA-402 throws RangeError for an unknown zone: the sentinel, never a silent UTC.
         const tz = normalizeTimeZone(timeZone);
-        const zdt = instant.toZonedDateTimeISO(tz);
-        const out = includeTimeZoneName
-            ? zdt.toLocaleString(locale, intlOptions)
-            : zdt.toPlainDateTime().toLocaleString(locale, intlOptions);
-        return normalizeDateTime(out);
+        if (!tz)
+            return "";
+        try {
+            const zdt = instant.toZonedDateTimeISO(tz);
+            return normalizeDateTime(formatWallClockOrZoned(zdt, locale, intlOptions, includeTimeZoneName));
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/get/getUtcNowUnit.d.ts

@@ -5,6 +5,8 @@ export type { UtcNowUnit };
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
  * - Uses Temporal.Now.instant() converted to UTC.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  * - Returns "" on invalid unit or failure.
  *
  * @param unit unit to extract from current utc instant
@@ -12,6 +14,7 @@ export type { UtcNowUnit };
  *
  * @example getUtcNowUnit("year") // "2024"
  * @example getUtcNowUnit("month") // "02"
+ * @example getUtcNowUnit("hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getUtcNowUnit("invalid") // ""
  */
 export declare function getUtcNowUnit(unit: UtcNowUnit): string;

package/dist/utc/get/getUtcNowUnit.js

@@ -1,5 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoWeekOfYear, zonedNowUnitValue, } from "../../internal/zonedNowUnitValue.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 function isValidUtcNowUnit(unit) {
     return isValidDateTimeUnit(unit) || ["dayOfWeek"].includes(unit);
 }
@@ -8,6 +10,8 @@ function isValidUtcNowUnit(unit) {
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
  * - Uses Temporal.Now.instant() converted to UTC.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  * - Returns "" on invalid unit or failure.
  *
  * @param unit unit to extract from current utc instant
@@ -15,45 +19,19 @@ function isValidUtcNowUnit(unit) {
  *
  * @example getUtcNowUnit("year") // "2024"
  * @example getUtcNowUnit("month") // "02"
+ * @example getUtcNowUnit("hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getUtcNowUnit("invalid") // ""
  */
 export function getUtcNowUnit(unit) {
-    if (!isValidUtcNowUnit(String(unit ?? "")))
+    if (typeof unit !== "string") {
+        return "";
+    }
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidUtcNowUnit(resolvedUnit))
         return "";
     try {
         const now = Temporal.Now.instant().toZonedDateTimeISO("UTC");
-        const plainDateTime = now.toPlainDateTime();
-        const plainDate = Temporal.PlainDate.from({
-            year: plainDateTime.year,
-            month: plainDateTime.month,
-            day: plainDateTime.day,
-        });
-        switch (unit) {
-            case "year":
-                return plainDateTime.year.toString();
-            case "month":
-                return plainDateTime.month.toString().padStart(2, "0");
-            case "week":
-                return (plainDate.weekOfYear ?? 0).toString();
-            case "day":
-                return plainDateTime.day.toString().padStart(2, "0");
-            case "dayOfWeek":
-                return now.dayOfWeek.toString();
-            case "hour":
-                return plainDateTime.hour.toString().padStart(2, "0");
-            case "minute":
-                return plainDateTime.minute.toString().padStart(2, "0");
-            case "second":
-                return plainDateTime.second.toString().padStart(2, "0");
-            case "millisecond":
-                return plainDateTime.millisecond.toString().padStart(3, "0");
-            case "microsecond":
-                return (plainDateTime.microsecond ?? 0).toString().padStart(3, "0");
-            case "nanosecond":
-                return (plainDateTime.nanosecond ?? 0).toString().padStart(3, "0");
-            default:
-                return "";
-        }
+        return zonedNowUnitValue(now, resolvedUnit, isoWeekOfYear);
     }
     catch {
         return "";

package/dist/utc/index.d.ts

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

package/dist/utc/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 "./chop/index.js";
 export * from "./compare/index.js";

package/dist/utc/interval/intervalAbutsUtc.d.ts

@@ -1,9 +1,12 @@
 /**
- * Return true when two UTC intervals are exactly adjacent — one's end equals the other's
- * start with zero gap and zero overlap.
+ * Return true when two half-open UTC intervals `[aStart, aEnd)` and `[bStart, bEnd)` are exactly
+ * adjacent — one ends where the other starts, so they share nothing and leave no gap.
  *
+ * - Half-open: an interval holds every `t` with `start <= t < end`, so an interval's `end` is the
+ *   first value after it. Returns `true` when `aEnd === bStart` or `bEnd === aStart` (Allen's
+ *   "meets"). There is no one-nanosecond step: a one-nanosecond gap is a gap.
+ * - An empty interval (`start === end`) abuts nothing.
  * - Uses `Temporal.Instant.compare` for comparison.
- * - Returns `true` when `aEnd + 1 nanosecond === bStart` or `bEnd + 1 nanosecond === aStart`.
  * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
  * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
  *
@@ -13,10 +16,10 @@
  * @param bEnd ISO 8601 UTC datetime string for the second interval end
  * @returns true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z", "2024-06-30T12:00:00.000000001Z", "2024-12-31T17:00:00Z") // true
- * @example intervalAbutsUtc("2024-06-30T12:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-06-30T12:00:00.000000001Z") // true
- * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z", "2024-06-30T12:00:01Z", "2024-12-31T17:00:00Z") // false (gap)
- * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-06-30T13:00:00Z", "2024-06-30T12:00:00Z", "2024-12-31T17:00:00Z") // false (overlap)
+ * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // true
+ * @example intervalAbutsUtc("2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z") // true
+ * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00.000000001Z", "2024-01-01T17:00:00Z") // false (1 ns gap)
+ * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // false (overlap)
  * @example intervalAbutsUtc("invalid", "2024-06-30T12:00:00Z", "2024-06-30T12:00:00Z", "2024-12-31T17:00:00Z") // false
  */
 export declare function intervalAbutsUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/utc/interval/intervalAbutsUtc.js

@@ -1,12 +1,16 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { halfOpenAbuts } from "../../internal/index.js";
+import { isValidUtc } from "../validate/index.js";
 /**
- * Return true when two UTC intervals are exactly adjacent — one's end equals the other's
- * start with zero gap and zero overlap.
+ * Return true when two half-open UTC intervals `[aStart, aEnd)` and `[bStart, bEnd)` are exactly
+ * adjacent — one ends where the other starts, so they share nothing and leave no gap.
  *
+ * - Half-open: an interval holds every `t` with `start <= t < end`, so an interval's `end` is the
+ *   first value after it. Returns `true` when `aEnd === bStart` or `bEnd === aStart` (Allen's
+ *   "meets"). There is no one-nanosecond step: a one-nanosecond gap is a gap.
+ * - An empty interval (`start === end`) abuts nothing.
  * - Uses `Temporal.Instant.compare` for comparison.
- * - Returns `true` when `aEnd + 1 nanosecond === bStart` or `bEnd + 1 nanosecond === aStart`.
  * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
  * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
  *
@@ -16,10 +20,10 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @param bEnd ISO 8601 UTC datetime string for the second interval end
  * @returns true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z", "2024-06-30T12:00:00.000000001Z", "2024-12-31T17:00:00Z") // true
- * @example intervalAbutsUtc("2024-06-30T12:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-06-30T12:00:00.000000001Z") // true
- * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z", "2024-06-30T12:00:01Z", "2024-12-31T17:00:00Z") // false (gap)
- * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-06-30T13:00:00Z", "2024-06-30T12:00:00Z", "2024-12-31T17:00:00Z") // false (overlap)
+ * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // true
+ * @example intervalAbutsUtc("2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z") // true
+ * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00.000000001Z", "2024-01-01T17:00:00Z") // false (1 ns gap)
+ * @example intervalAbutsUtc("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // false (overlap)
  * @example intervalAbutsUtc("invalid", "2024-06-30T12:00:00Z", "2024-06-30T12:00:00Z", "2024-12-31T17:00:00Z") // false
  */
 export function intervalAbutsUtc(aStart, aEnd, bStart, bEnd) {
@@ -29,16 +33,10 @@ export function intervalAbutsUtc(aStart, aEnd, bStart, bEnd) {
         typeof bEnd !== "string") {
         return false;
     }
-    if (!utcDateTime.test(aStart) ||
-        !utcDateTime.test(aEnd) ||
-        !utcDateTime.test(bStart) ||
-        !utcDateTime.test(bEnd)) {
-        return false;
-    }
-    if (isLeapSecond(aStart) ||
-        isLeapSecond(aEnd) ||
-        isLeapSecond(bStart) ||
-        isLeapSecond(bEnd)) {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return false;
     }
     try {
@@ -52,17 +50,7 @@ export function intervalAbutsUtc(aStart, aEnd, bStart, bEnd) {
         if (Temporal.Instant.compare(bS, bE) > 0) {
             return false;
         }
-        // aEnd + 1 nanosecond === bStart
-        const aEndPlusOne = aE.add({ nanoseconds: 1 });
-        if (Temporal.Instant.compare(aEndPlusOne, bS) === 0) {
-            return true;
-        }
-        // bEnd + 1 nanosecond === aStart
-        const bEndPlusOne = bE.add({ nanoseconds: 1 });
-        if (Temporal.Instant.compare(bEndPlusOne, aS) === 0) {
-            return true;
-        }
-        return false;
+        return halfOpenAbuts({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.Instant.compare);
     }
     catch {
         return false;

package/dist/utc/interval/intervalContainsUtc.d.ts

@@ -1,23 +1,31 @@
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` lies in the half-open interval `[intervalStart, intervalEnd)`
+ * (3-arg), or when the inner interval `[innerStart, innerEnd)` lies within it (4-arg).
  *
- * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Half-open: an interval holds every instant `t` with `start <= t < end`, so `intervalEnd` itself is
+ *   outside (the rule CORE-6's `intervalContains` uses). An empty interval (`start === end`)
+ *   contains no point.
+ * - 4-arg: the inner interval must start at or after `intervalStart`, end at or before
+ *   `intervalEnd`, and overlap the outer interval. An empty inner interval therefore counts only
+ *   strictly inside, never at an edge (CORE-6's `clampInterval` clamps it away there).
+ * - The 3-argument form delegates to CORE-6's `intervalContains` once the arguments pass the
+ *   UTC-string gate.
+ * - Uses `Temporal.Instant.compare` for comparison.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
- * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `false` on invalid input (wrong type, non-`Z` strings, malformed strings, leap seconds).
  *
  * @param intervalStart ISO 8601 UTC datetime string for the outer interval start
- * @param intervalEnd ISO 8601 UTC datetime string for the outer interval end
+ * @param intervalEnd ISO 8601 UTC datetime string for the outer interval end (excluded)
  * @param pointOrStart ISO 8601 UTC datetime string for the point (3-arg) or inner start (4-arg)
  * @param pointEnd optional ISO 8601 UTC datetime string for the inner interval end (4-arg mode)
  * @returns true if the point or inner interval is contained, or false on invalid input
  *
- * @example intervalContainsUtc("2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z", "2024-06-15T12:00:00Z") // true
- * @example intervalContainsUtc("2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z", "2024-06-15T12:00:00Z", "2024-07-15T12:00:00Z") // true
- * @example intervalContainsUtc("2024-12-31T23:59:59Z", "2024-01-01T00:00:00Z", "2024-06-15T12:00:00Z") // false
- * @example intervalContainsUtc("invalid", "2024-12-31T23:59:59Z", "2024-06-15T12:00:00Z") // false
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z") // true
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T16:59:59.999999999Z") // true (last value before the end)
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z") // false (end is excluded)
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // true (inner shares the end)
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z") // false (empty interval at the edge)
+ * @example intervalContainsUtc("2024-01-01T17:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z") // false (reversed interval)
  */
 export declare function intervalContainsUtc(intervalStart: string, intervalEnd: string, pointOrStart: string, pointEnd?: string): boolean;

package/dist/utc/interval/intervalContainsUtc.js

@@ -1,27 +1,36 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { halfOpenContainsSpan } from "../../internal/index.js";
+import { intervalContains } from "../../interval/compare/index.js";
+import { isValidUtc } from "../validate/index.js";
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` lies in the half-open interval `[intervalStart, intervalEnd)`
+ * (3-arg), or when the inner interval `[innerStart, innerEnd)` lies within it (4-arg).
  *
- * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Half-open: an interval holds every instant `t` with `start <= t < end`, so `intervalEnd` itself is
+ *   outside (the rule CORE-6's `intervalContains` uses). An empty interval (`start === end`)
+ *   contains no point.
+ * - 4-arg: the inner interval must start at or after `intervalStart`, end at or before
+ *   `intervalEnd`, and overlap the outer interval. An empty inner interval therefore counts only
+ *   strictly inside, never at an edge (CORE-6's `clampInterval` clamps it away there).
+ * - The 3-argument form delegates to CORE-6's `intervalContains` once the arguments pass the
+ *   UTC-string gate.
+ * - Uses `Temporal.Instant.compare` for comparison.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
- * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `false` on invalid input (wrong type, non-`Z` strings, malformed strings, leap seconds).
  *
  * @param intervalStart ISO 8601 UTC datetime string for the outer interval start
- * @param intervalEnd ISO 8601 UTC datetime string for the outer interval end
+ * @param intervalEnd ISO 8601 UTC datetime string for the outer interval end (excluded)
  * @param pointOrStart ISO 8601 UTC datetime string for the point (3-arg) or inner start (4-arg)
  * @param pointEnd optional ISO 8601 UTC datetime string for the inner interval end (4-arg mode)
  * @returns true if the point or inner interval is contained, or false on invalid input
  *
- * @example intervalContainsUtc("2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z", "2024-06-15T12:00:00Z") // true
- * @example intervalContainsUtc("2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z", "2024-06-15T12:00:00Z", "2024-07-15T12:00:00Z") // true
- * @example intervalContainsUtc("2024-12-31T23:59:59Z", "2024-01-01T00:00:00Z", "2024-06-15T12:00:00Z") // false
- * @example intervalContainsUtc("invalid", "2024-12-31T23:59:59Z", "2024-06-15T12:00:00Z") // false
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z") // true
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T16:59:59.999999999Z") // true (last value before the end)
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z") // false (end is excluded)
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // true (inner shares the end)
+ * @example intervalContainsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z") // false (empty interval at the edge)
+ * @example intervalContainsUtc("2024-01-01T17:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z") // false (reversed interval)
  */
 export function intervalContainsUtc(intervalStart, intervalEnd, pointOrStart, pointEnd) {
     if (typeof intervalStart !== "string" ||
@@ -30,35 +39,25 @@ export function intervalContainsUtc(intervalStart, intervalEnd, pointOrStart, po
         (pointEnd !== undefined && typeof pointEnd !== "string")) {
         return false;
     }
-    if (!utcDateTime.test(intervalStart) ||
-        !utcDateTime.test(intervalEnd) ||
-        !utcDateTime.test(pointOrStart) ||
-        (pointEnd !== undefined && !utcDateTime.test(pointEnd))) {
+    if (!isValidUtc(intervalStart) ||
+        !isValidUtc(intervalEnd) ||
+        !isValidUtc(pointOrStart) ||
+        (pointEnd !== undefined && !isValidUtc(pointEnd))) {
         return false;
     }
-    if (isLeapSecond(intervalStart) ||
-        isLeapSecond(intervalEnd) ||
-        isLeapSecond(pointOrStart) ||
-        (pointEnd !== undefined && isLeapSecond(pointEnd))) {
-        return false;
+    if (pointEnd === undefined) {
+        return intervalContains({ start: intervalStart, end: intervalEnd }, pointOrStart);
     }
     try {
         const startInstant = Temporal.Instant.from(intervalStart);
         const endInstant = Temporal.Instant.from(intervalEnd);
-        const pointInstant = Temporal.Instant.from(pointOrStart);
-        if (Temporal.Instant.compare(startInstant, endInstant) > 0) {
-            return false;
-        }
-        if (pointEnd === undefined) {
-            return (Temporal.Instant.compare(startInstant, pointInstant) <= 0 &&
-                Temporal.Instant.compare(pointInstant, endInstant) <= 0);
-        }
-        const endPointInstant = Temporal.Instant.from(pointEnd);
-        if (Temporal.Instant.compare(pointInstant, endPointInstant) > 0) {
+        const innerStartInstant = Temporal.Instant.from(pointOrStart);
+        const innerEndInstant = Temporal.Instant.from(pointEnd);
+        if (Temporal.Instant.compare(startInstant, endInstant) > 0 ||
+            Temporal.Instant.compare(innerStartInstant, innerEndInstant) > 0) {
             return false;
         }
-        return (Temporal.Instant.compare(startInstant, pointInstant) <= 0 &&
-            Temporal.Instant.compare(endPointInstant, endInstant) <= 0);
+        return halfOpenContainsSpan({ start: startInstant, end: endInstant }, { start: innerStartInstant, end: innerEndInstant }, Temporal.Instant.compare);
     }
     catch {
         return false;