@northguild/gmt 1.14.2

package/dist/plain/compare/isBetweenTime.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Return true when `time` is between `start` and `end` (inclusive by default).
+ *
+ * - Uses Temporal.PlainTime.compare to compare times.
+ * - Returns false if start > end (invalid range).
+ * - Returns false if any input is invalid.
+ * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
+ * - Note: PlainTime comparison does not account for day overflow.
+ *
+ * @param time ISO PlainTime string to check
+ * @param start ISO PlainTime string for the start of the range
+ * @param end ISO PlainTime string for the end of the range
+ * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @returns boolean indicating whether time is between start and end
+ *
+ * @example isBetweenTime("12:34:56", "12:00:00", "13:00:00") // true
+ * @example isBetweenTime("12:34:56", "12:34:56", "13:00:00") // true
+ * @example isBetweenTime("12:34:56", "12:34:57", "13:00:00") // false
+ * @example isBetweenTime("12:34:56", "12:00:00", "12:34:56") // true
+ * @example isBetweenTime("12:34:56", "12:00:00", "12:34:55") // false
+ * @example isBetweenTime("invalid", "12:00:00", "13:00:00") // false
+ * @example isBetweenTime("12:34:56", "invalid", "13:00:00") // false
+ * @example isBetweenTime("12:34:56", "12:00:00", "invalid") // false
+ */
+export declare function isBetweenTime(time: string, start: string, end: string, options?: {
+    inclusiveStart?: boolean;
+    inclusiveEnd?: boolean;
+}): boolean;

package/dist/plain/compare/isBetweenTime.js

@@ -0,0 +1,51 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Return true when `time` is between `start` and `end` (inclusive by default).
+ *
+ * - Uses Temporal.PlainTime.compare to compare times.
+ * - Returns false if start > end (invalid range).
+ * - Returns false if any input is invalid.
+ * - Use options.inclusiveStart and options.inclusiveEnd to control boundary inclusivity.
+ * - Note: PlainTime comparison does not account for day overflow.
+ *
+ * @param time ISO PlainTime string to check
+ * @param start ISO PlainTime string for the start of the range
+ * @param end ISO PlainTime string for the end of the range
+ * @param options { inclusiveStart?: boolean = true, inclusiveEnd?: boolean = true }
+ * @returns boolean indicating whether time is between start and end
+ *
+ * @example isBetweenTime("12:34:56", "12:00:00", "13:00:00") // true
+ * @example isBetweenTime("12:34:56", "12:34:56", "13:00:00") // true
+ * @example isBetweenTime("12:34:56", "12:34:57", "13:00:00") // false
+ * @example isBetweenTime("12:34:56", "12:00:00", "12:34:56") // true
+ * @example isBetweenTime("12:34:56", "12:00:00", "12:34:55") // false
+ * @example isBetweenTime("invalid", "12:00:00", "13:00:00") // false
+ * @example isBetweenTime("12:34:56", "invalid", "13:00:00") // false
+ * @example isBetweenTime("12:34:56", "12:00:00", "invalid") // false
+ */
+export function isBetweenTime(time, start, end, options) {
+    const inclusiveStart = options?.inclusiveStart ?? true;
+    const inclusiveEnd = options?.inclusiveEnd ?? true;
+    if (!isValidTime(time) || !isValidTime(start) || !isValidTime(end)) {
+        return false;
+    }
+    try {
+        const t = Temporal.PlainTime.from(time);
+        const s = Temporal.PlainTime.from(start);
+        const e = Temporal.PlainTime.from(end);
+        if (Temporal.PlainTime.compare(s, e) === 1) {
+            return false;
+        }
+        const startCheck = inclusiveStart
+            ? Temporal.PlainTime.compare(s, t) <= 0
+            : Temporal.PlainTime.compare(s, t) < 0;
+        const endCheck = inclusiveEnd
+            ? Temporal.PlainTime.compare(t, e) <= 0
+            : Temporal.PlainTime.compare(t, e) < 0;
+        return startCheck && endCheck;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/plain/compare/isBusinessDay.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return true when `value` falls on a Monday–Friday ISO business day.
+ *
+ * - Uses the fixed ISO Monday–Friday business-day boundary (Mon=1 … Fri=5),
+ *   matching the definition used by `addBusinessDays`/`subtractBusinessDays`.
+ * - Locale-agnostic: no `Intl.Locale` lookup and no holiday calendar.
+ * - Returns false if `value` is invalid.
+ *
+ * This is the locale-agnostic complement to the locale-aware `isWeekend`: `isWeekend`
+ * resolves weekend days per locale via `Intl.Locale.prototype.weekInfo`, whereas
+ * `isBusinessDay` always treats Monday–Friday as business days regardless of locale.
+ *
+ * @param value ISO PlainDate string
+ * @returns true if `value` is a Monday–Friday business day, false on invalid input
+ *
+ * @example isBusinessDay("2024-02-05") // true (Monday)
+ * @example isBusinessDay("2024-02-10") // false (Saturday)
+ * @example isBusinessDay("2024-02-04") // false (Sunday)
+ * @example isBusinessDay("invalid") // false
+ */
+export declare function isBusinessDay(value: string): boolean;

package/dist/plain/compare/isBusinessDay.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return true when `value` falls on a Monday–Friday ISO business day.
+ *
+ * - Uses the fixed ISO Monday–Friday business-day boundary (Mon=1 … Fri=5),
+ *   matching the definition used by `addBusinessDays`/`subtractBusinessDays`.
+ * - Locale-agnostic: no `Intl.Locale` lookup and no holiday calendar.
+ * - Returns false if `value` is invalid.
+ *
+ * This is the locale-agnostic complement to the locale-aware `isWeekend`: `isWeekend`
+ * resolves weekend days per locale via `Intl.Locale.prototype.weekInfo`, whereas
+ * `isBusinessDay` always treats Monday–Friday as business days regardless of locale.
+ *
+ * @param value ISO PlainDate string
+ * @returns true if `value` is a Monday–Friday business day, false on invalid input
+ *
+ * @example isBusinessDay("2024-02-05") // true (Monday)
+ * @example isBusinessDay("2024-02-10") // false (Saturday)
+ * @example isBusinessDay("2024-02-04") // false (Sunday)
+ * @example isBusinessDay("invalid") // false
+ */
+export function isBusinessDay(value) {
+    if (!isValidDate(value))
+        return false;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.dayOfWeek >= 1 && date.dayOfWeek <= 5;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/plain/compare/isFuture.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return true when `value` is strictly after today, per the system clock
+ * and system timeZone.
+ *
+ * - `value === today` returns false — "future" means strictly after, not
+ *   on-or-after.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. A caller needing determinism should use
+ *   `isZonedFuture` with an explicit timeZone, or compare against an
+ *   explicit reference with `isAfterDate`.
+ * - Returns false if `value` is invalid or the system timeZone is unavailable.
+ *
+ * @param value ISO PlainDate string
+ * @returns true if `value` is after today, false on invalid input
+ *
+ * @example isFuture("2024-03-16") // true, if today is 2024-03-15
+ * @example isFuture("2024-03-15") // false, if today is 2024-03-15 (equal is not future)
+ * @example isFuture("2024-03-14") // false, if today is 2024-03-15
+ * @example isFuture("invalid") // false
+ */
+export declare function isFuture(value: string): boolean;

package/dist/plain/compare/isFuture.js

@@ -0,0 +1,33 @@
+import { getToday } from "../get/getToday.js";
+import { isValidDate } from "../validate/index.js";
+import { isAfterDate } from "./isAfterDate.js";
+/**
+ * Return true when `value` is strictly after today, per the system clock
+ * and system timeZone.
+ *
+ * - `value === today` returns false — "future" means strictly after, not
+ *   on-or-after.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. A caller needing determinism should use
+ *   `isZonedFuture` with an explicit timeZone, or compare against an
+ *   explicit reference with `isAfterDate`.
+ * - Returns false if `value` is invalid or the system timeZone is unavailable.
+ *
+ * @param value ISO PlainDate string
+ * @returns true if `value` is after today, false on invalid input
+ *
+ * @example isFuture("2024-03-16") // true, if today is 2024-03-15
+ * @example isFuture("2024-03-15") // false, if today is 2024-03-15 (equal is not future)
+ * @example isFuture("2024-03-14") // false, if today is 2024-03-15
+ * @example isFuture("invalid") // false
+ */
+export function isFuture(value) {
+    if (!isValidDate(value)) {
+        return false;
+    }
+    const today = getToday();
+    if (today === "") {
+        return false;
+    }
+    return isAfterDate(value, today);
+}

package/dist/plain/compare/isPast.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return true when `value` is strictly before today, per the system clock
+ * and system timeZone.
+ *
+ * - `value === today` returns false — "past" means strictly before, not
+ *   on-or-before.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. A caller needing determinism should use `isZonedPast`
+ *   with an explicit timeZone, or compare against an explicit reference with
+ *   `isBeforeDate`.
+ * - Returns false if `value` is invalid or the system timeZone is unavailable.
+ *
+ * @param value ISO PlainDate string
+ * @returns true if `value` is before today, false on invalid input
+ *
+ * @example isPast("2024-03-14") // true, if today is 2024-03-15
+ * @example isPast("2024-03-15") // false, if today is 2024-03-15 (equal is not past)
+ * @example isPast("2024-03-16") // false, if today is 2024-03-15
+ * @example isPast("invalid") // false
+ */
+export declare function isPast(value: string): boolean;

package/dist/plain/compare/isPast.js

@@ -0,0 +1,33 @@
+import { getToday } from "../get/getToday.js";
+import { isValidDate } from "../validate/index.js";
+import { isBeforeDate } from "./isBeforeDate.js";
+/**
+ * Return true when `value` is strictly before today, per the system clock
+ * and system timeZone.
+ *
+ * - `value === today` returns false — "past" means strictly before, not
+ *   on-or-before.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. A caller needing determinism should use `isZonedPast`
+ *   with an explicit timeZone, or compare against an explicit reference with
+ *   `isBeforeDate`.
+ * - Returns false if `value` is invalid or the system timeZone is unavailable.
+ *
+ * @param value ISO PlainDate string
+ * @returns true if `value` is before today, false on invalid input
+ *
+ * @example isPast("2024-03-14") // true, if today is 2024-03-15
+ * @example isPast("2024-03-15") // false, if today is 2024-03-15 (equal is not past)
+ * @example isPast("2024-03-16") // false, if today is 2024-03-15
+ * @example isPast("invalid") // false
+ */
+export function isPast(value) {
+    if (!isValidDate(value)) {
+        return false;
+    }
+    const today = getToday();
+    if (today === "") {
+        return false;
+    }
+    return isBeforeDate(value, today);
+}

package/dist/plain/compare/isRelativeDay.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Return true when `value` falls `offsetDays` days from today, per the
+ * system clock and system timeZone.
+ *
+ * - Subsumes `isToday`/`isYesterday`/`isTomorrow`: `offsetDays: 0` is
+ *   "today", `-1` is "yesterday", `1` is "tomorrow", and any other integer
+ *   offset works the same way.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. The same call returns different answers on hosts in
+ *   different timeZones at the same instant — a caller needing determinism
+ *   (server-side rendering, tests, scheduled jobs) should use
+ *   `isZonedRelativeDay` with an explicit timeZone, or compare against an
+ *   explicit reference with `areDatesEqualBy`.
+ * - `offsetDays` must be an integer; non-integer or non-finite values return false.
+ * - Returns false if `value` is invalid or the system timeZone is unavailable.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `isToday(value)` → `isRelativeDay(value, 0)`
+ * - `isYesterday(value)` → `isRelativeDay(value, -1)`
+ * - `isTomorrow(value)` → `isRelativeDay(value, 1)`
+ *
+ * @param value ISO PlainDate string
+ * @param offsetDays integer number of days from today (0 = today, -1 = yesterday, 1 = tomorrow)
+ * @returns true if `value` is exactly `offsetDays` days from today, false on invalid input
+ *
+ * @example isRelativeDay("2024-03-15", 0) // true, if today is 2024-03-15
+ * @example isRelativeDay("2024-03-14", -1) // true, if today is 2024-03-15
+ * @example isRelativeDay("2024-03-22", 7) // true, if today is 2024-03-15
+ * @example isRelativeDay("2024-03-15", 1.5) // false (offsetDays must be an integer)
+ * @example isRelativeDay("invalid", 0) // false
+ */
+export declare function isRelativeDay(value: string, offsetDays: number): boolean;

package/dist/plain/compare/isRelativeDay.js

@@ -0,0 +1,49 @@
+import { addDate } from "../calculate/addDate.js";
+import { getToday } from "../get/getToday.js";
+import { isValidDate } from "../validate/index.js";
+import { areDatesEqual } from "./areDatesEqual.js";
+/**
+ * Return true when `value` falls `offsetDays` days from today, per the
+ * system clock and system timeZone.
+ *
+ * - Subsumes `isToday`/`isYesterday`/`isTomorrow`: `offsetDays: 0` is
+ *   "today", `-1` is "yesterday", `1` is "tomorrow", and any other integer
+ *   offset works the same way.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. The same call returns different answers on hosts in
+ *   different timeZones at the same instant — a caller needing determinism
+ *   (server-side rendering, tests, scheduled jobs) should use
+ *   `isZonedRelativeDay` with an explicit timeZone, or compare against an
+ *   explicit reference with `areDatesEqualBy`.
+ * - `offsetDays` must be an integer; non-integer or non-finite values return false.
+ * - Returns false if `value` is invalid or the system timeZone is unavailable.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `isToday(value)` → `isRelativeDay(value, 0)`
+ * - `isYesterday(value)` → `isRelativeDay(value, -1)`
+ * - `isTomorrow(value)` → `isRelativeDay(value, 1)`
+ *
+ * @param value ISO PlainDate string
+ * @param offsetDays integer number of days from today (0 = today, -1 = yesterday, 1 = tomorrow)
+ * @returns true if `value` is exactly `offsetDays` days from today, false on invalid input
+ *
+ * @example isRelativeDay("2024-03-15", 0) // true, if today is 2024-03-15
+ * @example isRelativeDay("2024-03-14", -1) // true, if today is 2024-03-15
+ * @example isRelativeDay("2024-03-22", 7) // true, if today is 2024-03-15
+ * @example isRelativeDay("2024-03-15", 1.5) // false (offsetDays must be an integer)
+ * @example isRelativeDay("invalid", 0) // false
+ */
+export function isRelativeDay(value, offsetDays) {
+    if (!isValidDate(value) || !Number.isInteger(offsetDays)) {
+        return false;
+    }
+    const today = getToday();
+    if (today === "") {
+        return false;
+    }
+    const target = addDate(today, { days: offsetDays });
+    if (target === "") {
+        return false;
+    }
+    return areDatesEqual(value, target);
+}

package/dist/plain/compare/isThisUnit.d.ts

@@ -0,0 +1,35 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return true when `value` falls in the same `unit` as today, per the
+ * system clock and system timeZone.
+ *
+ * - Subsumes `isThisWeek`/`isThisMonth`/`isThisYear`: `unit` is drawn from
+ *   the same `Temporal.DateUnit` `areDatesEqualBy` uses.
+ * - `"day"` is equivalent to `isRelativeDay(value, 0)`.
+ * - `locale` only affects the `"week"` case — which day the week starts on
+ *   varies by locale (e.g. en-US: Sunday, fr-FR: Monday). When `unit` is
+ *   `"week"` and `locale` is given, the comparison uses `getLocaleStartOfWeek`
+ *   instead of the ISO Monday-start default `areDatesEqualBy` otherwise uses.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. A caller needing determinism should use
+ *   `isZonedThisUnit` with an explicit timeZone, or compare against an
+ *   explicit reference with `areDatesEqualBy`.
+ * - Returns false for an unsupported unit, invalid input, or an invalid locale.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `isThisWeek(value, options)` → `isThisUnit(value, "week", locale)`
+ * - `isThisMonth(value)` → `isThisUnit(value, "month")`
+ * - `isThisYear(value)` → `isThisUnit(value, "year")`
+ *
+ * @param value ISO PlainDate 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` falls in the same `unit` as today, false on an unsupported unit or invalid input
+ *
+ * @example isThisUnit("2024-03-15", "month") // true, if today is any day in March 2024
+ * @example isThisUnit("2024-03-15", "year") // true, if today is any day in 2024
+ * @example isThisUnit("2024-02-26", "week", "fr-FR") // true, if today is 2024-03-01 (same fr-FR Monday-start week)
+ * @example isThisUnit("2024-03-15", "hour" as never) // false (unsupported unit)
+ * @example isThisUnit("invalid", "month") // false
+ */
+export declare function isThisUnit(value: string, unit: Temporal.DateUnit, locale?: string): boolean;

package/dist/plain/compare/isThisUnit.js

@@ -0,0 +1,52 @@
+import { getLocaleStartOfWeek } from "../calculate/getLocaleStartOfWeek.js";
+import { getToday } from "../get/getToday.js";
+import { isValidDateUnit } from "../validate/index.js";
+import { areDatesEqualBy } from "./areDatesEqualBy.js";
+/**
+ * Return true when `value` falls in the same `unit` as today, per the
+ * system clock and system timeZone.
+ *
+ * - Subsumes `isThisWeek`/`isThisMonth`/`isThisYear`: `unit` is drawn from
+ *   the same `Temporal.DateUnit` `areDatesEqualBy` uses.
+ * - `"day"` is equivalent to `isRelativeDay(value, 0)`.
+ * - `locale` only affects the `"week"` case — which day the week starts on
+ *   varies by locale (e.g. en-US: Sunday, fr-FR: Monday). When `unit` is
+ *   `"week"` and `locale` is given, the comparison uses `getLocaleStartOfWeek`
+ *   instead of the ISO Monday-start default `areDatesEqualBy` otherwise uses.
+ * - Compares against `getToday()`, so this depends on the **system clock and
+ *   system timeZone**. A caller needing determinism should use
+ *   `isZonedThisUnit` with an explicit timeZone, or compare against an
+ *   explicit reference with `areDatesEqualBy`.
+ * - Returns false for an unsupported unit, invalid input, or an invalid locale.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `isThisWeek(value, options)` → `isThisUnit(value, "week", locale)`
+ * - `isThisMonth(value)` → `isThisUnit(value, "month")`
+ * - `isThisYear(value)` → `isThisUnit(value, "year")`
+ *
+ * @param value ISO PlainDate 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` falls in the same `unit` as today, false on an unsupported unit or invalid input
+ *
+ * @example isThisUnit("2024-03-15", "month") // true, if today is any day in March 2024
+ * @example isThisUnit("2024-03-15", "year") // true, if today is any day in 2024
+ * @example isThisUnit("2024-02-26", "week", "fr-FR") // true, if today is 2024-03-01 (same fr-FR Monday-start week)
+ * @example isThisUnit("2024-03-15", "hour" as never) // false (unsupported unit)
+ * @example isThisUnit("invalid", "month") // false
+ */
+export function isThisUnit(value, unit, locale) {
+    if (!isValidDateUnit(unit)) {
+        return false;
+    }
+    const today = getToday();
+    if (today === "") {
+        return false;
+    }
+    if (unit === "week" && locale !== undefined) {
+        const startOfWeekValue = getLocaleStartOfWeek(value, locale);
+        const startOfWeekToday = getLocaleStartOfWeek(today, locale);
+        return startOfWeekValue !== "" && startOfWeekValue === startOfWeekToday;
+    }
+    return areDatesEqualBy(value, today, unit);
+}

package/dist/plain/compare/isWeekend.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return true when `value` falls on a weekend day 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).
+ * - 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 PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @returns true if `value` is a weekend day in `locale`, false on invalid input
+ *
+ * @example isWeekend("2024-02-03", "en-US") // true (Saturday, en-US weekend is Sat/Sun)
+ * @example isWeekend("2024-02-02", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
+ * @example isWeekend("2024-02-04", "he-IL") // false (Sunday, not part of he-IL's weekend)
+ * @example isWeekend("invalid", "en-US") // false
+ * @example isWeekend("2024-02-03", "not-a-locale") // false
+ */
+export declare function isWeekend(value: string, locale: string): boolean;

package/dist/plain/compare/isWeekend.js

@@ -0,0 +1,37 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleWeekendDays } from "../../internal/index.js";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return true when `value` falls on a weekend day 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).
+ * - 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 PlainDate string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @returns true if `value` is a weekend day in `locale`, false on invalid input
+ *
+ * @example isWeekend("2024-02-03", "en-US") // true (Saturday, en-US weekend is Sat/Sun)
+ * @example isWeekend("2024-02-02", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
+ * @example isWeekend("2024-02-04", "he-IL") // false (Sunday, not part of he-IL's weekend)
+ * @example isWeekend("invalid", "en-US") // false
+ * @example isWeekend("2024-02-03", "not-a-locale") // false
+ */
+export function isWeekend(value, locale) {
+    if (!isValidDate(value))
+        return false;
+    const weekendDays = getLocaleWeekendDays(locale);
+    if (!weekendDays)
+        return false;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return weekendDays.has(date.dayOfWeek);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/plain/convert/convertDateToCalendar.d.ts

@@ -0,0 +1,44 @@
+import type { CalendarSystem } from "../../types/index.js";
+/**
+ * Convert a PlainDate to the same date expressed in a different calendar system.
+ *
+ * - Accepts a plain ISO date ("2024-10-03") or a calendar-annotated date previously
+ *   produced by this function ("5785-01-01[u-ca=hebrew]"), so conversions can chain
+ *   between calendar systems.
+ * - The output for "gregorian" is always a bare, unannotated ISO string, matching every
+ *   other GMT PlainDate string. Any other calendar returns its own native year/month/day
+ *   (e.g. Hebrew year 5785, not the ISO year), tagged with `[u-ca=<identifier>]` — this
+ *   diverges from Temporal's own `[u-ca=...]` string convention (which keeps ISO digits
+ *   and only annotates the calendar) specifically so the calendar's native fields are
+ *   visible in GMT's string contract, not hidden behind calendar-aware accessors.
+ * - Uses Temporal's built-in calendar support (`PlainDate.prototype.withCalendar`) for every
+ *   calendar except the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic"),
+ *   which is computed with GMT-owned arithmetic instead — see
+ *   `internal/ethiopicFamilyCalendar.ts` for why. Either way, the underlying date never
+ *   changes, only which calendar's fields it resolves through.
+ * - Returns "" on invalid input or an unsupported `calendar`.
+ *
+ * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain
+ * native year — see the README's calendar-systems section for why.
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
+ *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
+ *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
+ * @returns calendar-native ISO-shaped PlainDate string, or "" on invalid input
+ *
+ * @example convertDateToCalendar("2024-10-03", "hebrew") // "5785-01-01[u-ca=hebrew]"
+ * @example convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "gregorian") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "islamic-umalqura") // "1446-03-30[u-ca=islamic-umalqura]"
+ * @example convertDateToCalendar("2024-10-03", "japanese") // "0006-10-03[u-ca=japanese;era=reiwa]"
+ * @example convertDateToCalendar("2024-10-03", "buddhist") // "2567-10-03[u-ca=buddhist]"
+ * @example convertDateToCalendar("2024-10-03", "taiwan") // "0113-10-03[u-ca=taiwan]"
+ * @example convertDateToCalendar("2024-10-03", "persian") // "1403-07-12[u-ca=persian]"
+ * @example convertDateToCalendar("2024-10-03", "indian") // "1946-07-11[u-ca=indian]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic") // "2017-01-23[u-ca=ethiopic;era=ethiopic]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem") // "7517-01-23[u-ca=ethiopic-amete-alem]"
+ * @example convertDateToCalendar("2024-10-03", "coptic") // "1741-01-23[u-ca=coptic]"
+ * @example convertDateToCalendar("invalid", "hebrew") // ""
+ */
+export declare function convertDateToCalendar(value: string, calendar: CalendarSystem): string;

package/dist/plain/convert/convertDateToCalendar.js

@@ -0,0 +1,59 @@
+import { formatCalendarDate, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, parseCalendarDateValue, temporalCalendarIds, } from "../../internal/index.js";
+import { isValidCalendarDate } from "../validate/index.js";
+/**
+ * Convert a PlainDate to the same date expressed in a different calendar system.
+ *
+ * - Accepts a plain ISO date ("2024-10-03") or a calendar-annotated date previously
+ *   produced by this function ("5785-01-01[u-ca=hebrew]"), so conversions can chain
+ *   between calendar systems.
+ * - The output for "gregorian" is always a bare, unannotated ISO string, matching every
+ *   other GMT PlainDate string. Any other calendar returns its own native year/month/day
+ *   (e.g. Hebrew year 5785, not the ISO year), tagged with `[u-ca=<identifier>]` — this
+ *   diverges from Temporal's own `[u-ca=...]` string convention (which keeps ISO digits
+ *   and only annotates the calendar) specifically so the calendar's native fields are
+ *   visible in GMT's string contract, not hidden behind calendar-aware accessors.
+ * - Uses Temporal's built-in calendar support (`PlainDate.prototype.withCalendar`) for every
+ *   calendar except the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic"),
+ *   which is computed with GMT-owned arithmetic instead — see
+ *   `internal/ethiopicFamilyCalendar.ts` for why. Either way, the underlying date never
+ *   changes, only which calendar's fields it resolves through.
+ * - Returns "" on invalid input or an unsupported `calendar`.
+ *
+ * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain
+ * native year — see the README's calendar-systems section for why.
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
+ *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
+ *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
+ * @returns calendar-native ISO-shaped PlainDate string, or "" on invalid input
+ *
+ * @example convertDateToCalendar("2024-10-03", "hebrew") // "5785-01-01[u-ca=hebrew]"
+ * @example convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "gregorian") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "islamic-umalqura") // "1446-03-30[u-ca=islamic-umalqura]"
+ * @example convertDateToCalendar("2024-10-03", "japanese") // "0006-10-03[u-ca=japanese;era=reiwa]"
+ * @example convertDateToCalendar("2024-10-03", "buddhist") // "2567-10-03[u-ca=buddhist]"
+ * @example convertDateToCalendar("2024-10-03", "taiwan") // "0113-10-03[u-ca=taiwan]"
+ * @example convertDateToCalendar("2024-10-03", "persian") // "1403-07-12[u-ca=persian]"
+ * @example convertDateToCalendar("2024-10-03", "indian") // "1946-07-11[u-ca=indian]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic") // "2017-01-23[u-ca=ethiopic;era=ethiopic]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem") // "7517-01-23[u-ca=ethiopic-amete-alem]"
+ * @example convertDateToCalendar("2024-10-03", "coptic") // "1741-01-23[u-ca=coptic]"
+ * @example convertDateToCalendar("invalid", "hebrew") // ""
+ */
+export function convertDateToCalendar(value, calendar) {
+    if (!isValidCalendarDate(value) || !(calendar in temporalCalendarIds)) {
+        return "";
+    }
+    try {
+        const date = parseCalendarDateValue(value);
+        if (isEthiopicFamilyCalendar(calendar)) {
+            return formatEthiopicFamilyDate(date, calendar);
+        }
+        return formatCalendarDate(date.withCalendar(temporalCalendarIds[calendar]));
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/convert/index.d.ts

@@ -0,0 +1 @@
+export * from "./convertDateToCalendar.js";

package/dist/plain/convert/index.js

@@ -0,0 +1 @@
+export * from "./convertDateToCalendar.js";

package/dist/plain/format/formatCalendar.d.ts

@@ -0,0 +1,43 @@
+export interface FormatCalendarOptions {
+    reference?: string;
+    /**
+     * `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half.
+     * "full" is deliberately not offered here: it appends a `timeZoneName`
+     * (e.g. "Coordinated Universal Time"), and plain values have no real
+     * timezone — the UTC anchor below is an implementation detail, not a
+     * fact about `value`, so surfacing it as a zone name would be a lie.
+     */
+    timeStyle?: "short" | "medium";
+}
+/**
+ * Format a plain date-time as a relative day label plus time-of-day, e.g.
+ * "Tomorrow at 2:30 PM" — Moment's `.calendar()`, which the existing
+ * `formatRelativeDateTime` family does not cover (that family renders
+ * "in 1 day", an elapsed-time phrase, not a day label + clock time).
+ *
+ * - Within `±6` days of `reference` (default: now), renders `<day label>`
+ *   joined to the localized time using the locale's own connector — never a
+ *   hardcoded "at". The day label comes from `Intl.RelativeTimeFormat`
+ *   (`numeric: "auto"`), so it reads "Today"/"Tomorrow"/"Yesterday" near
+ *   the boundary and "in N days"/"N days ago" further out, all locale-native.
+ * - Beyond `±6` days, falls back to an absolute `dateStyle: "long"` +
+ *   `timeStyle` string with no relative wording, matching Moment's
+ *   `sameElse` behavior.
+ * - The connector between the day label and the time is read from CLDR's
+ *   own combined date+time pattern for the locale (see
+ *   `internal/joinDateTimeConnector.ts`), not hardcoded — this is what lets
+ *   `formatCalendar` avoid the i18n objection that excludes a token
+ *   formatter (Decision 1 in `context/roadmap/issues/J.md`).
+ * - Use `formatCalendar` for user-facing schedules ("Tomorrow at 2:30 PM");
+ *   use `formatRelativeDateTime` for elapsed-time displays ("in 1 day").
+ *
+ * @param value ISO PlainDateTime string to format
+ * @param locale optional: BCP 47 locale tag
+ * @param options optional: { reference, timeStyle }
+ * @returns the formatted calendar string, or "" on invalid input
+ *
+ * @example formatCalendar("2026-03-16T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendar("2026-03-08T14:30:00", "en-US", { reference: "2026-03-15T09:00:00" }) // "March 8, 2026 at 2:30 PM" (7 days out — beyond the threshold, absolute fallback)
+ * @example formatCalendar("not-a-date") // ""
+ */
+export declare function formatCalendar(value: string, locale?: string, options?: FormatCalendarOptions): string;