@northguild/gmt 1.14.2

package/dist/zoned/compare/isBetweenZoned.js

@@ -0,0 +1,55 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `zoned` is between `start` and `end` (inclusive by default).
+ *
+ * - Validates inputs and then compares using Temporal.Instant (same instant semantics).
+ * - Returns false for invalid inputs.
+ *
+ * @param zoned ISO ZonedDateTime string to check
+ * @param start ISO ZonedDateTime string for the start of the range
+ * @param end ISO ZonedDateTime string for the end of the range
+ * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @returns boolean indicating whether zoned is between start and end
+ *
+ * @example isBetweenZoned("2024-02-29T12:00:00+00:00[UTC]", "2024-02-29T11:00:00+00:00[UTC]", "2024-02-29T13:00:00+00:00[UTC]") // true
+ * @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) {
+            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;
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Check whether a zoned value's instant falls within daylight saving time.
+ *
+ * - The third DST-related function in the roadmap, and distinct from the
+ *   other two — see docs/dst-disambiguation.md for the full four-way split:
+ *   `hasDaylightSaving(timeZone)` asks whether a zone observes DST *at all*
+ *   (zone-level, no instant); `listDstTransitions(timeZone, year)` asks
+ *   *where* a zone's transitions fall (enumerates instants);
+ *   `isInDaylightSaving(value)` asks whether *this particular instant* is
+ *   currently in DST. `disambiguation`/`offset` (Group C) are a fourth,
+ *   orthogonal concern: what to do when construction lands on an ambiguous
+ *   or nonexistent instant.
+ * - Returns false for invalid input, and false for a zone that doesn't
+ *   observe DST at all.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns true if the instant is in daylight saving time, false otherwise or on invalid input
+ *
+ * @example isInDaylightSaving("2024-07-15T12:00:00-04:00[America/New_York]") // true
+ * @example isInDaylightSaving("2024-01-15T12:00:00-05:00[America/New_York]") // false
+ * @example isInDaylightSaving("2024-01-15T12:00:00+11:00[Australia/Sydney]") // true (southern-hemisphere summer)
+ * @example isInDaylightSaving("2024-07-15T12:00:00+09:00[Asia/Tokyo]") // false (Asia/Tokyo has no DST)
+ * @example isInDaylightSaving("invalid") // false
+ */
+export declare function isInDaylightSaving(value: string): boolean;

package/dist/zoned/compare/isInDaylightSaving.js

@@ -0,0 +1,68 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Check whether a zoned value's instant falls within daylight saving time.
+ *
+ * - The third DST-related function in the roadmap, and distinct from the
+ *   other two — see docs/dst-disambiguation.md for the full four-way split:
+ *   `hasDaylightSaving(timeZone)` asks whether a zone observes DST *at all*
+ *   (zone-level, no instant); `listDstTransitions(timeZone, year)` asks
+ *   *where* a zone's transitions fall (enumerates instants);
+ *   `isInDaylightSaving(value)` asks whether *this particular instant* is
+ *   currently in DST. `disambiguation`/`offset` (Group C) are a fourth,
+ *   orthogonal concern: what to do when construction lands on an ambiguous
+ *   or nonexistent instant.
+ * - Returns false for invalid input, and false for a zone that doesn't
+ *   observe DST at all.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns true if the instant is in daylight saving time, false otherwise or on invalid input
+ *
+ * @example isInDaylightSaving("2024-07-15T12:00:00-04:00[America/New_York]") // true
+ * @example isInDaylightSaving("2024-01-15T12:00:00-05:00[America/New_York]") // false
+ * @example isInDaylightSaving("2024-01-15T12:00:00+11:00[Australia/Sydney]") // true (southern-hemisphere summer)
+ * @example isInDaylightSaving("2024-07-15T12:00:00+09:00[Asia/Tokyo]") // false (Asia/Tokyo has no DST)
+ * @example isInDaylightSaving("invalid") // false
+ */
+export function isInDaylightSaving(value) {
+    if (!isValidZonedDateTime(value)) {
+        return false;
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(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
+        // shifts a zone's clocks forward relative to its own standard time, in
+        // every hemisphere, so whichever of these two offsets is smaller is
+        // "standard" — regardless of whether the zone's DST season falls in the
+        // Jan or Jul half of the year. This mirrors `hasDaylightSaving`'s
+        // Jan/Jul sampling, but anchored to `value`'s own year rather than a
+        // 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({
+            year,
+            month: 1,
+            day: 15,
+            hour: 12,
+            minute: 0,
+            second: 0,
+            timeZone,
+        }).offsetNanoseconds;
+        const julyOffsetNanoseconds = Temporal.ZonedDateTime.from({
+            year,
+            month: 7,
+            day: 15,
+            hour: 12,
+            minute: 0,
+            second: 0,
+            timeZone,
+        }).offsetNanoseconds;
+        const standardOffsetNanoseconds = Math.min(januaryOffsetNanoseconds, julyOffsetNanoseconds);
+        return zonedDateTime.offsetNanoseconds > standardOffsetNanoseconds;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Return true when `value` falls on a Monday–Friday ISO business day in the given timezone.
+ *
+ * - Uses the fixed ISO Monday–Friday business-day boundary (Mon=1 … Fri=5),
+ *   matching the definition used by `addZonedBusinessDays`/`subtractZonedBusinessDays`.
+ * - 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).
+ *
+ * @param value ISO 8601 zoned datetime string
+ * @returns true if `value` is a Monday–Friday business day, false on invalid input
+ *
+ * @example isZonedBusinessDay("2024-02-05T10:00:00-05:00[America/New_York]") // true (Monday)
+ * @example isZonedBusinessDay("2024-02-10T10:00:00-05:00[America/New_York]") // false (Saturday)
+ * @example isZonedBusinessDay("2024-02-04T10:00:00-05:00[America/New_York]") // false (Sunday)
+ * @example isZonedBusinessDay("invalid") // false
+ */
+export declare function isZonedBusinessDay(value: string): boolean;

package/dist/zoned/compare/isZonedBusinessDay.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `value` falls on a Monday–Friday ISO business day in the given timezone.
+ *
+ * - Uses the fixed ISO Monday–Friday business-day boundary (Mon=1 … Fri=5),
+ *   matching the definition used by `addZonedBusinessDays`/`subtractZonedBusinessDays`.
+ * - 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).
+ *
+ * @param value ISO 8601 zoned datetime string
+ * @returns true if `value` is a Monday–Friday business day, false on invalid input
+ *
+ * @example isZonedBusinessDay("2024-02-05T10:00:00-05:00[America/New_York]") // true (Monday)
+ * @example isZonedBusinessDay("2024-02-10T10:00:00-05:00[America/New_York]") // false (Saturday)
+ * @example isZonedBusinessDay("2024-02-04T10:00:00-05:00[America/New_York]") // false (Sunday)
+ * @example isZonedBusinessDay("invalid") // false
+ */
+export function isZonedBusinessDay(value) {
+    if (!isValidZonedDateTime(value))
+        return false;
+    try {
+        const zoned = Temporal.ZonedDateTime.from(value);
+        return zoned.dayOfWeek >= 1 && zoned.dayOfWeek <= 5;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Return true when `value` represents an instant strictly after now.
+ *
+ * - Unlike the plain `isFuture`, which compares calendar days, this compares
+ *   the exact instant `value` represents against `Temporal.Now.instant()` —
+ *   `value` carries a full time-of-day, not just a date.
+ * - `value === now` (to the precision available) returns false — "future"
+ *   means strictly after, not on-or-after.
+ * - Returns false if `value` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @returns true if `value` is after the current instant, false on invalid input
+ *
+ * @example isZonedFuture("2999-01-01T00:00:00Z[UTC]") // true (an instant in the distant future)
+ * @example isZonedFuture("2020-01-01T00:00:00Z[UTC]") // false (an instant in the distant past)
+ * @example isZonedFuture("invalid") // false
+ */
+export declare function isZonedFuture(value: string): boolean;

package/dist/zoned/compare/isZonedFuture.js

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `value` represents an instant strictly after now.
+ *
+ * - Unlike the plain `isFuture`, which compares calendar days, this compares
+ *   the exact instant `value` represents against `Temporal.Now.instant()` —
+ *   `value` carries a full time-of-day, not just a date.
+ * - `value === now` (to the precision available) returns false — "future"
+ *   means strictly after, not on-or-after.
+ * - Returns false if `value` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @returns true if `value` is after the current instant, false on invalid input
+ *
+ * @example isZonedFuture("2999-01-01T00:00:00Z[UTC]") // true (an instant in the distant future)
+ * @example isZonedFuture("2020-01-01T00:00:00Z[UTC]") // false (an instant in the distant past)
+ * @example isZonedFuture("invalid") // false
+ */
+export function isZonedFuture(value) {
+    if (!isValidZonedDateTime(value)) {
+        return false;
+    }
+    try {
+        const instant = Temporal.ZonedDateTime.from(value).toInstant();
+        return Temporal.Instant.compare(instant, Temporal.Now.instant()) === 1;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Return true when `value` represents an instant strictly before now.
+ *
+ * - Unlike the plain `isPast`, which compares calendar days, this compares
+ *   the exact instant `value` represents against `Temporal.Now.instant()` —
+ *   `value` carries a full time-of-day, not just a date.
+ * - `value === now` (to the precision available) returns false — "past"
+ *   means strictly before, not on-or-before.
+ * - Returns false if `value` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @returns true if `value` is before the current instant, false on invalid input
+ *
+ * @example isZonedPast("2020-01-01T00:00:00Z[UTC]") // true (an instant in the distant past)
+ * @example isZonedPast("2999-01-01T00:00:00Z[UTC]") // false (an instant in the distant future)
+ * @example isZonedPast("invalid") // false
+ */
+export declare function isZonedPast(value: string): boolean;

package/dist/zoned/compare/isZonedPast.js

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `value` represents an instant strictly before now.
+ *
+ * - Unlike the plain `isPast`, which compares calendar days, this compares
+ *   the exact instant `value` represents against `Temporal.Now.instant()` —
+ *   `value` carries a full time-of-day, not just a date.
+ * - `value === now` (to the precision available) returns false — "past"
+ *   means strictly before, not on-or-before.
+ * - Returns false if `value` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @returns true if `value` is before the current instant, false on invalid input
+ *
+ * @example isZonedPast("2020-01-01T00:00:00Z[UTC]") // true (an instant in the distant past)
+ * @example isZonedPast("2999-01-01T00:00:00Z[UTC]") // false (an instant in the distant future)
+ * @example isZonedPast("invalid") // false
+ */
+export function isZonedPast(value) {
+    if (!isValidZonedDateTime(value)) {
+        return false;
+    }
+    try {
+        const instant = Temporal.ZonedDateTime.from(value).toInstant();
+        return Temporal.Instant.compare(instant, Temporal.Now.instant()) === -1;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Return true when `value`'s local calendar day falls `offsetDays` days from
+ * today in `value`'s own IANA timeZone.
+ *
+ * - Subsumes `isZonedToday`/`isZonedYesterday`/`isZonedTomorrow`:
+ *   `offsetDays: 0` is "today", `-1` is "yesterday", `1` is "tomorrow", and
+ *   any other integer offset works the same way.
+ * - "Today" is resolved in `value`'s own timeZone — no separate timeZone
+ *   argument needed, since `value` already carries its IANA timeZone. This
+ *   is the deterministic counterpart to `isRelativeDay`, which depends on
+ *   the system clock and system timeZone: the same instant is "today" in
+ *   `Pacific/Apia` and "yesterday" in `Pacific/Niue`, a 24-hour spread.
+ * - `offsetDays` must be an integer; non-integer or non-finite values return false.
+ * - Returns false if `value` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @param offsetDays integer number of days from today in `value`'s own timeZone
+ * @returns true if `value`'s local day is exactly `offsetDays` days from today in its own timeZone, false on invalid input
+ *
+ * @example isZonedRelativeDay("2024-03-15T10:00:00-04:00[America/New_York]", 0) // true, if today is 2024-03-15 in America/New_York
+ * @example isZonedRelativeDay("2024-03-14T10:00:00-04:00[America/New_York]", -1) // true, if today is 2024-03-15 in America/New_York
+ * @example isZonedRelativeDay("2024-03-15T10:00:00+13:00[Pacific/Apia]", 0) // true, when the same instant is "yesterday" in Pacific/Niue
+ * @example isZonedRelativeDay("invalid", 0) // false
+ */
+export declare function isZonedRelativeDay(value: string, offsetDays: number): boolean;

package/dist/zoned/compare/isZonedRelativeDay.js

@@ -0,0 +1,40 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `value`'s local calendar day falls `offsetDays` days from
+ * today in `value`'s own IANA timeZone.
+ *
+ * - Subsumes `isZonedToday`/`isZonedYesterday`/`isZonedTomorrow`:
+ *   `offsetDays: 0` is "today", `-1` is "yesterday", `1` is "tomorrow", and
+ *   any other integer offset works the same way.
+ * - "Today" is resolved in `value`'s own timeZone — no separate timeZone
+ *   argument needed, since `value` already carries its IANA timeZone. This
+ *   is the deterministic counterpart to `isRelativeDay`, which depends on
+ *   the system clock and system timeZone: the same instant is "today" in
+ *   `Pacific/Apia` and "yesterday" in `Pacific/Niue`, a 24-hour spread.
+ * - `offsetDays` must be an integer; non-integer or non-finite values return false.
+ * - Returns false if `value` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @param offsetDays integer number of days from today in `value`'s own timeZone
+ * @returns true if `value`'s local day is exactly `offsetDays` days from today in its own timeZone, false on invalid input
+ *
+ * @example isZonedRelativeDay("2024-03-15T10:00:00-04:00[America/New_York]", 0) // true, if today is 2024-03-15 in America/New_York
+ * @example isZonedRelativeDay("2024-03-14T10:00:00-04:00[America/New_York]", -1) // true, if today is 2024-03-15 in America/New_York
+ * @example isZonedRelativeDay("2024-03-15T10:00:00+13:00[Pacific/Apia]", 0) // true, when the same instant is "yesterday" in Pacific/Niue
+ * @example isZonedRelativeDay("invalid", 0) // false
+ */
+export function isZonedRelativeDay(value, offsetDays) {
+    if (!isValidZonedDateTime(value) || !Number.isInteger(offsetDays)) {
+        return false;
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const today = Temporal.Now.zonedDateTimeISO(zonedDateTime.timeZoneId).toPlainDate();
+        const target = today.add({ days: offsetDays });
+        return (Temporal.PlainDate.compare(zonedDateTime.toPlainDate(), target) === 0);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return true when `value`'s local calendar day falls in the same `unit` as
+ * today, both resolved in `value`'s own IANA timeZone.
+ *
+ * - Subsumes `isZonedThisWeek`/`isZonedThisMonth`/`isZonedThisYear`; `unit`
+ *   is drawn from the same `Temporal.DateUnit` `isThisUnit` uses.
+ * - "Today" is resolved in `value`'s own timeZone — no separate timeZone
+ *   argument needed, since `value` already carries its IANA timeZone. This
+ *   is the deterministic counterpart to `isThisUnit`, which depends on the
+ *   system clock and system timeZone.
+ * - `locale` only affects the `"week"` case — which day the week starts on
+ *   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.
+ *
+ * @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")
+ * @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
+ */
+export declare function isZonedThisUnit(value: string, unit: Temporal.DateUnit, locale?: string): boolean;

package/dist/zoned/compare/isZonedThisUnit.js

@@ -0,0 +1,52 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleStartOfWeek } from "../../plain/calculate/getLocaleStartOfWeek.js";
+import { areDatesEqualBy } from "../../plain/compare/areDatesEqualBy.js";
+import { isValidDateUnit } from "../../plain/validate/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `value`'s local calendar day falls in the same `unit` as
+ * today, both resolved in `value`'s own IANA timeZone.
+ *
+ * - Subsumes `isZonedThisWeek`/`isZonedThisMonth`/`isZonedThisYear`; `unit`
+ *   is drawn from the same `Temporal.DateUnit` `isThisUnit` uses.
+ * - "Today" is resolved in `value`'s own timeZone — no separate timeZone
+ *   argument needed, since `value` already carries its IANA timeZone. This
+ *   is the deterministic counterpart to `isThisUnit`, which depends on the
+ *   system clock and system timeZone.
+ * - `locale` only affects the `"week"` case — which day the week starts on
+ *   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.
+ *
+ * @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")
+ * @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
+ */
+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;
+        }
+        return areDatesEqualBy(valueDate, today, unit);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Return true when `value`'s local calendar day falls on a weekend for `locale`.
+ *
+ * - Uses `Intl.Locale.prototype.weekInfo` to resolve which ISO weekday
+ *   numbers count as "weekend" for the locale (e.g. en-US: Sat/Sun,
+ *   he-IL/ar-SA: Fri/Sat).
+ * - Checks the ZonedDateTime's own local day of week — no separate timezone
+ *   conversion needed, since `value` already carries its IANA timezone.
+ * - Falls back to Saturday/Sunday if the runtime's `weekInfo` data doesn't
+ *   resolve a weekend for the locale.
+ * - Returns false if `value` or `locale` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @returns true if `value`'s local day is a weekend day in `locale`, false on invalid input
+ *
+ * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "en-US") // true (Saturday)
+ * @example isZonedWeekend("2024-02-02T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
+ * @example isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // false (Sunday)
+ * @example isZonedWeekend("invalid", "en-US") // false
+ * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "not-a-locale") // false
+ */
+export declare function isZonedWeekend(value: string, locale: string): boolean;

package/dist/zoned/compare/isZonedWeekend.js

@@ -0,0 +1,39 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleWeekendDays } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return true when `value`'s local calendar day falls on a weekend for `locale`.
+ *
+ * - Uses `Intl.Locale.prototype.weekInfo` to resolve which ISO weekday
+ *   numbers count as "weekend" for the locale (e.g. en-US: Sat/Sun,
+ *   he-IL/ar-SA: Fri/Sat).
+ * - Checks the ZonedDateTime's own local day of week — no separate timezone
+ *   conversion needed, since `value` already carries its IANA timezone.
+ * - Falls back to Saturday/Sunday if the runtime's `weekInfo` data doesn't
+ *   resolve a weekend for the locale.
+ * - Returns false if `value` or `locale` is invalid.
+ *
+ * @param value ISO ZonedDateTime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @returns true if `value`'s local day is a weekend day in `locale`, false on invalid input
+ *
+ * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "en-US") // true (Saturday)
+ * @example isZonedWeekend("2024-02-02T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
+ * @example isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL") // false (Sunday)
+ * @example isZonedWeekend("invalid", "en-US") // false
+ * @example isZonedWeekend("2024-02-03T10:00:00-05:00[America/New_York]", "not-a-locale") // false
+ */
+export function isZonedWeekend(value, locale) {
+    if (!isValidZonedDateTime(value))
+        return false;
+    const weekendDays = getLocaleWeekendDays(locale);
+    if (!weekendDays)
+        return false;
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return weekendDays.has(zonedDateTime.dayOfWeek);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/zoned/convert/convertPlainDateTimeToZoned.d.ts

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Attach the specified `timeZone` to a plain datetime string and return a zoned ISO 8601 datetime string.
+ *
+ * - Combines plain datetime with timezone to create ZonedDateTime.
+ * - `disambiguation` controls DST gap/overlap resolution: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
+ * - `offset` ("prefer" | "use" | "ignore" (default) | "reject", per Temporal's `OffsetDisambiguationOptions`) is accepted for API consistency with sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect here**: `value` is a plain datetime string with no UTC offset embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against. `disambiguation` is the only option that affects this function's output.
+ * - Returns "" for invalid input.
+ *
+ * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
+ * @param timeZone IANA timeZone identifier
+ * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above)
+ * @returns zoned ISO 8601 datetime string or "" when invalid
+ *
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.123-05:00[America/New_York]"
+ * @example convertPlainDateTimeToZoned("invalid", "America/New_York") // ""
+ * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T01:30:00.000-05:00[America/New_York]" (spring-forward gap)
+ * @example convertPlainDateTimeToZoned("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T01:30:00.000-05:00[America/New_York]" (fall-back overlap)
+ * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "reject" }) // ""
+ */
+export declare function convertPlainDateTimeToZoned(value: string, timeZone: string, optionsArg?: {
+    smallestUnit?: Temporal.ZonedDateTimeToStringOptions["smallestUnit"];
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/zoned/convert/convertPlainDateTimeToZoned.js

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../../plain/validate/index.js";
+import { isValidTimeZone } from "../validate/index.js";
+/**
+ * Attach the specified `timeZone` to a plain datetime string and return a zoned ISO 8601 datetime string.
+ *
+ * - Combines plain datetime with timezone to create ZonedDateTime.
+ * - `disambiguation` controls DST gap/overlap resolution: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
+ * - `offset` ("prefer" | "use" | "ignore" (default) | "reject", per Temporal's `OffsetDisambiguationOptions`) is accepted for API consistency with sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect here**: `value` is a plain datetime string with no UTC offset embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against. `disambiguation` is the only option that affects this function's output.
+ * - Returns "" for invalid input.
+ *
+ * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
+ * @param timeZone IANA timeZone identifier
+ * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above)
+ * @returns zoned ISO 8601 datetime string or "" when invalid
+ *
+ * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.123-05:00[America/New_York]"
+ * @example convertPlainDateTimeToZoned("invalid", "America/New_York") // ""
+ * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T01:30:00.000-05:00[America/New_York]" (spring-forward gap)
+ * @example convertPlainDateTimeToZoned("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T01:30:00.000-05:00[America/New_York]" (fall-back overlap)
+ * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "reject" }) // ""
+ */
+export function convertPlainDateTimeToZoned(value, timeZone, optionsArg) {
+    if (!isValidDateTime(value) || !isValidTimeZone(timeZone)) {
+        return "";
+    }
+    const disambiguation = optionsArg?.disambiguation ?? "compatible";
+    const offset = optionsArg?.offset ?? "ignore";
+    const options = {
+        smallestUnit: optionsArg?.smallestUnit ?? "milliseconds",
+    };
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(`${value}[${timeZone}]`, {
+            disambiguation,
+            offset,
+        });
+        return zonedDateTime.toString(options);
+    }
+    catch {
+        return "";
+    }
+}