@northguild/gmt 1.15.0 → 1.16.0

package/dist/zoned/chop/chopZonedMilliseconds.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Returns the zoned datetime string rounded/truncated to second precision.
  *
@@ -16,7 +16,7 @@ export function chopZonedMilliseconds(value) {
     if (!isValidZonedDateTime(value))
         return "";
     try {
-        return Temporal.ZonedDateTime.from(value).toString({
+        return zonedDateTimeFrom(value).toString({
             smallestUnit: "second",
         });
     }

package/dist/zoned/chop/chopZonedSeconds.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Returns the zoned datetime string truncated to minute precision.
  *
@@ -16,7 +16,7 @@ export function chopZonedSeconds(value) {
     if (!isValidZonedDateTime(value))
         return "";
     try {
-        return Temporal.ZonedDateTime.from(value).toString({
+        return zonedDateTimeFrom(value).toString({
             smallestUnit: "minute",
         });
     }

package/dist/zoned/chop/chopZonedTime.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extracts the local date portion from an ISO 8601 zoned datetime string.
  *
@@ -16,7 +16,7 @@ export function chopZonedTime(value) {
     if (!isValidZonedDateTime(value))
         return "";
     try {
-        return Temporal.ZonedDateTime.from(value).toPlainDate().toString();
+        return zonedDateTimeFrom(value).toPlainDate().toString();
     }
     catch {
         return "";

package/dist/zoned/chop/chopZonedTimezone.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Returns the local plain datetime (date + time) extracted from a zoned datetime string.
  *
@@ -16,7 +16,7 @@ export function chopZonedTimezone(value) {
     if (!isValidZonedDateTime(value))
         return "";
     try {
-        return Temporal.ZonedDateTime.from(value).toPlainDateTime().toString();
+        return zonedDateTimeFrom(value).toPlainDateTime().toString();
     }
     catch {
         return "";

package/dist/zoned/compare/areZonedEqual.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Compare two zoned datetime strings for exact local-field equality.
  *
@@ -21,8 +22,8 @@ export function areZonedEqual(value1, value2) {
     let zonedDateTime1;
     let zonedDateTime2;
     try {
-        zonedDateTime1 = Temporal.ZonedDateTime.from(value1);
-        zonedDateTime2 = Temporal.ZonedDateTime.from(value2);
+        zonedDateTime1 = zonedDateTimeFrom(value1);
+        zonedDateTime2 = zonedDateTimeFrom(value2);
     }
     catch {
         return false;

package/dist/zoned/compare/areZonedEqualBy.d.ts

@@ -1,3 +1,4 @@
+import { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeUnit } from "../../types/index.js";
 /**
  * Compare two zoned ISO datetime strings for equality at a given unit.
@@ -7,7 +8,17 @@ import type { DateTimeUnit } from "../../types/index.js";
  *   same instant can be "the same day" in one zone and a different day in
  *   another, and this function answers per each value's own zone, the way
  *   Luxon's `dt.hasSame(other, unit)` does for zoned `DateTime`s.
+ * - Each value's start-of-unit is its real local bucket (see `startOfZoned`), so a bucket a
+ *   zone transition shortened is still its own unit: in `Pacific/Chatham` on its 2024
+ *   spring-forward, 03:50 and 04:05 are different hours, because the 03:00 hour lasted only
+ *   from 03:45 to 04:00.
+ * - Two values in the same time zone are equal only when their bucket starts are the same
+ *   instant, as in `areUnixEqualBy`: both passes of New York's repeated 01:00 on its 2024
+ *   fall-back read the same wall clock but are different hours. Values in different zones are
+ *   compared by their buckets' local labels, since their instants never line up.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
+ * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
@@ -17,14 +28,16 @@ import type { DateTimeUnit } from "../../types/index.js";
  *
  * @param value1 first zoned ISO datetime string
  * @param value2 second zoned ISO datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
+ * @param unit date or time unit, singular or plural, to compare by
  * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
  * @returns true if both values share the same local start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "day") // true (both are local March 15 in their own zone)
+ * @example areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "days") // true (plural unit)
  * @example areZonedEqualBy("2024-03-15T23:30:00-04:00[America/New_York]", "2024-03-16T04:30:00+00:00[UTC]", "day") // false (same instant, different local calendar day per zone)
+ * @example areZonedEqualBy("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]", "hour") // false (both read 01:30, but they sit in the two different real 01:00 hours)
  * @example areZonedEqualBy("invalid", "2024-03-15T10:00:00-04:00[America/New_York]", "day") // false
  */
-export declare function areZonedEqualBy(value1: string, value2: string, unit: DateTimeUnit, optionsArg?: {
+export declare function areZonedEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<DateTimeUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/zoned/compare/areZonedEqualBy.js

@@ -2,6 +2,10 @@ import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
 import { startOfZoned } from "../calculate/startOfZoned.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two zoned ISO datetime strings for equality at a given unit.
  *
@@ -10,7 +14,17 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   same instant can be "the same day" in one zone and a different day in
  *   another, and this function answers per each value's own zone, the way
  *   Luxon's `dt.hasSame(other, unit)` does for zoned `DateTime`s.
+ * - Each value's start-of-unit is its real local bucket (see `startOfZoned`), so a bucket a
+ *   zone transition shortened is still its own unit: in `Pacific/Chatham` on its 2024
+ *   spring-forward, 03:50 and 04:05 are different hours, because the 03:00 hour lasted only
+ *   from 03:45 to 04:00.
+ * - Two values in the same time zone are equal only when their bucket starts are the same
+ *   instant, as in `areUnixEqualBy`: both passes of New York's repeated 01:00 on its 2024
+ *   fall-back read the same wall clock but are different hours. Values in different zones are
+ *   compared by their buckets' local labels, since their instants never line up.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
+ * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
@@ -20,30 +34,49 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *
  * @param value1 first zoned ISO datetime string
  * @param value2 second zoned ISO datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
+ * @param unit date or time unit, singular or plural, to compare by
  * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
  * @returns true if both values share the same local start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "day") // true (both are local March 15 in their own zone)
+ * @example areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "days") // true (plural unit)
  * @example areZonedEqualBy("2024-03-15T23:30:00-04:00[America/New_York]", "2024-03-16T04:30:00+00:00[UTC]", "day") // false (same instant, different local calendar day per zone)
+ * @example areZonedEqualBy("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]", "hour") // false (both read 01:30, but they sit in the two different real 01:00 hours)
  * @example areZonedEqualBy("invalid", "2024-03-15T10:00:00-04:00[America/New_York]", "day") // false
  */
 export function areZonedEqualBy(value1, value2, unit, optionsArg) {
-    if (!isValidZonedDateTime(value1) ||
-        !isValidZonedDateTime(value2) ||
-        !isValidDateTimeUnit(unit)) {
-        return false;
-    }
     try {
-        const start1 = startOfZoned(value1, unit, optionsArg);
-        const start2 = startOfZoned(value2, unit, optionsArg);
-        if (start1 === "" || start2 === "")
+        if (!isOptionsArgument(optionsArg)) {
+            return false;
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (!isValidZonedDateTime(value1) ||
+            !isValidZonedDateTime(value2) ||
+            !isValidDateTimeUnit(resolvedUnit) ||
+            weekStartsOn === null) {
+            return false;
+        }
+        try {
+            const start1 = startOfZoned(value1, resolvedUnit, { weekStartsOn });
+            const start2 = startOfZoned(value2, resolvedUnit, { weekStartsOn });
+            if (start1 === "" || start2 === "")
+                return false;
+            const zoned1 = zonedDateTimeFrom(start1);
+            const zoned2 = zonedDateTimeFrom(start2);
+            // Same zone: one real bucket is one instant, so a repeated wall clock is not a match.
+            if (zoned1.timeZoneId === zoned2.timeZoneId) {
+                return (Temporal.Instant.compare(zoned1.toInstant(), zoned2.toInstant()) === 0);
+            }
+            return (Temporal.PlainDateTime.compare(zoned1.toPlainDateTime(), zoned2.toPlainDateTime()) === 0);
+        }
+        catch {
             return false;
-        const local1 = Temporal.ZonedDateTime.from(start1).toPlainDateTime();
-        const local2 = Temporal.ZonedDateTime.from(start2).toPlainDateTime();
-        return Temporal.PlainDateTime.compare(local1, local2) === 0;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/zoned/compare/isAfterZoned.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return whether `value1` represents an instant strictly after `value2`.
  *
@@ -21,8 +22,8 @@ export function isAfterZoned(value1, value2) {
     let zonedDateTime1;
     let zonedDateTime2;
     try {
-        zonedDateTime1 = Temporal.ZonedDateTime.from(value1);
-        zonedDateTime2 = Temporal.ZonedDateTime.from(value2);
+        zonedDateTime1 = zonedDateTimeFrom(value1);
+        zonedDateTime2 = zonedDateTimeFrom(value2);
     }
     catch {
         return false;

package/dist/zoned/compare/isBeforeZoned.d.ts

@@ -9,7 +9,7 @@
  * @param value2 second zoned datetime string
  * @returns `true` if `value1` is before `value2`, otherwise `false`
  *
- * @example isBeforeZoned("2024-03-17T14:30:45-05:00[America/New_York]", "2024-03-17T15:30:45-05:00[America/New_York]") // true
+ * @example isBeforeZoned("2024-03-17T14:30:45-04:00[America/New_York]", "2024-03-17T15:30:45-04:00[America/New_York]") // true
  * @example isBeforeZoned("invalid", "2024-03-17T14:30:45-05:00[America/New_York]") // false
  */
 export declare function isBeforeZoned(value1: string, value2: string): boolean;

package/dist/zoned/compare/isBeforeZoned.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return whether `value1` represents an instant strictly before `value2`.
  *
@@ -11,7 +12,7 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @param value2 second zoned datetime string
  * @returns `true` if `value1` is before `value2`, otherwise `false`
  *
- * @example isBeforeZoned("2024-03-17T14:30:45-05:00[America/New_York]", "2024-03-17T15:30:45-05:00[America/New_York]") // true
+ * @example isBeforeZoned("2024-03-17T14:30:45-04:00[America/New_York]", "2024-03-17T15:30:45-04:00[America/New_York]") // true
  * @example isBeforeZoned("invalid", "2024-03-17T14:30:45-05:00[America/New_York]") // false
  */
 export function isBeforeZoned(value1, value2) {
@@ -21,8 +22,8 @@ export function isBeforeZoned(value1, value2) {
     let zonedDateTime1;
     let zonedDateTime2;
     try {
-        zonedDateTime1 = Temporal.ZonedDateTime.from(value1);
-        zonedDateTime2 = Temporal.ZonedDateTime.from(value2);
+        zonedDateTime1 = zonedDateTimeFrom(value1);
+        zonedDateTime2 = zonedDateTimeFrom(value2);
     }
     catch {
         return false;

package/dist/zoned/compare/isBetweenZoned.js

@@ -1,5 +1,8 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true when `zoned` is between `start` and `end` (inclusive by default).
  *
@@ -16,40 +19,54 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @example isBetweenZoned("invalid", "2024-02-29T11:00:00+00:00[UTC]", "2024-02-29T13:00:00+00:00[UTC]") // false
  */
 export function isBetweenZoned(zoned, start, end, options) {
-    const inclusiveStart = options?.inclusiveStart ?? true;
-    const inclusiveEnd = options?.inclusiveEnd ?? true;
-    if (!isValidZonedDateTime(zoned) ||
-        !isValidZonedDateTime(start) ||
-        !isValidZonedDateTime(end)) {
-        return false;
-    }
-    let zdt;
-    let startZdt;
-    let endZdt;
-    try {
-        zdt = Temporal.ZonedDateTime.from(zoned);
-        startZdt = Temporal.ZonedDateTime.from(start);
-        endZdt = Temporal.ZonedDateTime.from(end);
-    }
-    catch {
-        return false;
-    }
     try {
-        const startInstant = startZdt.toInstant();
-        const endInstant = endZdt.toInstant();
-        const zonedInstant = zdt.toInstant();
-        if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
+        // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
+        // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
+        // behaves here exactly as `0` and `""` already do.
+        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
+        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        if (!isValidZonedDateTime(zoned) ||
+            !isValidZonedDateTime(start) ||
+            !isValidZonedDateTime(end)) {
+            return false;
+        }
+        let zdt;
+        let startZdt;
+        let endZdt;
+        try {
+            zdt = zonedDateTimeFrom(zoned);
+            startZdt = zonedDateTimeFrom(start);
+            endZdt = zonedDateTimeFrom(end);
+        }
+        catch {
+            return false;
+        }
+        try {
+            const startInstant = startZdt.toInstant();
+            const endInstant = endZdt.toInstant();
+            const zonedInstant = zdt.toInstant();
+            if (Temporal.Instant.compare(startInstant, endInstant) === 1) {
+                return false;
+            }
+            const startCheck = inclusiveStart
+                ? Temporal.Instant.compare(startInstant, zonedInstant) <= 0
+                : Temporal.Instant.compare(startInstant, zonedInstant) < 0;
+            const endCheck = inclusiveEnd
+                ? Temporal.Instant.compare(zonedInstant, endInstant) <= 0
+                : Temporal.Instant.compare(zonedInstant, endInstant) < 0;
+            return startCheck && endCheck;
+        }
+        catch {
             return false;
         }
-        const startCheck = inclusiveStart
-            ? Temporal.Instant.compare(startInstant, zonedInstant) <= 0
-            : Temporal.Instant.compare(startInstant, zonedInstant) < 0;
-        const endCheck = inclusiveEnd
-            ? Temporal.Instant.compare(zonedInstant, endInstant) <= 0
-            : Temporal.Instant.compare(zonedInstant, endInstant) < 0;
-        return startCheck && endCheck;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/zoned/compare/isInDaylightSaving.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Check whether a zoned value's instant falls within daylight saving time.
  *
@@ -29,7 +29,7 @@ export function isInDaylightSaving(value) {
         return false;
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         const { timeZoneId: timeZone, year } = zonedDateTime;
         // Sample the zone's offset 6 months apart, within the same calendar year
         // as `value` (a zone's DST rules can change between years). DST always
@@ -41,7 +41,7 @@ export function isInDaylightSaving(value) {
         // fixed reference year, and doesn't attempt to detect a zone whose
         // standard offset itself changed permanently mid-year (rare, and H3
         // shares the same limitation).
-        const januaryOffsetNanoseconds = Temporal.ZonedDateTime.from({
+        const januaryOffsetNanoseconds = zonedDateTimeFrom({
             year,
             month: 1,
             day: 15,
@@ -50,7 +50,7 @@ export function isInDaylightSaving(value) {
             second: 0,
             timeZone,
         }).offsetNanoseconds;
-        const julyOffsetNanoseconds = Temporal.ZonedDateTime.from({
+        const julyOffsetNanoseconds = zonedDateTimeFrom({
             year,
             month: 7,
             day: 15,

package/dist/zoned/compare/isZonedBusinessDay.d.ts

@@ -6,10 +6,13 @@
  * - Locale-agnostic: no `Intl.Locale` lookup and no holiday calendar.
  * - Returns false if `value` is invalid.
  *
- * This is the timezone-aware complement to the plain `isBusinessDay`: both use
- * ISO Mon–Fri, but `isZonedBusinessDay` resolves the local day in the given
- * timezone (so a UTC instant that is Friday evening may be Saturday morning
- * in `Asia/Tokyo` and thus not a business day there).
+ * - Resolves the local day in the value's own timezone, so a UTC instant that is
+ *   Friday evening may be Saturday morning in `Asia/Tokyo` and thus not a business
+ *   day there.
+ * - Has no calendar parameter: the weekend is always Saturday–Sunday. It is not
+ *   the zoned form of the plain `isBusinessDay`, which takes a `BusinessCalendar`
+ *   (weekend days, holidays). For a Friday–Saturday weekend or holidays, convert
+ *   to a plain date and call `isBusinessDay` with a calendar.
  *
  * @param value ISO 8601 zoned datetime string
  * @returns true if `value` is a Monday–Friday business day, false on invalid input

package/dist/zoned/compare/isZonedBusinessDay.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return true when `value` falls on a Monday–Friday ISO business day in the given timezone.
  *
@@ -8,10 +8,13 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * - Locale-agnostic: no `Intl.Locale` lookup and no holiday calendar.
  * - Returns false if `value` is invalid.
  *
- * This is the timezone-aware complement to the plain `isBusinessDay`: both use
- * ISO Mon–Fri, but `isZonedBusinessDay` resolves the local day in the given
- * timezone (so a UTC instant that is Friday evening may be Saturday morning
- * in `Asia/Tokyo` and thus not a business day there).
+ * - Resolves the local day in the value's own timezone, so a UTC instant that is
+ *   Friday evening may be Saturday morning in `Asia/Tokyo` and thus not a business
+ *   day there.
+ * - Has no calendar parameter: the weekend is always Saturday–Sunday. It is not
+ *   the zoned form of the plain `isBusinessDay`, which takes a `BusinessCalendar`
+ *   (weekend days, holidays). For a Friday–Saturday weekend or holidays, convert
+ *   to a plain date and call `isBusinessDay` with a calendar.
  *
  * @param value ISO 8601 zoned datetime string
  * @returns true if `value` is a Monday–Friday business day, false on invalid input
@@ -25,7 +28,7 @@ export function isZonedBusinessDay(value) {
     if (!isValidZonedDateTime(value))
         return false;
     try {
-        const zoned = Temporal.ZonedDateTime.from(value);
+        const zoned = zonedDateTimeFrom(value);
         return zoned.dayOfWeek >= 1 && zoned.dayOfWeek <= 5;
     }
     catch {

package/dist/zoned/compare/isZonedFuture.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return true when `value` represents an instant strictly after now.
  *
@@ -22,7 +23,7 @@ export function isZonedFuture(value) {
         return false;
     }
     try {
-        const instant = Temporal.ZonedDateTime.from(value).toInstant();
+        const instant = zonedDateTimeFrom(value).toInstant();
         return Temporal.Instant.compare(instant, Temporal.Now.instant()) === 1;
     }
     catch {

package/dist/zoned/compare/isZonedPast.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return true when `value` represents an instant strictly before now.
  *
@@ -22,7 +23,7 @@ export function isZonedPast(value) {
         return false;
     }
     try {
-        const instant = Temporal.ZonedDateTime.from(value).toInstant();
+        const instant = zonedDateTimeFrom(value).toInstant();
         return Temporal.Instant.compare(instant, Temporal.Now.instant()) === -1;
     }
     catch {

package/dist/zoned/compare/isZonedRelativeDay.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return true when `value`'s local calendar day falls `offsetDays` days from
  * today in `value`'s own IANA timeZone.
@@ -29,7 +30,7 @@ export function isZonedRelativeDay(value, offsetDays) {
         return false;
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         const today = Temporal.Now.zonedDateTimeISO(zonedDateTime.timeZoneId).toPlainDate();
         const target = today.add({ days: offsetDays });
         return (Temporal.PlainDate.compare(zonedDateTime.toPlainDate(), target) === 0);

package/dist/zoned/compare/isZonedThisUnit.d.ts

@@ -13,16 +13,24 @@ import { Temporal } from "@js-temporal/polyfill";
  *   varies by locale. When `unit` is `"week"` and `locale` is given, the
  *   comparison uses `getLocaleStartOfWeek` instead of the ISO Monday-start
  *   default `areDatesEqualBy` otherwise uses.
- * - Returns false for an unsupported unit, invalid input, or an invalid locale.
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `locale` may be a BCP 47 tag or a preference list of tags (ECMA-402); the first tag with locale
+ *   data sets the week start.
+ * - Returns false for an unsupported unit or invalid input. The locale is validated for every
+ *   unit, so an invalid locale returns false for `"day"`, `"month"` and `"year"` too.
+ * - **Compatibility:** before 1.16.0 an invalid locale was ignored for every unit but `"week"`.
  *
  * @param value ISO ZonedDateTime string
- * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
- * @param locale optional BCP 47 locale tag — only affects the "week" case (e.g. "en-US", "fr-FR")
+ * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
+ * @param locale optional BCP 47 locale tag or preference list — sets the "week" start (e.g. "en-US", ["fr-FR", "en-US"])
  * @returns true if `value`'s local day falls in the same `unit` as today in its own timeZone, false on an unsupported unit or invalid input
  *
  * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "month") // true, if today is any day in March 2024 in America/New_York
  * @example isZonedThisUnit("2024-02-26T10:00:00+01:00[Europe/Paris]", "week", "fr-FR") // true, if today is 2024-03-01 in Europe/Paris (same fr-FR Monday-start week)
  * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "hour" as never) // false (unsupported unit)
  * @example isZonedThisUnit("invalid", "month") // false
+ * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "week", "not-a-locale-!!") // false (invalid locale)
+ * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "day", "not-a-locale-!!") // false (invalid locale, for every unit)
+ * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "months") // true, if today is any day in March 2024 in America/New_York
  */
-export declare function isZonedThisUnit(value: string, unit: Temporal.DateUnit, locale?: string): boolean;
+export declare function isZonedThisUnit(value: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, locale?: string | string[]): boolean;

package/dist/zoned/compare/isZonedThisUnit.js

@@ -3,6 +3,9 @@ import { getLocaleStartOfWeek } from "../../plain/calculate/getLocaleStartOfWeek
 import { areDatesEqualBy } from "../../plain/compare/areDatesEqualBy.js";
 import { isValidDateUnit } from "../../plain/validate/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveLocale } from "../../internal/resolveLocale.js";
 /**
  * Return true when `value`'s local calendar day falls in the same `unit` as
  * today, both resolved in `value`'s own IANA timeZone.
@@ -17,36 +20,54 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *   varies by locale. When `unit` is `"week"` and `locale` is given, the
  *   comparison uses `getLocaleStartOfWeek` instead of the ISO Monday-start
  *   default `areDatesEqualBy` otherwise uses.
- * - Returns false for an unsupported unit, invalid input, or an invalid locale.
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `locale` may be a BCP 47 tag or a preference list of tags (ECMA-402); the first tag with locale
+ *   data sets the week start.
+ * - Returns false for an unsupported unit or invalid input. The locale is validated for every
+ *   unit, so an invalid locale returns false for `"day"`, `"month"` and `"year"` too.
+ * - **Compatibility:** before 1.16.0 an invalid locale was ignored for every unit but `"week"`.
  *
  * @param value ISO ZonedDateTime string
- * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
- * @param locale optional BCP 47 locale tag — only affects the "week" case (e.g. "en-US", "fr-FR")
+ * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
+ * @param locale optional BCP 47 locale tag or preference list — sets the "week" start (e.g. "en-US", ["fr-FR", "en-US"])
  * @returns true if `value`'s local day falls in the same `unit` as today in its own timeZone, false on an unsupported unit or invalid input
  *
  * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "month") // true, if today is any day in March 2024 in America/New_York
  * @example isZonedThisUnit("2024-02-26T10:00:00+01:00[Europe/Paris]", "week", "fr-FR") // true, if today is 2024-03-01 in Europe/Paris (same fr-FR Monday-start week)
  * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "hour" as never) // false (unsupported unit)
  * @example isZonedThisUnit("invalid", "month") // false
+ * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "week", "not-a-locale-!!") // false (invalid locale)
+ * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "day", "not-a-locale-!!") // false (invalid locale, for every unit)
+ * @example isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "months") // true, if today is any day in March 2024 in America/New_York
  */
 export function isZonedThisUnit(value, unit, locale) {
-    if (!isValidZonedDateTime(value) || !isValidDateUnit(unit)) {
-        return false;
-    }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
-        const today = Temporal.Now.zonedDateTimeISO(zonedDateTime.timeZoneId)
-            .toPlainDate()
-            .toString();
-        const valueDate = zonedDateTime.toPlainDate().toString();
-        if (unit === "week" && locale !== undefined) {
-            const startOfWeekValue = getLocaleStartOfWeek(valueDate, locale);
-            const startOfWeekToday = getLocaleStartOfWeek(today, locale);
-            return startOfWeekValue !== "" && startOfWeekValue === startOfWeekToday;
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        if (!isValidZonedDateTime(value) ||
+            !isValidDateUnit(resolvedUnit) ||
+            (locale !== undefined && resolveLocale(locale) === null)) {
+            return false;
+        }
+        try {
+            const zonedDateTime = zonedDateTimeFrom(value);
+            const today = Temporal.Now.zonedDateTimeISO(zonedDateTime.timeZoneId)
+                .toPlainDate()
+                .toString();
+            const valueDate = zonedDateTime.toPlainDate().toString();
+            if (resolvedUnit === "week" && locale !== undefined) {
+                const startOfWeekValue = getLocaleStartOfWeek(valueDate, locale);
+                const startOfWeekToday = getLocaleStartOfWeek(today, locale);
+                return startOfWeekValue !== "" && startOfWeekValue === startOfWeekToday;
+            }
+            return areDatesEqualBy(valueDate, today, resolvedUnit);
+        }
+        catch {
+            return false;
         }
-        return areDatesEqualBy(valueDate, today, unit);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }