@northguild/gmt 1.14.2

package/dist/zoned/format/formatRfc3339.js

@@ -0,0 +1,37 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Format a zoned ISO 8601 datetime string as strict RFC 3339 — the ISO 8601
+ * *profile* RFC 3339 §5.6 defines, permitting only an explicit numeric
+ * offset or `Z`, never a bracketed IANA zone name.
+ *
+ * - **Not a passthrough.** GMT's own zoned strings always carry a bracketed
+ *   IANA zone annotation (e.g. `...+00:00[UTC]`) that plain
+ *   `Temporal.ZonedDateTime.prototype.toString()` reproduces by default —
+ *   that annotation is *not* valid RFC 3339. This function's only job is to
+ *   strip it (`{ timeZoneName: "never" }`), which is exactly the detail a
+ *   caller reaching for "give me RFC 3339" would otherwise miss. (Go/no-go
+ *   recorded in roadmap `issues/J.md` J13: this narrow gap is real; a
+ *   parallel `utc`/`unix` wrapper was *not* added, because
+ *   `Temporal.Instant.prototype.toString()` is already fully RFC 3339
+ *   compliant with no bracket to strip — that would be a pure passthrough.)
+ *
+ * @param value zoned ISO 8601 datetime string (e.g. "2024-03-15T14:30:00-04:00[America/New_York]")
+ * @returns RFC 3339 datetime string, or "" on invalid input
+ *
+ * @example formatRfc3339("2024-03-15T14:30:00-04:00[America/New_York]") // "2024-03-15T14:30:00-04:00"
+ * @example formatRfc3339("2024-03-15T14:30:00Z[UTC]") // "2024-03-15T14:30:00+00:00"
+ * @example formatRfc3339("invalid") // ""
+ */
+export function formatRfc3339(value) {
+    if (!isValidZonedDateTime(value))
+        return "";
+    try {
+        return Temporal.ZonedDateTime.from(value).toString({
+            timeZoneName: "never",
+        });
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/format/formatTimeZoneName.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Name style for `formatTimeZoneName`, mirroring
+ * `Intl.DateTimeFormatOptions`'s `timeZoneName` values.
+ */
+export type TimeZoneNameStyle = "short" | "long" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+export interface FormatTimeZoneNameOptions {
+    style?: TimeZoneNameStyle;
+}
+/**
+ * Return the localized display name for an IANA timeZone.
+ *
+ * - `options.style` covers every `Intl.DateTimeFormatOptions` `timeZoneName`
+ *   value: "short" (EST), "long" (Eastern Standard Time), "shortOffset"
+ *   (GMT-5), "longOffset" (GMT-05:00), "shortGeneric" (ET), "longGeneric"
+ *   (Eastern Time). Default "long".
+ * - "short"/"long"/"shortOffset"/"longOffset" name the zone's *current*
+ *   offset — for a DST-observing zone the label flips between standard and
+ *   daylight names depending on when this is called, since there's no
+ *   instant parameter to pin it to (this matches how
+ *   `Intl.DateTimeFormat.prototype.format()` itself defaults to "now" when
+ *   called with no argument). "shortGeneric"/"longGeneric" are
+ *   season-independent (e.g. "ET", "Eastern Time") and don't have this
+ *   issue — prefer them for a name that won't change twice a year.
+ * - Output depends on runtime ICU data.
+ * - Returns "" for an invalid timeZone or locale.
+ *
+ * @param timeZone IANA timeZone identifier
+ * @param locale BCP 47 locale tag (e.g. "en-US")
+ * @param options optional: { style } name style, default "long"
+ * @returns localized zone name, or "" on invalid input
+ *
+ * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"
+ * @example formatTimeZoneName("America/New_York", "en-US", { style: "longGeneric" }) // "Eastern Time"
+ * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortOffset" }) // "GMT-4" or "GMT-5", depending on the current date
+ * @example formatTimeZoneName("Asia/Tokyo", "ja-JP", { style: "longGeneric" }) // "日本標準時"
+ * @example formatTimeZoneName("Invalid/Zone", "en-US") // ""
+ * @example formatTimeZoneName("America/New_York", "!!!") // ""
+ */
+export declare function formatTimeZoneName(timeZone: string, locale: string, options?: FormatTimeZoneNameOptions): string;

package/dist/zoned/format/formatTimeZoneName.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../validate/index.js";
+/**
+ * Return the localized display name for an IANA timeZone.
+ *
+ * - `options.style` covers every `Intl.DateTimeFormatOptions` `timeZoneName`
+ *   value: "short" (EST), "long" (Eastern Standard Time), "shortOffset"
+ *   (GMT-5), "longOffset" (GMT-05:00), "shortGeneric" (ET), "longGeneric"
+ *   (Eastern Time). Default "long".
+ * - "short"/"long"/"shortOffset"/"longOffset" name the zone's *current*
+ *   offset — for a DST-observing zone the label flips between standard and
+ *   daylight names depending on when this is called, since there's no
+ *   instant parameter to pin it to (this matches how
+ *   `Intl.DateTimeFormat.prototype.format()` itself defaults to "now" when
+ *   called with no argument). "shortGeneric"/"longGeneric" are
+ *   season-independent (e.g. "ET", "Eastern Time") and don't have this
+ *   issue — prefer them for a name that won't change twice a year.
+ * - Output depends on runtime ICU data.
+ * - Returns "" for an invalid timeZone or locale.
+ *
+ * @param timeZone IANA timeZone identifier
+ * @param locale BCP 47 locale tag (e.g. "en-US")
+ * @param options optional: { style } name style, default "long"
+ * @returns localized zone name, or "" on invalid input
+ *
+ * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"
+ * @example formatTimeZoneName("America/New_York", "en-US", { style: "longGeneric" }) // "Eastern Time"
+ * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortOffset" }) // "GMT-4" or "GMT-5", depending on the current date
+ * @example formatTimeZoneName("Asia/Tokyo", "ja-JP", { style: "longGeneric" }) // "日本標準時"
+ * @example formatTimeZoneName("Invalid/Zone", "en-US") // ""
+ * @example formatTimeZoneName("America/New_York", "!!!") // ""
+ */
+export function formatTimeZoneName(timeZone, locale, options) {
+    if (!isValidTimeZone(timeZone)) {
+        return "";
+    }
+    try {
+        new Intl.Locale(locale);
+    }
+    catch {
+        return "";
+    }
+    try {
+        const style = options?.style ?? "long";
+        const formatter = new Intl.DateTimeFormat(locale, {
+            timeZone,
+            timeZoneName: style,
+            hour: "numeric",
+        });
+        const parts = formatter.formatToParts(Temporal.Now.instant().epochMilliseconds);
+        return parts.find((part) => part.type === "timeZoneName")?.value ?? "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/format/formatZonedDateTime.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Format a zoned ISO 8601 datetime string using the Intl.DateTimeFormat implementation.
+ *
+ * - Uses Temporal.ZonedDateTime.toLocaleString for formatting.
+ * - Accepts optional locale and Intl.DateTimeFormatOptions.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale optional locale tag (e.g. "en-US")
+ * @param options optional Intl.DateTimeFormatOptions
+ * @returns localized string or "" when invalid
+ *
+ * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "long" }) // "February 29, 2024 at 12:34:56 PM Coordinated Universal Time"
+ * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:34"
+ * @example formatZonedDateTime("invalid", "en-US") // "" (invalid input)
+ */
+export declare function formatZonedDateTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;

package/dist/zoned/format/formatZonedDateTime.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { normalizeDateTime } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Format a zoned ISO 8601 datetime string using the Intl.DateTimeFormat implementation.
+ *
+ * - Uses Temporal.ZonedDateTime.toLocaleString for formatting.
+ * - Accepts optional locale and Intl.DateTimeFormatOptions.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale optional locale tag (e.g. "en-US")
+ * @param options optional Intl.DateTimeFormatOptions
+ * @returns localized string or "" when invalid
+ *
+ * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "long" }) // "February 29, 2024 at 12:34:56 PM Coordinated Universal Time"
+ * @example formatZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:34"
+ * @example formatZonedDateTime("invalid", "en-US") // "" (invalid input)
+ */
+export function formatZonedDateTime(value, locale, options) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const out = zonedDateTime.toLocaleString(locale, options);
+        return normalizeDateTime(out);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/format/formatZonedRange.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
+ *
+ * - Both datetimes must have the same timezone.
+ * - Uses Temporal.ZonedDateTime.toInstant for formatting.
+ * - Returns "" for invalid input or mismatched timezones.
+ *
+ * @param from zoned ISO 8601 datetime string (range start)
+ * @param to zoned ISO 8601 datetime string (range end)
+ * @param locale optional locale tag
+ * @param options optional Intl.DateTimeFormatOptions
+ * @returns localized range string or "" when invalid
+ *
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024 at 12:00 PM – 2:00 PM Coordinated Universal Time"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00 – 14:00"
+ * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US") // "" (invalid input)
+ */
+export declare function formatZonedRange(from: string, to: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;

package/dist/zoned/format/formatZonedRange.js

@@ -0,0 +1,48 @@
+import { Temporal, Intl as TemporalIntl } from "@js-temporal/polyfill";
+import { normalizeDateTime } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
+ *
+ * - Both datetimes must have the same timezone.
+ * - Uses Temporal.ZonedDateTime.toInstant for formatting.
+ * - Returns "" for invalid input or mismatched timezones.
+ *
+ * @param from zoned ISO 8601 datetime string (range start)
+ * @param to zoned ISO 8601 datetime string (range end)
+ * @param locale optional locale tag
+ * @param options optional Intl.DateTimeFormatOptions
+ * @returns localized range string or "" when invalid
+ *
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024 at 12:00 PM – 2:00 PM Coordinated Universal Time"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00 – 14:00"
+ * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US") // "" (invalid input)
+ */
+export function formatZonedRange(from, to, locale, options) {
+    if (!isValidZonedDateTime(from) || !isValidZonedDateTime(to)) {
+        return "";
+    }
+    let zdt1;
+    let zdt2;
+    try {
+        zdt1 = Temporal.ZonedDateTime.from(from);
+        zdt2 = Temporal.ZonedDateTime.from(to);
+    }
+    catch {
+        return "";
+    }
+    if (zdt1.timeZoneId !== zdt2.timeZoneId) {
+        return "";
+    }
+    const formatOptions = {
+        ...options,
+        timeZone: zdt1.timeZoneId,
+    };
+    try {
+        const out = new TemporalIntl.DateTimeFormat(locale, formatOptions).formatRange(zdt1.toInstant(), zdt2.toInstant());
+        return normalizeDateTime(out);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/format/formatZonedToParts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Return the locale-formatted parts of a ZonedDateTime.
+ *
+ * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
+ *   `format`). A token pattern hard-codes field order and ships US ordering to
+ *   every locale; `formatToParts` gives the caller full control over presentation
+ *   while the *locale* keeps control of order. See Decision 1 in
+ *   `context/roadmap/issues/J.md`.
+ * - Each part is `{ type, value }` where `type` can be:
+ *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"hour"`,
+ *   `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
+ *   `"timeZoneName"`, `"literal"`.
+ * - The caller should iterate the array as returned; reassembling in a fixed
+ *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - Returns `[]` for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale optional locale tag (e.g. "en-US")
+ * @param options optional Intl.DateTimeFormatOptions
+ * @returns array of `{ type, value }` parts, or `[]` on invalid input
+ *
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // includes { type: "timeZoneName", value: "GMT-4" }
+ * @example formatZonedToParts("invalid", "en-US") // []
+ */
+export declare function formatZonedToParts(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): Array<{
+    type: string;
+    value: string;
+}>;

package/dist/zoned/format/formatZonedToParts.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the locale-formatted parts of a ZonedDateTime.
+ *
+ * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
+ *   `format`). A token pattern hard-codes field order and ships US ordering to
+ *   every locale; `formatToParts` gives the caller full control over presentation
+ *   while the *locale* keeps control of order. See Decision 1 in
+ *   `context/roadmap/issues/J.md`.
+ * - Each part is `{ type, value }` where `type` can be:
+ *   `"era"`, `"year"`, `"month"`, `"day"`, `"weekday"`, `"hour"`,
+ *   `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
+ *   `"timeZoneName"`, `"literal"`.
+ * - The caller should iterate the array as returned; reassembling in a fixed
+ *   order reintroduces exactly the bug `formatToParts` exists to avoid.
+ * - Returns `[]` for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param locale optional locale tag (e.g. "en-US")
+ * @param options optional Intl.DateTimeFormatOptions
+ * @returns array of `{ type, value }` parts, or `[]` on invalid input
+ *
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // includes { type: "timeZoneName", value: "GMT-4" }
+ * @example formatZonedToParts("invalid", "en-US") // []
+ */
+export function formatZonedToParts(value, locale, options) {
+    if (!isValidZonedDateTime(value)) {
+        return [];
+    }
+    try {
+        // Intl.DateTimeFormat cannot format a Temporal.ZonedDateTime directly —
+        // pass its instant (epochMilliseconds) and its own IANA zone as the
+        // formatter's timeZone, mirroring formatTimeZoneName's approach.
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const formatter = new Intl.DateTimeFormat(locale, {
+            timeZone: zonedDateTime.timeZoneId,
+            ...options,
+        });
+        return formatter
+            .formatToParts(zonedDateTime.epochMilliseconds)
+            .map((p) => ({ type: p.type, value: p.value }));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,8 @@
+export * from "./formatCalendarZoned.js";
+export * from "./formatRelativeZoned.js";
+export * from "./formatRfc2822.js";
+export * from "./formatRfc3339.js";
+export * from "./formatTimeZoneName.js";
+export * from "./formatZonedDateTime.js";
+export * from "./formatZonedRange.js";
+export * from "./formatZonedToParts.js";

package/dist/zoned/format/index.js

@@ -0,0 +1,8 @@
+export * from "./formatCalendarZoned.js";
+export * from "./formatRelativeZoned.js";
+export * from "./formatRfc2822.js";
+export * from "./formatRfc3339.js";
+export * from "./formatTimeZoneName.js";
+export * from "./formatZonedDateTime.js";
+export * from "./formatZonedRange.js";
+export * from "./formatZonedToParts.js";

package/dist/zoned/get/getDstTransitions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A single DST transition instant, with the UTC offset in effect immediately
+ * before and after the change.
+ */
+export interface DstTransition {
+    instant: string;
+    offsetBefore: string;
+    offsetAfter: string;
+}
+/**
+ * List every DST transition instant for an IANA timezone within a given year.
+ *
+ * - A "transition" is any UTC offset change: a spring-forward gap (nonexistent
+ *   local time) or a fall-back overlap (ambiguous local time) — see
+ *   `docs/dst-disambiguation.md` for the gap/overlap terminology. This is
+ *   distinct from `hasDaylightSaving` (whether a zone observes DST at all)
+ *   and from the `disambiguation`/`offset` options (what to do when
+ *   constructing a single instant that lands in a gap/overlap).
+ * - Most zones have 0 or 2 transitions per year; some (e.g. `Africa/Casablanca`,
+ *   which pauses DST for Ramadan) can have more.
+ * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
+ *   with zero transitions in that year (not an error case).
+ *
+ * @param timeZone IANA timeZone identifier
+ * @param year calendar year to scan (must be an integer)
+ * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
+ *
+ * @example getDstTransitions("America/New_York", 2024)
+ * // [
+ * //   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
+ * //   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
+ * // ]
+ * @example getDstTransitions("Asia/Tokyo", 2024) // []
+ * @example getDstTransitions("Invalid/Zone", 2024) // []
+ */
+export declare function getDstTransitions(timeZone: string, year: number): DstTransition[];

package/dist/zoned/get/getDstTransitions.js

@@ -0,0 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../validate/index.js";
+const MAX_TRANSITIONS_PER_YEAR = 20;
+/**
+ * List every DST transition instant for an IANA timezone within a given year.
+ *
+ * - A "transition" is any UTC offset change: a spring-forward gap (nonexistent
+ *   local time) or a fall-back overlap (ambiguous local time) — see
+ *   `docs/dst-disambiguation.md` for the gap/overlap terminology. This is
+ *   distinct from `hasDaylightSaving` (whether a zone observes DST at all)
+ *   and from the `disambiguation`/`offset` options (what to do when
+ *   constructing a single instant that lands in a gap/overlap).
+ * - Most zones have 0 or 2 transitions per year; some (e.g. `Africa/Casablanca`,
+ *   which pauses DST for Ramadan) can have more.
+ * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
+ *   with zero transitions in that year (not an error case).
+ *
+ * @param timeZone IANA timeZone identifier
+ * @param year calendar year to scan (must be an integer)
+ * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
+ *
+ * @example getDstTransitions("America/New_York", 2024)
+ * // [
+ * //   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
+ * //   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
+ * // ]
+ * @example getDstTransitions("Asia/Tokyo", 2024) // []
+ * @example getDstTransitions("Invalid/Zone", 2024) // []
+ */
+export function getDstTransitions(timeZone, year) {
+    if (!isValidTimeZone(timeZone) || !Number.isInteger(year)) {
+        return [];
+    }
+    try {
+        let cur = Temporal.ZonedDateTime.from({
+            year,
+            month: 1,
+            day: 1,
+            hour: 0,
+            minute: 0,
+            second: 0,
+            timeZone,
+        });
+        const transitions = [];
+        for (let i = 0; i < MAX_TRANSITIONS_PER_YEAR; i++) {
+            const next = cur.getTimeZoneTransition("next");
+            if (!next || next.year > year) {
+                break;
+            }
+            transitions.push({
+                instant: next.toInstant().toString(),
+                offsetBefore: cur.offset,
+                offsetAfter: next.offset,
+            });
+            cur = next;
+        }
+        return transitions;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/zoned/get/getSystemTimeZone.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Return the runtime system timeZone name (for example "America/New_York").
+ *
+ * - Uses Intl.DateTimeFormat().resolvedOptions().timeZone to get system timezone.
+ * - Returns "" when timezone is unavailable.
+ *
+ * @returns system timeZone name or "" on failure
+ *
+ * @example getSystemTimeZone() // "America/New_York"
+ */
+export declare function getSystemTimeZone(): string;

package/dist/zoned/get/getSystemTimeZone.js

@@ -0,0 +1,19 @@
+/**
+ * Return the runtime system timeZone name (for example "America/New_York").
+ *
+ * - Uses Intl.DateTimeFormat().resolvedOptions().timeZone to get system timezone.
+ * - Returns "" when timezone is unavailable.
+ *
+ * @returns system timeZone name or "" on failure
+ *
+ * @example getSystemTimeZone() // "America/New_York"
+ */
+export function getSystemTimeZone() {
+    try {
+        const systemTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        return systemTimeZone || "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/get/getTimeZoneOffset.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return an IANA timeZone's UTC offset at a given instant.
+ *
+ * - Unlike `getZonedOffset`, this doesn't need an existing zoned value in
+ *   hand — pass any timeZone identifier and an instant to look up, which is
+ *   why (like `getDstTransitions`) it lives in `get/` despite taking two
+ *   arguments: neither is a date *value* being described, both are
+ *   coordinates for a zone-level lookup.
+ * - Returns "" for an invalid timeZone or instant.
+ *
+ * @param timeZone IANA timeZone identifier
+ * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
+ * @returns offset string (e.g. "-04:00"), or "" on invalid input
+ *
+ * @example getTimeZoneOffset("America/New_York", "2024-07-15T12:00:00Z") // "-04:00"
+ * @example getTimeZoneOffset("America/New_York", "2024-01-15T12:00:00Z") // "-05:00"
+ * @example getTimeZoneOffset("Asia/Kathmandu", "2024-01-15T12:00:00Z") // "+05:45"
+ * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
+ * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
+ */
+export declare function getTimeZoneOffset(timeZone: string, instant: string): string;

package/dist/zoned/get/getTimeZoneOffset.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../validate/index.js";
+/**
+ * Return an IANA timeZone's UTC offset at a given instant.
+ *
+ * - Unlike `getZonedOffset`, this doesn't need an existing zoned value in
+ *   hand — pass any timeZone identifier and an instant to look up, which is
+ *   why (like `getDstTransitions`) it lives in `get/` despite taking two
+ *   arguments: neither is a date *value* being described, both are
+ *   coordinates for a zone-level lookup.
+ * - Returns "" for an invalid timeZone or instant.
+ *
+ * @param timeZone IANA timeZone identifier
+ * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
+ * @returns offset string (e.g. "-04:00"), or "" on invalid input
+ *
+ * @example getTimeZoneOffset("America/New_York", "2024-07-15T12:00:00Z") // "-04:00"
+ * @example getTimeZoneOffset("America/New_York", "2024-01-15T12:00:00Z") // "-05:00"
+ * @example getTimeZoneOffset("Asia/Kathmandu", "2024-01-15T12:00:00Z") // "+05:45"
+ * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
+ * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
+ */
+export function getTimeZoneOffset(timeZone, instant) {
+    if (!isValidTimeZone(timeZone)) {
+        return "";
+    }
+    try {
+        return Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone).offset;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/get/getTimeZones.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Return the array of all available IANA timezone identifiers.
+ *
+ * - Uses `Intl.supportedValuesOf('timeZone')` to get the full list.
+ * - Returns `[]` when the API is unavailable (older runtimes).
+ *
+ * @returns array of IANA timezone identifier strings, or `[]` on failure
+ *
+ * @example getTimeZones() // ["America/New_York", "Europe/London", ...]
+ * @example getTimeZones().length // ~422 (varies by runtime/ICU)
+ */
+export declare function getTimeZones(): string[];

package/dist/zoned/get/getTimeZones.js

@@ -0,0 +1,19 @@
+/**
+ * Return the array of all available IANA timezone identifiers.
+ *
+ * - Uses `Intl.supportedValuesOf('timeZone')` to get the full list.
+ * - Returns `[]` when the API is unavailable (older runtimes).
+ *
+ * @returns array of IANA timezone identifier strings, or `[]` on failure
+ *
+ * @example getTimeZones() // ["America/New_York", "Europe/London", ...]
+ * @example getTimeZones().length // ~422 (varies by runtime/ICU)
+ */
+export function getTimeZones() {
+    try {
+        return Intl.supportedValuesOf("timeZone") || [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/zoned/get/getZonedDay.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Return the current day of month for the specified IANA timeZone.
+ *
+ * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
+ * - Validation is performed on the timezone.
+ *
+ * @param ianaTimezone IANA timeZone identifier
+ * @returns current day string (zero-padded to 2 digits) or "" on invalid input
+ *
+ * @example getZonedDay("America/New_York") // "28"
+ * @example getZonedDay("invalid") // ""
+ */
+export declare function getZonedDay(ianaTimezone: string): string;

package/dist/zoned/get/getZonedDay.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../validate/index.js";
+/**
+ * Return the current day of month for the specified IANA timeZone.
+ *
+ * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
+ * - Validation is performed on the timezone.
+ *
+ * @param ianaTimezone IANA timeZone identifier
+ * @returns current day string (zero-padded to 2 digits) or "" on invalid input
+ *
+ * @example getZonedDay("America/New_York") // "28"
+ * @example getZonedDay("invalid") // ""
+ */
+export function getZonedDay(ianaTimezone) {
+    if (!isValidTimeZone(ianaTimezone))
+        return "";
+    try {
+        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
+            .day.toString()
+            .padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/get/getZonedDayOfWeek.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the current day of week for the specified IANA timeZone.
+ *
+ * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
+ * - Returns 1-7 (Monday=1 through Sunday=7).
+ * - Validation is performed on the timezone.
+ *
+ * @param ianaTimezone IANA timeZone identifier
+ * @returns current day of week number (1-7) or null on invalid input
+ *
+ * @example getZonedDayOfWeek("America/New_York") // 3
+ * @example getZonedDayOfWeek("invalid") // null
+ */
+export declare function getZonedDayOfWeek(ianaTimezone: string): number | null;