@northguild/gmt 1.14.2

package/dist/zoned/calculate/endOfZoned.js

@@ -0,0 +1,130 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeUnit } from "../../plain/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the end of the specified date-time `unit` for a given zoned ISO 8601 datetime string.
+ *
+ * - Converts to ZonedDateTime, sets to end of unit, converts back to string.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - `disambiguation` controls DST gap/overlap resolution when the boundary jump lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
+ * - `offset` controls whether the source's existing UTC offset is kept when computing the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the end
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string representing the end of the specified unit, or "" on invalid input
+ *
+ * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"
+ * @example endOfZoned("invalid", "month") // ""
+ * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "earlier" }) // "2024-11-03T01:59:59-04:00[America/New_York]" (source sits in the second, repeated 1am of the fall-back overlap; "earlier" resolves end-of-hour to the first (EDT) pass)
+ * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "reject" }) // "" (same overlap; "reject" throws because end-of-hour is ambiguous between the two 1am instants)
+ * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:59:59-05:00[America/New_York]" (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ */
+export function endOfZoned(value, unit, optionsArg) {
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
+    const disambiguation = optionsArg?.disambiguation ?? "compatible";
+    const offset = optionsArg?.offset ?? "ignore";
+    if (!isValidZonedDateTime(value) || !isValidDateTimeUnit(unit))
+        return "";
+    try {
+        const source = Temporal.ZonedDateTime.from(value);
+        let result;
+        switch (unit) {
+            case "year":
+                result = source.with({
+                    month: 12,
+                    day: 31,
+                    hour: 23,
+                    minute: 59,
+                    second: 59,
+                    millisecond: 999,
+                    microsecond: 999,
+                    nanosecond: 999,
+                }, { disambiguation, offset });
+                break;
+            case "month": {
+                const lastDay = Temporal.PlainDate.from({
+                    year: source.year,
+                    month: source.month,
+                    day: 1,
+                }).daysInMonth;
+                result = source.with({
+                    day: lastDay,
+                    hour: 23,
+                    minute: 59,
+                    second: 59,
+                    millisecond: 999,
+                    microsecond: 999,
+                    nanosecond: 999,
+                }, { disambiguation, offset });
+                break;
+            }
+            case "week": {
+                const daysToSubtract = weekStartsOn === "monday"
+                    ? source.dayOfWeek - 1
+                    : source.dayOfWeek % 7;
+                const endOfWeekDate = source
+                    .subtract({ days: daysToSubtract })
+                    .add({ days: 6 });
+                result = endOfWeekDate.with({
+                    hour: 23,
+                    minute: 59,
+                    second: 59,
+                    millisecond: 999,
+                    microsecond: 999,
+                    nanosecond: 999,
+                }, { disambiguation, offset });
+                break;
+            }
+            case "day":
+                result = source.with({
+                    hour: 23,
+                    minute: 59,
+                    second: 59,
+                    millisecond: 999,
+                    microsecond: 999,
+                    nanosecond: 999,
+                }, { disambiguation, offset });
+                break;
+            case "hour":
+                result = source.with({
+                    minute: 59,
+                    second: 59,
+                    millisecond: 999,
+                    microsecond: 999,
+                    nanosecond: 999,
+                }, { disambiguation, offset });
+                break;
+            case "minute":
+                result = source.with({ second: 59, millisecond: 999, microsecond: 999, nanosecond: 999 }, { disambiguation, offset });
+                break;
+            case "second":
+                result = source.with({ millisecond: 999, microsecond: 999, nanosecond: 999 }, { disambiguation, offset });
+                break;
+            case "millisecond":
+                result = source.with({ microsecond: 999, nanosecond: 999 }, { disambiguation, offset });
+                break;
+            case "microsecond":
+                result = source.with({ nanosecond: 999 }, { disambiguation, offset });
+                break;
+            case "nanosecond":
+                result = source; // Smallest unit, nothing to set
+                break;
+            default:
+                return "";
+        }
+        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
+        const precisionMap = {
+            millisecond: 3,
+            microsecond: 6,
+            nanosecond: 9,
+        };
+        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[unit] || 0);
+        return result.toString({ fractionalSecondDigits: fractionalDigits });
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/calculate/getHoursInZonedDay.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Return the number of hours in the calendar day a zoned datetime falls on.
+ *
+ * - Accounts for DST transitions: a spring-forward day is 23 hours, a fall-back
+ *   day is 25 hours, and a normal day is 24 hours. Zones whose DST shift isn't
+ *   a whole hour (e.g. `Australia/Lord_Howe`'s 30-minute shift) return a
+ *   fractional value instead, such as 23.5 or 24.5.
+ * - The calculation is based on the local calendar day of the input, not the
+ *   UTC instant.
+ * - Returns null for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns number of hours in the day (usually 23, 24, or 25; fractional for
+ *   non-whole-hour DST shifts), or null on invalid input
+ *
+ * @example getHoursInZonedDay("2024-03-10T12:00:00-04:00[America/New_York]") // 23
+ * @example getHoursInZonedDay("2024-11-03T12:00:00-05:00[America/New_York]") // 25
+ * @example getHoursInZonedDay("2024-02-29T12:00:00+00:00[UTC]")              // 24
+ * @example getHoursInZonedDay("2024-10-06T12:00:00+11:00[Australia/Lord_Howe]") // 23.5
+ * @example getHoursInZonedDay("invalid")                                      // null
+ */
+export declare function getHoursInZonedDay(value: string): number | null;

package/dist/zoned/calculate/getHoursInZonedDay.js

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the number of hours in the calendar day a zoned datetime falls on.
+ *
+ * - Accounts for DST transitions: a spring-forward day is 23 hours, a fall-back
+ *   day is 25 hours, and a normal day is 24 hours. Zones whose DST shift isn't
+ *   a whole hour (e.g. `Australia/Lord_Howe`'s 30-minute shift) return a
+ *   fractional value instead, such as 23.5 or 24.5.
+ * - The calculation is based on the local calendar day of the input, not the
+ *   UTC instant.
+ * - Returns null for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns number of hours in the day (usually 23, 24, or 25; fractional for
+ *   non-whole-hour DST shifts), or null on invalid input
+ *
+ * @example getHoursInZonedDay("2024-03-10T12:00:00-04:00[America/New_York]") // 23
+ * @example getHoursInZonedDay("2024-11-03T12:00:00-05:00[America/New_York]") // 25
+ * @example getHoursInZonedDay("2024-02-29T12:00:00+00:00[UTC]")              // 24
+ * @example getHoursInZonedDay("2024-10-06T12:00:00+11:00[Australia/Lord_Howe]") // 23.5
+ * @example getHoursInZonedDay("invalid")                                      // null
+ */
+export function getHoursInZonedDay(value) {
+    if (!isValidZonedDateTime(value)) {
+        return null;
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const startOfDay = zonedDateTime.with({
+            hour: 0,
+            minute: 0,
+            second: 0,
+            millisecond: 0,
+            microsecond: 0,
+            nanosecond: 0,
+        });
+        const nextDay = startOfDay.add({ days: 1 });
+        const duration = startOfDay.until(nextDay);
+        return duration.total({ unit: "hours" });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zoned/calculate/getLocaleZonedDayOfWeek.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Return the locale-relative day-of-week index for a zoned `value`.
+ *
+ * - `0` = the locale's first day of week (e.g. Sunday for en-US, Monday for fr-FR).
+ * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - Returns `null` if `value` is not a valid zoned ISO datetime or `locale` is unresolvable.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns locale-relative day-of-week index (0–6) or null on invalid input
+ *
+ * @example getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US") // 0 (Sunday)
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "en-US") // 1 (Monday)
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "fr-FR") // 0 (Monday)
+ * @example getLocaleZonedDayOfWeek("invalid-zoned", "en-US") // null
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "not-a-locale") // null
+ */
+export declare function getLocaleZonedDayOfWeek(value: string, locale: string): number | null;

package/dist/zoned/calculate/getLocaleZonedDayOfWeek.js

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the locale-relative day-of-week index for a zoned `value`.
+ *
+ * - `0` = the locale's first day of week (e.g. Sunday for en-US, Monday for fr-FR).
+ * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - Returns `null` if `value` is not a valid zoned ISO datetime or `locale` is unresolvable.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @returns locale-relative day-of-week index (0–6) or null on invalid input
+ *
+ * @example getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US") // 0 (Sunday)
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "en-US") // 1 (Monday)
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "fr-FR") // 0 (Monday)
+ * @example getLocaleZonedDayOfWeek("invalid-zoned", "en-US") // null
+ * @example getLocaleZonedDayOfWeek("2024-02-26T12:00:00+00:00[UTC]", "not-a-locale") // null
+ */
+export function getLocaleZonedDayOfWeek(value, locale) {
+    if (!isValidZonedDateTime(value))
+        return null;
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return null;
+    try {
+        const zoned = Temporal.ZonedDateTime.from(value);
+        return (zoned.dayOfWeek - firstDay + 7) % 7;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zoned/calculate/getLocaleZonedEndOfWeek.d.ts

@@ -0,0 +1,44 @@
+import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+/**
+ * Return the end of the week containing `value`, using `locale`'s first
+ * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
+ *   the last instant of the day.
+ * - Falls back to Monday-start (so the week ends Sunday) if the runtime's
+ *   `weekInfo` data doesn't resolve a first day for the locale.
+ * - `disambiguation` controls DST gap/overlap resolution when the
+ *   end-of-day reset lands on an ambiguous local time: "compatible"
+ *   (default, matches Temporal's default), "earlier", "later", or
+ *   "reject" (throws, resulting in "").
+ * - `offset` controls whether the source's existing UTC offset is kept
+ *   when resetting to end-of-day: "prefer" (Temporal's own default —
+ *   keeps the source offset whenever still valid, which **makes
+ *   `disambiguation` inert** for almost every case here), "use", "ignore"
+ *   (**this function's default** — always recomputes from time zone +
+ *   local time, discarding the stale offset; this is what makes
+ *   `disambiguation` actually take effect), or "reject" (throws if the
+ *   source offset is invalid for the new fields, independent of
+ *   `disambiguation`). Leave `offset` at its default unless you
+ *   specifically need Temporal's raw `.with()` semantics.
+ * - Distinct from `endOfZoned(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string for the end of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59+00:00[UTC]" (Saturday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-03-03T23:59:59+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedEndOfWeek("invalid", "en-US") // ""
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ */
+export declare function getLocaleZonedEndOfWeek(value: string, locale: string, optionsArg?: {
+    fractionalSecondDigits?: FractionalDigit;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/zoned/calculate/getLocaleZonedEndOfWeek.js

@@ -0,0 +1,68 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the end of the week containing `value`, using `locale`'s first
+ * day of week (e.g. en-US: week ends Saturday, fr-FR: week ends Sunday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
+ *   the last instant of the day.
+ * - Falls back to Monday-start (so the week ends Sunday) if the runtime's
+ *   `weekInfo` data doesn't resolve a first day for the locale.
+ * - `disambiguation` controls DST gap/overlap resolution when the
+ *   end-of-day reset lands on an ambiguous local time: "compatible"
+ *   (default, matches Temporal's default), "earlier", "later", or
+ *   "reject" (throws, resulting in "").
+ * - `offset` controls whether the source's existing UTC offset is kept
+ *   when resetting to end-of-day: "prefer" (Temporal's own default —
+ *   keeps the source offset whenever still valid, which **makes
+ *   `disambiguation` inert** for almost every case here), "use", "ignore"
+ *   (**this function's default** — always recomputes from time zone +
+ *   local time, discarding the stale offset; this is what makes
+ *   `disambiguation` actually take effect), or "reject" (throws if the
+ *   source offset is invalid for the new fields, independent of
+ *   `disambiguation`). Leave `offset` at its default unless you
+ *   specifically need Temporal's raw `.with()` semantics.
+ * - Distinct from `endOfZoned(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string for the end of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-03-02T23:59:59+00:00[UTC]" (Saturday)
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-03-03T23:59:59+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedEndOfWeek("invalid", "en-US") // ""
+ * @example getLocaleZonedEndOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ */
+export function getLocaleZonedEndOfWeek(value, locale, optionsArg) {
+    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits ?? 0;
+    const disambiguation = optionsArg?.disambiguation ?? "compatible";
+    const offset = optionsArg?.offset ?? "ignore";
+    if (!isValidZonedDateTime(value))
+        return "";
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return "";
+    try {
+        const source = Temporal.ZonedDateTime.from(value);
+        const daysToSubtract = (source.dayOfWeek - firstDay + 7) % 7;
+        const endOfWeekDate = source.add({ days: 6 - daysToSubtract });
+        const result = endOfWeekDate.with({
+            hour: 23,
+            minute: 59,
+            second: 59,
+            millisecond: 999,
+            microsecond: 999,
+            nanosecond: 999,
+        }, { disambiguation, offset });
+        return result.toString({ fractionalSecondDigits });
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/calculate/getLocaleZonedStartOfWeek.d.ts

@@ -0,0 +1,44 @@
+import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+/**
+ * Return the start of the week containing `value`, using `locale`'s
+ * first day of week (e.g. en-US: Sunday, fr-FR: Monday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
+ *   midnight.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - `disambiguation` controls DST gap/overlap resolution when the
+ *   midnight reset lands on an ambiguous local time: "compatible"
+ *   (default, matches Temporal's default), "earlier", "later", or
+ *   "reject" (throws, resulting in "").
+ * - `offset` controls whether the source's existing UTC offset is kept
+ *   when resetting to midnight: "prefer" (Temporal's own default — keeps
+ *   the source offset whenever still valid, which **makes
+ *   `disambiguation` inert** for almost every case here), "use", "ignore"
+ *   (**this function's default** — always recomputes from time zone +
+ *   local time, discarding the stale offset; this is what makes
+ *   `disambiguation` actually take effect), or "reject" (throws if the
+ *   source offset is invalid for the new fields, independent of
+ *   `disambiguation`). Leave `offset` at its default unless you
+ *   specifically need Temporal's raw `.with()` semantics.
+ * - Distinct from `startOfZoned(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string for the start of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-02-26T00:00:00+00:00[UTC]" (Monday)
+ * @example getLocaleZonedStartOfWeek("invalid", "en-US") // ""
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ */
+export declare function getLocaleZonedStartOfWeek(value: string, locale: string, optionsArg?: {
+    fractionalSecondDigits?: FractionalDigit;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/zoned/calculate/getLocaleZonedStartOfWeek.js

@@ -0,0 +1,68 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the start of the week containing `value`, using `locale`'s
+ * first day of week (e.g. en-US: Sunday, fr-FR: Monday).
+ *
+ * - Resolves the locale's first day of week via
+ *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
+ *   midnight.
+ * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
+ *   a first day for the locale.
+ * - `disambiguation` controls DST gap/overlap resolution when the
+ *   midnight reset lands on an ambiguous local time: "compatible"
+ *   (default, matches Temporal's default), "earlier", "later", or
+ *   "reject" (throws, resulting in "").
+ * - `offset` controls whether the source's existing UTC offset is kept
+ *   when resetting to midnight: "prefer" (Temporal's own default — keeps
+ *   the source offset whenever still valid, which **makes
+ *   `disambiguation` inert** for almost every case here), "use", "ignore"
+ *   (**this function's default** — always recomputes from time zone +
+ *   local time, discarding the stale offset; this is what makes
+ *   `disambiguation` actually take effect), or "reject" (throws if the
+ *   source offset is invalid for the new fields, independent of
+ *   `disambiguation`). Leave `offset` at its default unless you
+ *   specifically need Temporal's raw `.with()` semantics.
+ * - Distinct from `startOfZoned(value, "week", { weekStartsOn })`, which
+ *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
+ *   it from a locale.
+ * - Returns "" if `value` or `locale` is invalid.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string for the start of `value`'s locale-relative week, or "" on invalid input
+ *
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-02-26T00:00:00+00:00[UTC]" (Monday)
+ * @example getLocaleZonedStartOfWeek("invalid", "en-US") // ""
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ */
+export function getLocaleZonedStartOfWeek(value, locale, optionsArg) {
+    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits ?? 0;
+    const disambiguation = optionsArg?.disambiguation ?? "compatible";
+    const offset = optionsArg?.offset ?? "ignore";
+    if (!isValidZonedDateTime(value))
+        return "";
+    const firstDay = getLocaleFirstDayOfWeek(locale);
+    if (firstDay === null)
+        return "";
+    try {
+        const source = Temporal.ZonedDateTime.from(value);
+        const daysToSubtract = (source.dayOfWeek - firstDay + 7) % 7;
+        const startOfWeekDate = source.subtract({ days: daysToSubtract });
+        const result = startOfWeekDate.with({
+            hour: 0,
+            minute: 0,
+            second: 0,
+            millisecond: 0,
+            microsecond: 0,
+            nanosecond: 0,
+        }, { disambiguation, offset });
+        return result.toString({ fractionalSecondDigits });
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/calculate/getQuarterForZoned.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return the quarter of the year (1-4) for a given zoned ISO datetime.
+ *
+ * - Q1 = months 1-3, Q2 = months 4-6, Q3 = months 7-9, Q4 = months 10-12.
+ * - Validation is performed on the input.
+ *
+ * @param value ISO ZonedDateTime string
+ * @returns number (1-4) or null on invalid input
+ *
+ * @example getQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // 1
+ * @example getQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // 2
+ * @example getQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // 4
+ * @example getQuarterForZoned("invalid") // null
+ */
+export declare function getQuarterForZoned(value: string): number | null;

package/dist/zoned/calculate/getQuarterForZoned.js

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the quarter of the year (1-4) for a given zoned ISO datetime.
+ *
+ * - Q1 = months 1-3, Q2 = months 4-6, Q3 = months 7-9, Q4 = months 10-12.
+ * - Validation is performed on the input.
+ *
+ * @param value ISO ZonedDateTime string
+ * @returns number (1-4) or null on invalid input
+ *
+ * @example getQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // 1
+ * @example getQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // 2
+ * @example getQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // 4
+ * @example getQuarterForZoned("invalid") // null
+ */
+export function getQuarterForZoned(value) {
+    if (!isValidZonedDateTime(value)) {
+        return null;
+    }
+    try {
+        const zdt = Temporal.ZonedDateTime.from(value);
+        return Math.floor((zdt.month - 1) / 3) + 1;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zoned/calculate/index.d.ts

@@ -0,0 +1,23 @@
+export * from "./addZoned.js";
+export * from "./addZonedBusinessDays.js";
+export * from "./clampZoned.js";
+export * from "./closestZonedTo.js";
+export * from "./cycleZoned.js";
+export * from "./diffZoned.js";
+export * from "./diffZonedAsDuration.js";
+export * from "./endOfQuarterForZoned.js";
+export * from "./endOfZoned.js";
+export * from "./getHoursInZonedDay.js";
+export * from "./getLocaleZonedDayOfWeek.js";
+export * from "./getLocaleZonedEndOfWeek.js";
+export * from "./getLocaleZonedStartOfWeek.js";
+export * from "./getQuarterForZoned.js";
+export * from "./maxZoned.js";
+export * from "./minZoned.js";
+export * from "./roundZoned.js";
+export * from "./setZoned.js";
+export * from "./sortZoned.js";
+export * from "./startOfQuarterForZoned.js";
+export * from "./startOfZoned.js";
+export * from "./subtractZoned.js";
+export * from "./subtractZonedBusinessDays.js";

package/dist/zoned/calculate/index.js

@@ -0,0 +1,23 @@
+export * from "./addZoned.js";
+export * from "./addZonedBusinessDays.js";
+export * from "./clampZoned.js";
+export * from "./closestZonedTo.js";
+export * from "./cycleZoned.js";
+export * from "./diffZoned.js";
+export * from "./diffZonedAsDuration.js";
+export * from "./endOfQuarterForZoned.js";
+export * from "./endOfZoned.js";
+export * from "./getHoursInZonedDay.js";
+export * from "./getLocaleZonedDayOfWeek.js";
+export * from "./getLocaleZonedEndOfWeek.js";
+export * from "./getLocaleZonedStartOfWeek.js";
+export * from "./getQuarterForZoned.js";
+export * from "./maxZoned.js";
+export * from "./minZoned.js";
+export * from "./roundZoned.js";
+export * from "./setZoned.js";
+export * from "./sortZoned.js";
+export * from "./startOfQuarterForZoned.js";
+export * from "./startOfZoned.js";
+export * from "./subtractZoned.js";
+export * from "./subtractZonedBusinessDays.js";

package/dist/zoned/calculate/maxZoned.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return the latest (maximum) of the given ZonedDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param zonedDateTimes Array of ISO ZonedDateTime strings
+ * @returns The latest zoned datetime string, or null on invalid input
+ *
+ * @example maxZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
+ * @example maxZoned(["invalid", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
+ * @example maxZoned(["invalid", "also invalid"]) // null
+ * @example maxZoned([]) // null
+ */
+export declare function maxZoned(zonedDateTimes: string[]): string | null;

package/dist/zoned/calculate/maxZoned.js

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the latest (maximum) of the given ZonedDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param zonedDateTimes Array of ISO ZonedDateTime strings
+ * @returns The latest zoned datetime string, or null on invalid input
+ *
+ * @example maxZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
+ * @example maxZoned(["invalid", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
+ * @example maxZoned(["invalid", "also invalid"]) // null
+ * @example maxZoned([]) // null
+ */
+export function maxZoned(zonedDateTimes) {
+    if (!zonedDateTimes.length)
+        return null;
+    const valid = zonedDateTimes.filter(isValidZonedDateTime);
+    if (!valid.length)
+        return null;
+    try {
+        const max = valid.reduce((currentMax, candidateStr) => {
+            const candidate = Temporal.ZonedDateTime.from(candidateStr);
+            return Temporal.ZonedDateTime.compare(candidate, currentMax) > 0
+                ? candidate
+                : currentMax;
+        }, Temporal.ZonedDateTime.from(valid[0]));
+        return max.toString();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zoned/calculate/minZoned.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return the earliest (minimum) of the given ZonedDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param zonedDateTimes Array of ISO ZonedDateTime strings
+ * @returns The earliest zoned datetime string, or null on invalid input
+ *
+ * @example minZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-10T12:00:00-05:00[America/New_York]"
+ * @example minZoned(["invalid", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
+ * @example minZoned(["invalid", "also invalid"]) // null
+ * @example minZoned([]) // null
+ */
+export declare function minZoned(zonedDateTimes: string[]): string | null;