@northguild/gmt 1.17.0 → 1.19.0

package/dist/zoned/format/formatRfc3339.js

@@ -11,9 +11,8 @@ const NANOSECONDS_PER_MINUTE = 60_000_000_000;
  *   `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
+ *   caller reaching for "give me RFC 3339" would otherwise miss. (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.)
  * - **Sub-minute offsets are written in UTC.** `time-numoffset` holds whole minutes, and RFC 3339

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

@@ -18,7 +18,16 @@
  * const s: TimeZoneNameStyle = "shortGeneric";
  */
 export type TimeZoneNameStyle = "short" | "long" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+/** Options for `formatTimeZoneName`: the form the zone name is written in. */
 export interface FormatTimeZoneNameOptions {
+    /**
+     * The form of the name, one of `Intl.DateTimeFormat`'s `timeZoneName` values. `"short"` and
+     * `"long"` give the abbreviated or full name and `"shortOffset"` and `"longOffset"` the UTC
+     * offset, all four for the offset in effect now. `"shortGeneric"` and `"longGeneric"` give a name
+     * that does not change with daylight saving.
+     *
+     * @defaultValue `"long"`
+     */
     style?: TimeZoneNameStyle;
 }
 /**
@@ -27,7 +36,7 @@ export interface FormatTimeZoneNameOptions {
  * - `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".
+ *   (Eastern Time).
  * - "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
@@ -38,10 +47,14 @@ export interface FormatTimeZoneNameOptions {
  *   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.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @param locale BCP 47 locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: { style } name style, default "long"
+ * @param options optional setting for the form of the name
  * @returns localized zone name, or "" on invalid input
  *
  * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"

package/dist/zoned/format/formatTimeZoneName.js

@@ -2,13 +2,14 @@ import { Temporal } from "@js-temporal/polyfill";
 import { resolveRequiredLocale } from "../../internal/resolveLocale.js";
 import { isValidTimeZone } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.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".
+ *   (Eastern Time).
  * - "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
@@ -19,10 +20,14 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   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.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @param locale BCP 47 locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: { style } name style, default "long"
+ * @param options optional setting for the form of the name
  * @returns localized zone name, or "" on invalid input
  *
  * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"
@@ -45,7 +50,7 @@ export function formatTimeZoneName(timeZone, locale, options) {
         if (resolvedLocale === null)
             return "";
         try {
-            const style = options?.style === undefined ? "long" : options.style;
+            const style = optionOrDefault(options?.style, "long");
             const formatter = new Intl.DateTimeFormat(resolvedLocale, {
                 timeZone,
                 timeZoneName: style,

package/dist/zoned/format/formatZonedDateTime.js

@@ -1,6 +1,7 @@
 import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Format a zoned ISO 8601 datetime string using the Intl.DateTimeFormat implementation.
  *
@@ -51,7 +52,7 @@ export function formatZonedDateTime(value, locale, options) {
         // (GetDateTimeFormat ~any~, ~zoned-date-time~, ~all~), so the requested
         // fields and widths are kept.
         const zonedDateTime = zonedDateTimeFrom(value);
-        const resolved = instantFormatOptions(options ?? {}, zonedDateTime.timeZoneId, "zoned-date-time");
+        const resolved = instantFormatOptions(readDateTimeFormatOptions(options), zonedDateTime.timeZoneId, "zoned-date-time");
         if (resolved === null) {
             return "";
         }

package/dist/zoned/format/formatZonedRange.js

@@ -1,6 +1,7 @@
 import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Format a zoned datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -61,7 +62,7 @@ export function formatZonedRange(from, to, locale, options) {
         // an Instant format resolves to (GetDateTimeFormat ~any~, ~all~, ~all~), so
         // the requested fields and widths are kept. A `timeZone` option is rejected
         // rather than silently overridden.
-        const formatOptions = instantFormatOptions(options ?? {}, zdt1.timeZoneId, "all");
+        const formatOptions = instantFormatOptions(readDateTimeFormatOptions(options), zdt1.timeZoneId, "all");
         if (formatOptions === null) {
             return "";
         }

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

@@ -5,8 +5,7 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * - 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`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
@@ -24,8 +23,11 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   whitespace normalisation.
  * - A ZonedDateTime is formatted in its own zone: a `timeZone` option returns
  *   `[]`, as `ZonedDateTime#toLocaleString` throws a TypeError for one.
- * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
- *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
+ * - The literal before the day period depends on the runtime. CLDR 42 (ICU 72) put U+202F NARROW
+ *   NO-BREAK SPACE there for `en-US`; Node 22 and 24 return it in the parts, and Node 26 returns
+ *   an ordinary space (U+0020) instead. Both were checked on those runtimes. The examples show the
+ *   Node 22 and 24 form, written as `"\u202f"` so the difference is visible. Treat the two
+ *   characters as equal when you compare parts.
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts, with
  *   no time zone name. Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
@@ -48,6 +50,15 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * @example formatZonedToParts("2024-02-03T14:30:00-05:00[America/New_York]", "en-US", null as never) // [] (null options, as ECMA-402 rejects them)
  */
 export declare function formatZonedToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
+    /**
+     * The kind of part, named as ECMA-402 `Intl.DateTimeFormat.prototype.formatToParts` names it: a
+     * field such as `"year"`, `"month"` or `"day"`, or `"literal"` for the separator text between
+     * fields.
+     */
     type: string;
+    /**
+     * The text of the part in the requested locale, exactly as the formatter wrote it. Joining every
+     * `value` in array order gives the whole formatted text.
+     */
     value: string;
 }>;

package/dist/zoned/format/formatZonedToParts.js

@@ -1,14 +1,14 @@
 import { isValidZonedDateTime } from "../validate/index.js";
 import { zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.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`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
@@ -26,8 +26,11 @@ import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
  *   whitespace normalisation.
  * - A ZonedDateTime is formatted in its own zone: a `timeZone` option returns
  *   `[]`, as `ZonedDateTime#toLocaleString` throws a TypeError for one.
- * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
- *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
+ * - The literal before the day period depends on the runtime. CLDR 42 (ICU 72) put U+202F NARROW
+ *   NO-BREAK SPACE there for `en-US`; Node 22 and 24 return it in the parts, and Node 26 returns
+ *   an ordinary space (U+0020) instead. Both were checked on those runtimes. The examples show the
+ *   Node 22 and 24 form, written as `"\u202f"` so the difference is visible. Treat the two
+ *   characters as equal when you compare parts.
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts, with
  *   no time zone name. Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
@@ -63,7 +66,7 @@ export function formatZonedToParts(value, locale, options) {
         // formatter's timeZone, with the options ZonedDateTime#toLocaleString
         // resolves to (GetDateTimeFormat ~any~, ~zoned-date-time~, ~all~).
         const zonedDateTime = zonedDateTimeFrom(value);
-        const resolved = instantFormatOptions(options ?? {}, zonedDateTime.timeZoneId, "zoned-date-time");
+        const resolved = instantFormatOptions(readDateTimeFormatOptions(options), zonedDateTime.timeZoneId, "zoned-date-time");
         if (resolved === null) {
             return [];
         }

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

@@ -2,14 +2,6 @@
  * A single DST transition instant: the UTC instant of an offset change plus the
  * offset in effect immediately before and after it.
  *
- * @remarks Members:
- *
- * | Member | Type | Description |
- * | --- | --- | --- |
- * | `instant` | `string` | UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-03-10T07:00:00Z`). |
- * | `offsetBefore` | `string` | UTC offset in effect immediately before the transition (e.g. `-05:00`). |
- * | `offsetAfter` | `string` | UTC offset in effect immediately after the transition (e.g. `-04:00`). |
- *
  * @example
  * import { DstTransition } from "@northguild/gmt/zoned";
  * const t: DstTransition = {
@@ -19,12 +11,16 @@
  * };
  */
 export interface DstTransition {
+    /** The UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-03-10T07:00:00Z`). */
     instant: string;
+    /** The UTC offset in effect immediately before the transition (e.g. `-05:00`). */
     offsetBefore: string;
+    /** The UTC offset in effect immediately after the transition (e.g. `-04:00`). */
     offsetAfter: string;
 }
 /**
- * List every DST transition instant for an IANA timezone within a given year.
+ * List every DST transition instant for a time zone (an IANA name or a UTC offset) 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
@@ -39,8 +35,11 @@ export interface DstTransition {
  * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
  *   with zero transitions in that year (not an error case), and when the scan
  *   exhausts its internal bound — never a partial list.
+ * - A UTC offset, with or without seconds (`"+05:30"`, `"-00:44:30"`), never changes, so it has no
+ *   transitions and returns `[]` for every year.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
+ *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @param year calendar year to scan (must be an integer)
  * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
  *
@@ -52,6 +51,8 @@ export interface DstTransition {
  * @example getDstTransitions("Asia/Singapore", 1982)
  * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]
  * @example getDstTransitions("Asia/Tokyo", 2024) // []
+ * @example getDstTransitions("+05:30", 2024) // [] (a fixed offset has no transitions)
  * @example getDstTransitions("Invalid/Zone", 2024) // []
+ * @example getDstTransitions("-00:44:30", 1970) // [] (a fixed offset)
  */
 export declare function getDstTransitions(timeZone: string, year: number): DstTransition[];

package/dist/zoned/get/getDstTransitions.js

@@ -1,8 +1,10 @@
-import { isValidTimeZone } from "../validate/index.js";
-import { zonedDateTimeFrom, zonedNextTransition, zonedStartOfDay, } from "../../internal/index.js";
+import { zonedDateTimeFrom, zonedNextTransition, zonedStartOfDay, zoneFrame, } from "../../internal/index.js";
 const MAX_TRANSITIONS_PER_YEAR = 20;
+/** 368 days: a 366-day year plus a day at each end for the zone's offset. */
+const SEARCH_SPAN_NANOSECONDS = 368n * 86400000000000n;
 /**
- * List every DST transition instant for an IANA timezone within a given year.
+ * List every DST transition instant for a time zone (an IANA name or a UTC offset) 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
@@ -17,8 +19,11 @@ const MAX_TRANSITIONS_PER_YEAR = 20;
  * - Returns `[]` for an invalid timeZone, a non-integer year, or a valid zone
  *   with zero transitions in that year (not an error case), and when the scan
  *   exhausts its internal bound — never a partial list.
+ * - A UTC offset, with or without seconds (`"+05:30"`, `"-00:44:30"`), never changes, so it has no
+ *   transitions and returns `[]` for every year.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
+ *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @param year calendar year to scan (must be an integer)
  * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
  *
@@ -30,21 +35,30 @@ const MAX_TRANSITIONS_PER_YEAR = 20;
  * @example getDstTransitions("Asia/Singapore", 1982)
  * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]
  * @example getDstTransitions("Asia/Tokyo", 2024) // []
+ * @example getDstTransitions("+05:30", 2024) // [] (a fixed offset has no transitions)
  * @example getDstTransitions("Invalid/Zone", 2024) // []
+ * @example getDstTransitions("-00:44:30", 1970) // [] (a fixed offset)
  */
 export function getDstTransitions(timeZone, year) {
-    if (!isValidTimeZone(timeZone) || !Number.isInteger(year)) {
+    const frame = zoneFrame(timeZone);
+    // A stored offset with seconds is a fixed offset: it has no transitions, as "-00:45" has none.
+    if (frame === null ||
+        frame.shiftNanoseconds !== 0n ||
+        !Number.isInteger(year)) {
         return [];
     }
     try {
         // getTimeZoneTransition("next") is strictly after its receiver, so start 1ns before the
         // year opens to catch a transition landing exactly on local January 1 00:00.
-        let cur = zonedStartOfDay(zonedDateTimeFrom({ year, month: 1, day: 1, timeZone })).subtract({ nanoseconds: 1 });
+        let cur = zonedStartOfDay(zonedDateTimeFrom({ year, month: 1, day: 1, timeZone: frame.timeZone })).subtract({ nanoseconds: 1 });
+        // A calendar year is at most 366 days and an offset is under a day, so no search needs to
+        // read past this.
+        const searchEnd = cur.epochNanoseconds + SEARCH_SPAN_NANOSECONDS;
         const transitions = [];
         // `<=`: up to MAX in-year transitions are pushed, plus one more lookup to observe the scan
         // leaving the year.
         for (let i = 0; i <= MAX_TRANSITIONS_PER_YEAR; i++) {
-            const next = zonedNextTransition(cur);
+            const next = zonedNextTransition(cur, searchEnd);
             if (!next || next.year > year) {
                 return transitions;
             }

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

@@ -2,7 +2,9 @@
  * 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 "" when the host reports no usable time zone. With an empty `TZ` the runtime reports
+ *   ICU's placeholder `"Etc/Unknown"`, and with an unrecognised `TZ` it reports `undefined`;
+ *   neither is a zone that Temporal or `Intl.DateTimeFormat` accepts.
  *
  * @returns system timeZone name or "" on failure
  *

package/dist/zoned/get/getSystemTimeZone.js

@@ -1,8 +1,11 @@
+import { isValidTimeZone } from "../validate/isValidTimeZone.js";
 /**
  * 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 "" when the host reports no usable time zone. With an empty `TZ` the runtime reports
+ *   ICU's placeholder `"Etc/Unknown"`, and with an unrecognised `TZ` it reports `undefined`;
+ *   neither is a zone that Temporal or `Intl.DateTimeFormat` accepts.
  *
  * @returns system timeZone name or "" on failure
  *
@@ -11,7 +14,7 @@
 export function getSystemTimeZone() {
     try {
         const systemTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-        return systemTimeZone || "";
+        return isValidTimeZone(systemTimeZone) ? systemTimeZone : "";
     }
     catch {
         return "";

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

@@ -1,5 +1,5 @@
 /**
- * Return an IANA timeZone's UTC offset at a given instant.
+ * Return a time zone'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
@@ -14,14 +14,25 @@
  * - The instant is ISO 8601 extended format before any annotation (`<date>T<time>`, then `Z` or
  *   `±HH:MM[:SS[.fraction]]`): basic format, a `t` or space separator, a lower-case `z` and an
  *   hour-only offset return "".
+ * - Only the instant is read from `instant`, as `isValidInstant` describes it: a bracketed zone
+ *   in it is not validated, and an offset written to the minute that is that zone's sub-minute
+ *   offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives.
+ * - The result is `±HH:MM`, or `±HH:MM:SS` where the zone was not on a whole minute
+ *   (`Africa/Monrovia` stood at `-00:44:30` until 1972). It goes straight into the time zone
+ *   position of any function whose result has no zone in it, and of this one: a UTC offset is its
+ *   own answer at every instant, written without seconds when they are zero.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
+ *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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("Africa/Monrovia", "1970-01-01T12:00:00Z") // "-00:44:30" (an offset with seconds)
+ * @example getTimeZoneOffset("-00:44:30", "1970-01-01T12:00:00Z") // "-00:44:30" (its own result, read back)
+ * @example getTimeZoneOffset("+05:30:00", "1970-01-01T12:00:00Z") // "+05:30"
  * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
  * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
  * @example getTimeZoneOffset("America/New_York", "2024-07-15T16:00:00z") // "" (lower-case z)

package/dist/zoned/get/getTimeZoneOffset.js

@@ -1,9 +1,9 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { instantFrom } from "../../internal/instantNanoseconds.js";
 import { hasInstantShape } from "../../internal/isoStringBody.js";
 import { instantLeapSecond } from "../../regex/index.js";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameOffset, zoneFrame } from "../../internal/zoneFrame.js";
 /**
- * Return an IANA timeZone's UTC offset at a given instant.
+ * Return a time zone'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
@@ -18,14 +18,25 @@ import { isValidTimeZone } from "../validate/index.js";
  * - The instant is ISO 8601 extended format before any annotation (`<date>T<time>`, then `Z` or
  *   `±HH:MM[:SS[.fraction]]`): basic format, a `t` or space separator, a lower-case `z` and an
  *   hour-only offset return "".
+ * - Only the instant is read from `instant`, as `isValidInstant` describes it: a bracketed zone
+ *   in it is not validated, and an offset written to the minute that is that zone's sub-minute
+ *   offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives.
+ * - The result is `±HH:MM`, or `±HH:MM:SS` where the zone was not on a whole minute
+ *   (`Africa/Monrovia` stood at `-00:44:30` until 1972). It goes straight into the time zone
+ *   position of any function whose result has no zone in it, and of this one: a UTC offset is its
+ *   own answer at every instant, written without seconds when they are zero.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
+ *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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("Africa/Monrovia", "1970-01-01T12:00:00Z") // "-00:44:30" (an offset with seconds)
+ * @example getTimeZoneOffset("-00:44:30", "1970-01-01T12:00:00Z") // "-00:44:30" (its own result, read back)
+ * @example getTimeZoneOffset("+05:30:00", "1970-01-01T12:00:00Z") // "+05:30"
  * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
  * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
  * @example getTimeZoneOffset("America/New_York", "2024-07-15T16:00:00z") // "" (lower-case z)
@@ -36,13 +47,18 @@ export function getTimeZoneOffset(timeZone, instant) {
     if (typeof instant !== "string") {
         return "";
     }
-    if (!isValidTimeZone(timeZone) ||
+    const frame = zoneFrame(timeZone);
+    if (frame === null ||
         instantLeapSecond.test(instant) ||
         !hasInstantShape(instant)) {
         return "";
     }
     try {
-        return Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone).offset;
+        const at = instantFrom(instant);
+        // A stored offset with seconds is its own answer at every valid instant.
+        return frame.shiftNanoseconds !== 0n
+            ? frameOffset(frame)
+            : at.toZonedDateTimeISO(frame.timeZone).offset;
     }
     catch {
         return "";

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

@@ -4,7 +4,8 @@
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
  *
- * @param ianaTimezone IANA timeZone identifier
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedDay("America/New_York") // "28"

package/dist/zoned/get/getZonedDay.js

@@ -1,24 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.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
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .day.toString()
-            .padStart(2, "0");
+        return frameNowWallClock(frame).day.toString().padStart(2, "0");
     }
     catch {
         return "";

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

@@ -5,7 +5,8 @@
  * - Returns 1-7 (Monday=1 through Sunday=7).
  * - Validation is performed on the timezone.
  *
- * @param ianaTimezone IANA timeZone identifier
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day of week number (1-7) or null on invalid input
  *
  * @example getZonedDayOfWeek("America/New_York") // 3

package/dist/zoned/get/getZonedDayOfWeek.js

@@ -1,5 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
 /**
  * Return the current day of week for the specified IANA timeZone.
  *
@@ -7,17 +6,19 @@ import { isValidTimeZone } from "../validate/index.js";
  * - Returns 1-7 (Monday=1 through Sunday=7).
  * - Validation is performed on the timezone.
  *
- * @param ianaTimezone IANA timeZone identifier
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day of week number (1-7) or null on invalid input
  *
  * @example getZonedDayOfWeek("America/New_York") // 3
  * @example getZonedDayOfWeek("invalid") // null
  */
 export function getZonedDayOfWeek(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return null;
     try {
-        const now = Temporal.Now.zonedDateTimeISO(ianaTimezone);
+        const now = frameNowWallClock(frame);
         return now.dayOfWeek;
     }
     catch {

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

@@ -4,7 +4,8 @@
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
  *
- * @param ianaTimezone IANA timeZone identifier
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current hour string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedHour("America/New_York") // "19"

package/dist/zoned/get/getZonedHour.js

@@ -1,24 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
 /**
  * Return the current hour 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
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current hour string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedHour("America/New_York") // "19"
  * @example getZonedHour("invalid") // ""
  */
 export function getZonedHour(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .hour.toString()
-            .padStart(2, "0");
+        return frameNowWallClock(frame).hour.toString().padStart(2, "0");
     }
     catch {
         return "";

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

@@ -4,7 +4,8 @@
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
  *
- * @param ianaTimezone IANA timeZone identifier
+ * @param ianaTimezone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or
+ *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current microsecond string (zero-padded to 3 digits) or "" on invalid input
  *
  * @example getZonedMicrosecond("America/New_York") // "000"