@northguild/gmt 1.18.0 → 1.19.0

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

@@ -10,10 +10,23 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  *   equivalent to `.with()`'s, because Temporal's `ZonedDateTime.prototype.add()` doesn't accept
  *   `disambiguation`/`offset` at all.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op. `calendar`, `timeZone`, and `offset` are
- *   deliberately excluded from `fields` — this function only sets date/time components, never
- *   the zone or calendar identity, and `offset` is controlled separately via `options.offset`.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
+ * - `calendar`, `timeZone`, and `offset` are deliberately excluded from `fields` — this function
+ *   only sets date/time components, never the zone or calendar identity, and `offset` is
+ *   controlled separately via `options.offset`.
  * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
  *   to keep that resolution.
  * - Returns "" for invalid input.
@@ -29,9 +42,10 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset defaults to "prefer": the source's -05:00 is still valid, so it is kept and "reject" never fires)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "ignore" }) // "" (offset "ignore" re-resolves the repeated 01:00, and "reject" throws)
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: "9" }) // "" (not converted)
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
-export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset" | "era" | "eraYear">, options?: {
     /**
      * What happens when the result names a day its month does not have, such as setting `month: 2`
      * on 31 January. `"constrain"` clamps to the last valid day; `"reject"` returns `""`.

package/dist/zoned/calculate/setZoned.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow, withZonedFields, zonedDateTimeFrom, } from "../../internal/index.js";
+import { DATE_TIME_FIELDS, readSetFields, resolveOverflow, withZonedFields, zonedDateTimeFrom, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
@@ -13,10 +13,23 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *   equivalent to `.with()`'s, because Temporal's `ZonedDateTime.prototype.add()` doesn't accept
  *   `disambiguation`/`offset` at all.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op. `calendar`, `timeZone`, and `offset` are
- *   deliberately excluded from `fields` — this function only sets date/time components, never
- *   the zone or calendar identity, and `offset` is controlled separately via `options.offset`.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
+ * - `calendar`, `timeZone`, and `offset` are deliberately excluded from `fields` — this function
+ *   only sets date/time components, never the zone or calendar identity, and `offset` is
+ *   controlled separately via `options.offset`.
  * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
  *   to keep that resolution.
  * - Returns "" for invalid input.
@@ -32,6 +45,7 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset defaults to "prefer": the source's -05:00 is still valid, so it is kept and "reject" never fires)
  * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "ignore" }) // "" (offset "ignore" re-resolves the repeated 01:00, and "reject" throws)
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: "9" }) // "" (not converted)
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
 export function setZoned(value, fields, options) {
@@ -47,11 +61,14 @@ export function setZoned(value, fields, options) {
         const offset = optionOrDefault(options?.offset, "prefer");
         try {
             const zoned = zonedDateTimeFrom(value);
-            // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
-            // properties found") rather than treating it as a no-op, so short-circuit here.
-            if (Object.keys(fields).length === 0)
+            const set = readSetFields(fields, DATE_TIME_FIELDS);
+            if (set === null)
+                return "";
+            // Only the values readSetFields checked reach Temporal, on both paths of withZonedFields. An
+            // empty result sets nothing: a no-op here, where Temporal's with() would throw.
+            if (Object.keys(set).length === 0)
                 return zoned.toString();
-            return withZonedFields(zoned, fields, {
+            return withZonedFields(zoned, set, {
                 overflow,
                 disambiguation,
                 offset,

package/dist/zoned/calculate/subtractZoned.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, isValidAmount, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
+import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, parseCalendarZonedValue, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -58,11 +58,8 @@ export function subtractZoned(value, units, optionsArg) {
             return "";
         }
         const validZonedDateTime = isValidCalendarZonedDateTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validZonedDateTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validZonedDateTime || amounts === null) {
             return "";
         }
         const disambiguation = optionOrDefault(optionsArg?.disambiguation, "compatible");
@@ -73,7 +70,7 @@ export function subtractZoned(value, units, optionsArg) {
                 return "";
             }
             const zoned = parseCalendarZonedValue(value);
-            const subtracted = addToZonedDisambiguated(zoned, units, -1, {
+            const subtracted = addToZonedDisambiguated(zoned, amounts, -1, {
                 overflow,
                 disambiguation,
             });

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

@@ -9,9 +9,12 @@ import type { Disambiguation } from "../../types/index.js";
  * - **Output is cut to milliseconds by default**, so microseconds and nanoseconds in `value` are
  *   dropped. Pass `{ smallestUnit: "nanoseconds" }` to keep every digit.
  * - Returns "" for invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call `resolveLocal` for the
+ *   instant the wall time names at that offset.
  *
  * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
- * @param timeZone IANA name or UTC offset
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @param optionsArg optional settings for the precision of the output string and for resolving a DST gap or overlap
  * @returns zoned ISO 8601 datetime string or "" when invalid
  *

package/dist/zoned/convert/convertPlainDateTimeToZoned.js

@@ -13,9 +13,12 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  * - **Output is cut to milliseconds by default**, so microseconds and nanoseconds in `value` are
  *   dropped. Pass `{ smallestUnit: "nanoseconds" }` to keep every digit.
  * - Returns "" for invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call `resolveLocal` for the
+ *   instant the wall time names at that offset.
  *
  * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
- * @param timeZone IANA name or UTC offset
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @param optionsArg optional settings for the precision of the output string and for resolving a DST gap or overlap
  * @returns zoned ISO 8601 datetime string or "" when invalid
  *

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

@@ -3,9 +3,13 @@
  *
  * - Uses Temporal.ZonedDateTime.withTimeZone to convert.
  * - Returns "" for invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param value zoned ISO 8601 datetime string
- * @param timeZone target IANA name or UTC offset
+ * @param timeZone target IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @returns zoned ISO 8601 string in target timeZone or "" when invalid
  *
  * @example convertZonedToZoned("2024-02-29T12:34:56.789+00:00[UTC]", "America/New_York") // "2024-02-29T07:34:56.789-05:00[America/New_York]"

package/dist/zoned/convert/convertZonedToZoned.js

@@ -5,9 +5,13 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
  *
  * - Uses Temporal.ZonedDateTime.withTimeZone to convert.
  * - Returns "" for invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param value zoned ISO 8601 datetime string
- * @param timeZone target IANA name or UTC offset
+ * @param timeZone target IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @returns zoned ISO 8601 string in target timeZone or "" when invalid
  *
  * @example convertZonedToZoned("2024-02-29T12:34:56.789+00:00[UTC]", "America/New_York") // "2024-02-29T07:34:56.789-05:00[America/New_York]"

package/dist/zoned/format/formatCalendarZoned.js

@@ -5,6 +5,7 @@ import { isValidUtc } from "../../utc/validate/index.js";
 import { isValidZonedFormatReference } from "../../internal/zonedFormatReference.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Format a zoned date-time as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the zoned counterpart of `formatCalendar`. See
@@ -29,7 +30,7 @@ export function formatCalendarZoned(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidZonedDateTime(value))
             return "";

package/dist/zoned/format/formatRelativeZoned.js

@@ -4,6 +4,7 @@ import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js
 import { isValidUtc } from "../../utc/validate/index.js";
 import { isValidZonedFormatReference } from "../../internal/zonedFormatReference.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Format the relative time between a zoned date-time and a reference instant.
  *
@@ -34,7 +35,7 @@ export function formatRelativeZoned(value, locale, options = {}) {
     try {
         // Temporal GetOptionsObject: options must be an object or omitted; null and other primitives are
         // invalid input.
-        if (options === null || typeof options !== "object")
+        if (!isObject(options))
             return "";
         if (!isValidZonedDateTime(value))
             return "";

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

@@ -47,8 +47,12 @@ 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 name or UTC offset
+ * @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 setting for the form of the name
  * @returns localized zone name, or "" on invalid input

package/dist/zoned/format/formatTimeZoneName.js

@@ -20,8 +20,12 @@ import { optionOrDefault } from "../../internal/optionOrDefault.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 name or UTC offset
+ * @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 setting for the form of the name
  * @returns localized zone name, or "" on invalid input

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

@@ -35,10 +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 such as `"+05:30"` is a valid zone whose offset never changes,
- *   so it has no transitions and returns `[]` for every year.
+ * - 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 name or UTC offset
+ * @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,5 +53,6 @@ export interface DstTransition {
  * @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,5 +1,4 @@
-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;
@@ -20,10 +19,11 @@ const SEARCH_SPAN_NANOSECONDS = 368n * 86400000000000n;
  * - 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 such as `"+05:30"` is a valid zone whose offset never changes,
- *   so it has no transitions and returns `[]` for every year.
+ * - 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 name or UTC offset
+ * @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
  *
@@ -37,15 +37,20 @@ const SEARCH_SPAN_NANOSECONDS = 368n * 86400000000000n;
  * @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;

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
@@ -17,14 +17,22 @@
  * - 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 name or UTC offset
+ * @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 { 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
@@ -21,14 +21,22 @@ import { isValidTimeZone } from "../validate/index.js";
  * - 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 name or UTC offset
+ * @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)
@@ -39,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 instantFrom(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"