@northguild/gmt 1.14.2 → 1.16.0

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

@@ -1,10 +1,12 @@
-import type { DateTimeUnit } from "../../types/index.js";
-type UtcNowUnit = DateTimeUnit | "dayOfWeek";
+import type { UtcNowUnit } from "../../types/index.js";
+export type { UtcNowUnit };
 /**
  * Return the requested unit value from the current UTC instant.
  *
  * - 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,7 +14,7 @@ type UtcNowUnit = DateTimeUnit | "dayOfWeek";
  *
  * @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;
-export {};

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;

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

@@ -5,8 +5,8 @@
  *   from `diffUtc`, which measures exact elapsed duration. An interval from 23:59 to 00:01 is
  *   two minutes long but touches 2 day boundaries.
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary.
+ * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
+ *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
  * - Boundaries are UTC boundaries — no DST is involved.
  * - Weeks start on Monday (ISO 8601).
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
@@ -21,8 +21,7 @@
  * @example intervalCountUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 2
  * @example intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-03T00:00:00Z", "day") // 2
  * @example intervalCountUtc("2024-01-15T00:00:00Z", "2024-03-10T00:00:00Z", "month") // 3
- * @example intervalCountUtc("2024-01-01T05:00:00Z", "2024-01-01T05:00:00Z", "day") // 1 (zero-length, mid-day)
- * @example intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0 (zero-length, on the boundary)
+ * @example intervalCountUtc("2024-01-01T05:00:00Z", "2024-01-01T05:00:00Z", "day") // 0 (zero-length: holds no instant)
  * @example intervalCountUtc("invalid", "2024-01-02T00:00:00Z", "day") // null
  */
 export declare function intervalCountUtc(start: string, end: string, unit: string): number | null;

package/dist/utc/interval/intervalCountUtc.js

@@ -1,8 +1,7 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { getStartOfZonedUnit, getUnitSpan, resolveDateTimeUnit, } from "../../internal/index.js";
+import { countZonedBuckets, resolveDateTimeUnit } from "../../internal/index.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 /**
  * Count how many `unit` boundaries a UTC interval crosses.
@@ -11,8 +10,8 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  *   from `diffUtc`, which measures exact elapsed duration. An interval from 23:59 to 00:01 is
  *   two minutes long but touches 2 day boundaries.
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary.
+ * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
+ *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
  * - Boundaries are UTC boundaries — no DST is involved.
  * - Weeks start on Monday (ISO 8601).
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
@@ -27,20 +26,13 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example intervalCountUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 2
  * @example intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-03T00:00:00Z", "day") // 2
  * @example intervalCountUtc("2024-01-15T00:00:00Z", "2024-03-10T00:00:00Z", "month") // 3
- * @example intervalCountUtc("2024-01-01T05:00:00Z", "2024-01-01T05:00:00Z", "day") // 1 (zero-length, mid-day)
- * @example intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0 (zero-length, on the boundary)
+ * @example intervalCountUtc("2024-01-01T05:00:00Z", "2024-01-01T05:00:00Z", "day") // 0 (zero-length: holds no instant)
  * @example intervalCountUtc("invalid", "2024-01-02T00:00:00Z", "day") // null
  */
 export function intervalCountUtc(start, end, unit) {
     if (typeof start !== "string" || typeof end !== "string") {
         return null;
     }
-    if (!utcDateTime.test(start) || !utcDateTime.test(end)) {
-        return null;
-    }
-    if (isLeapSecond(start) || isLeapSecond(end)) {
-        return null;
-    }
     if (!isValidUtc(start) || !isValidUtc(end)) {
         return null;
     }
@@ -54,13 +46,15 @@ export function intervalCountUtc(start, end, unit) {
     try {
         const startVal = Temporal.Instant.from(start).toZonedDateTimeISO("UTC");
         const endVal = Temporal.Instant.from(end).toZonedDateTimeISO("UTC");
-        if (Temporal.ZonedDateTime.compare(startVal, endVal) > 0) {
+        const order = Temporal.ZonedDateTime.compare(startVal, endVal);
+        if (order > 0) {
             return null;
         }
-        const startOfStart = getStartOfZonedUnit(startVal, resolvedUnit);
-        const startOfEnd = getStartOfZonedUnit(endVal, resolvedUnit);
-        const spanned = getUnitSpan(startOfStart.until(startOfEnd, { largestUnit: resolvedUnit }), resolvedUnit);
-        return spanned + (startOfEnd.equals(endVal) ? 0 : 1);
+        // An empty interval [t, t) holds no instant, so it touches no unit (CORE-6 empty-interval rule).
+        if (order === 0) {
+            return 0;
+        }
+        return countZonedBuckets(startVal, endVal, resolvedUnit);
     }
     catch {
         return null;

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

@@ -1,12 +1,19 @@
 /**
  * Return the portion(s) of interval A not covered by interval B.
  *
- * - Uses `Temporal.Instant.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one unit.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - Delegates to CORE-6's `subtractIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the pieces to canonical `Z` strings.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns A unchanged when B lies entirely before or after it.
  * - Returns `[]` if either interval is invalid (`start > end`).
- * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `[]` on invalid input (wrong type, non-`Z` strings, malformed strings, leap seconds).
  *
  * @param aStart ISO 8601 UTC datetime string for the first interval start
  * @param aEnd ISO 8601 UTC datetime string for the first interval end
@@ -14,7 +21,8 @@
  * @param bEnd ISO 8601 UTC datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-05-31T17:00:00Z" }, { start: "2024-07-01T13:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }] (touching B removes nothing)
  * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // []
  * @example intervalDifferenceUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // []
  */

package/dist/utc/interval/intervalDifferenceUtc.js

@@ -1,15 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { canonicalInstantIntervals } from "../../internal/index.js";
+import { subtractIntervals } from "../../interval/calculate/index.js";
+import { isValidUtc } from "../validate/index.js";
 /**
  * Return the portion(s) of interval A not covered by interval B.
  *
- * - Uses `Temporal.Instant.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one unit.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - Delegates to CORE-6's `subtractIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the pieces to canonical `Z` strings.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns A unchanged when B lies entirely before or after it.
  * - Returns `[]` if either interval is invalid (`start > end`).
- * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `[]` on invalid input (wrong type, non-`Z` strings, malformed strings, leap seconds).
  *
  * @param aStart ISO 8601 UTC datetime string for the first interval start
  * @param aEnd ISO 8601 UTC datetime string for the first interval end
@@ -17,7 +25,8 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @param bEnd ISO 8601 UTC datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-05-31T17:00:00Z" }, { start: "2024-07-01T13:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }] (touching B removes nothing)
  * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // []
  * @example intervalDifferenceUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // []
  */
@@ -28,49 +37,14 @@ export function intervalDifferenceUtc(aStart, aEnd, bStart, bEnd) {
         typeof bEnd !== "string") {
         return [];
     }
-    if (!utcDateTime.test(aStart) ||
-        !utcDateTime.test(aEnd) ||
-        !utcDateTime.test(bStart) ||
-        !utcDateTime.test(bEnd)) {
-        return [];
-    }
-    if (isLeapSecond(aStart) ||
-        isLeapSecond(aEnd) ||
-        isLeapSecond(bStart) ||
-        isLeapSecond(bEnd)) {
-        return [];
-    }
-    try {
-        const aS = Temporal.Instant.from(aStart);
-        const aE = Temporal.Instant.from(aEnd);
-        const bS = Temporal.Instant.from(bStart);
-        const bE = Temporal.Instant.from(bEnd);
-        if (Temporal.Instant.compare(aS, aE) > 0) {
-            return [];
-        }
-        if (Temporal.Instant.compare(bS, bE) > 0) {
-            return [];
-        }
-        const result = [];
-        // Left piece: A before B starts
-        if (Temporal.Instant.compare(aS, bS) < 0) {
-            const leftEnd = Temporal.Instant.compare(aE, bS) < 0
-                ? aE
-                : bS.subtract({ nanoseconds: 1 });
-            if (Temporal.Instant.compare(leftEnd, aS) >= 0) {
-                result.push({ start: aS.toString(), end: leftEnd.toString() });
-            }
-        }
-        // Right piece: A after B ends
-        if (Temporal.Instant.compare(aE, bE) > 0) {
-            result.push({
-                start: bE.add({ nanoseconds: 1 }).toString(),
-                end: aE.toString(),
-            });
-        }
-        return result;
-    }
-    catch {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return [];
     }
+    // subtractIntervals returns [] for an invalid (reversed) interval, the same sentinel.
+    return (canonicalInstantIntervals(subtractIntervals({ start: aStart, end: aEnd }, [
+        { start: bStart, end: bEnd },
+    ])) ?? []);
 }