@northguild/gmt 1.17.0 → 1.19.0

package/dist/zoned/get/getZonedMicrosecond.js

@@ -1,22 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
 /**
  * Return the current microsecond 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 microsecond string (zero-padded to 3 digits) or "" on invalid input
  *
  * @example getZonedMicrosecond("America/New_York") // "000"
  * @example getZonedMicrosecond("invalid") // ""
  */
 export function getZonedMicrosecond(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return (Temporal.Now.zonedDateTimeISO(ianaTimezone).microsecond ?? 0)
+        return (frameNowWallClock(frame).microsecond ?? 0)
             .toString()
             .padStart(3, "0");
     }

package/dist/zoned/get/getZonedMillisecond.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 millisecond string (zero-padded to 3 digits) or "" on invalid input
  *
  * @example getZonedMillisecond("America/New_York") // "000"

package/dist/zoned/get/getZonedMillisecond.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 millisecond 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 millisecond string (zero-padded to 3 digits) or "" on invalid input
  *
  * @example getZonedMillisecond("America/New_York") // "000"
  * @example getZonedMillisecond("invalid") // ""
  */
 export function getZonedMillisecond(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .millisecond.toString()
-            .padStart(3, "0");
+        return frameNowWallClock(frame).millisecond.toString().padStart(3, "0");
     }
     catch {
         return "";

package/dist/zoned/get/getZonedMinute.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 minute string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedMinute("America/New_York") // "00"

package/dist/zoned/get/getZonedMinute.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 minute 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 minute string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedMinute("America/New_York") // "00"
  * @example getZonedMinute("invalid") // ""
  */
 export function getZonedMinute(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .minute.toString()
-            .padStart(2, "0");
+        return frameNowWallClock(frame).minute.toString().padStart(2, "0");
     }
     catch {
         return "";

package/dist/zoned/get/getZonedMonth.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 month string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedMonth("America/New_York") // "02"

package/dist/zoned/get/getZonedMonth.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 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 month string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedMonth("America/New_York") // "02"
  * @example getZonedMonth("invalid") // ""
  */
 export function getZonedMonth(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .month.toString()
-            .padStart(2, "0");
+        return frameNowWallClock(frame).month.toString().padStart(2, "0");
     }
     catch {
         return "";

package/dist/zoned/get/getZonedNanosecond.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 nanosecond string (zero-padded to 3 digits) or "" on invalid input
  *
  * @example getZonedNanosecond("America/New_York") // "000"

package/dist/zoned/get/getZonedNanosecond.js

@@ -1,22 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
 /**
  * Return the current nanosecond 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 nanosecond string (zero-padded to 3 digits) or "" on invalid input
  *
  * @example getZonedNanosecond("America/New_York") // "000"
  * @example getZonedNanosecond("invalid") // ""
  */
 export function getZonedNanosecond(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return (Temporal.Now.zonedDateTimeISO(ianaTimezone).nanosecond ?? 0)
+        return (frameNowWallClock(frame).nanosecond ?? 0)
             .toString()
             .padStart(3, "0");
     }

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

@@ -4,14 +4,30 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
+ * - `smallestUnit` is the only option read. Any other key on `optionsArg` is ignored, so the
+ *   string always carries the offset and the bracketed time zone, and smaller units are always
+ *   truncated.
+ * - 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 ianaTimezone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond")
+ * @param ianaTimezone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 datetime string or "" on invalid input
  *
  * @example getZonedNow("America/New_York") // "2024-02-29T09:30:45.123-05:00[America/New_York]"
+ * @example getZonedNow("America/New_York", { smallestUnit: "second" }) // "2024-02-29T09:30:45-05:00[America/New_York]"
  * @example getZonedNow("Invalid/Zone") // ""
+ * @example getZonedNow("America/New_York", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
  */
 export declare function getZonedNow(ianaTimezone: string, optionsArg?: {
+    /**
+     * The smallest unit written in the output string, from `"minute"` to `"nanosecond"`, singular
+     * or plural. Anything smaller is truncated, as Temporal's `toString` does with its `"trunc"`
+     * rounding mode.
+     *
+     * @defaultValue `"millisecond"`
+     */
     smallestUnit?: Temporal.ZonedDateTimeToStringOptions["smallestUnit"];
 }): string;

package/dist/zoned/get/getZonedNow.js

@@ -1,27 +1,40 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTimeZone } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return the current zoned datetime for the specified IANA timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
+ * - `smallestUnit` is the only option read. Any other key on `optionsArg` is ignored, so the
+ *   string always carries the offset and the bracketed time zone, and smaller units are always
+ *   truncated.
+ * - 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 ianaTimezone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond")
+ * @param ianaTimezone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
+ * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 datetime string or "" on invalid input
  *
  * @example getZonedNow("America/New_York") // "2024-02-29T09:30:45.123-05:00[America/New_York]"
+ * @example getZonedNow("America/New_York", { smallestUnit: "second" }) // "2024-02-29T09:30:45-05:00[America/New_York]"
  * @example getZonedNow("Invalid/Zone") // ""
+ * @example getZonedNow("America/New_York", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
  */
 export function getZonedNow(ianaTimezone, optionsArg) {
     try {
         if (!isOptionsArgument(optionsArg)) {
             return "";
         }
+        // ECMA-402 GetOption (the Temporal specification defines the same operation): the option is
+        // read once, and a value of undefined is absent, so the default applies.
+        // Only smallestUnit is read: any other key on the caller's object (roundingMode, offset,
+        // timeZoneName, calendarName, fractionalSecondDigits) never reaches Temporal's toString.
         const options = {
-            smallestUnit: "millisecond",
-            ...optionsArg,
+            smallestUnit: optionOrDefault(optionsArg?.smallestUnit, "millisecond"),
         };
         if (!isValidTimeZone(ianaTimezone)) {
             return "";

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

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 /**
  * Units extractable from the current time in a specific IANA timeZone, as
  * consumed by `getZonedNowUnit`.
@@ -7,7 +7,7 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * | Member | Description |
  * | --- | --- |
- * | `year` | Full calendar year (e.g. `2024`), no padding. |
+ * | `year` | Four digits (e.g. `2024`, `0005`); a sign and six digits outside 0000–9999 (e.g. `+010000`). |
  * | `month` | 1–12, zero-padded to 2 digits (e.g. `02`). |
  * | `week` | Week-of-year from `parseWeekFromDate`, 1–53. |
  * | `day` | Day of month 1–31, zero-padded (e.g. `15`). |
@@ -32,8 +32,11 @@ export type ZonedNowUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "da
  * - Validation is performed on timezone and unit.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
- * @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)
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *

package/dist/zoned/get/getZonedNowUnit.js

@@ -1,7 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { zonedNowUnitValue } from "../../internal/zonedNowUnitValue.js";
 import { parseWeekFromDate } from "../../plain/parse/index.js";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 function isValidZonedNowUnit(unit) {
     return [
@@ -26,8 +25,11 @@ function isValidZonedNowUnit(unit) {
  * - Validation is performed on timezone and unit.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
- * @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)
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *
@@ -40,13 +42,14 @@ export function getZonedNowUnit(ianaTimezone, unit) {
         return "";
     }
     const resolvedUnit = resolveDateTimeUnit(unit);
-    if (!isValidTimeZone(ianaTimezone) || !isValidZonedNowUnit(resolvedUnit)) {
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null || !isValidZonedNowUnit(resolvedUnit)) {
         return "";
     }
     try {
-        const now = Temporal.Now.zonedDateTimeISO(ianaTimezone);
-        return zonedNowUnitValue(now, resolvedUnit, (zdt) => {
-            const w = parseWeekFromDate(zdt.toPlainDate().toString());
+        const now = frameNowWallClock(frame);
+        return zonedNowUnitValue(now, resolvedUnit, (wallClock) => {
+            const w = parseWeekFromDate(wallClock.toPlainDate().toString());
             return w === null ? "" : w.toString();
         });
     }

package/dist/zoned/get/getZonedSecond.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 second string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedSecond("America/New_York") // "00"

package/dist/zoned/get/getZonedSecond.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 second 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 second string (zero-padded to 2 digits) or "" on invalid input
  *
  * @example getZonedSecond("America/New_York") // "00"
  * @example getZonedSecond("invalid") // ""
  */
 export function getZonedSecond(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .second.toString()
-            .padStart(2, "0");
+        return frameNowWallClock(frame).second.toString().padStart(2, "0");
     }
     catch {
         return "";

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

@@ -4,7 +4,8 @@
  * - Uses Temporal.Now.zonedDateTimeISO to get current date in timezone.
  * - Returns "" for invalid 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 ISO date string (YYYY-MM-DD) or "" when invalid
  *
  * @example getZonedToday("America/New_York") // "2024-02-29"

package/dist/zoned/get/getZonedToday.js

@@ -1,23 +1,24 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
 /**
  * Return today's date in the given IANA timeZone as an ISO date string.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get current date in timezone.
  * - Returns "" for invalid 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 ISO date string (YYYY-MM-DD) or "" when invalid
  *
  * @example getZonedToday("America/New_York") // "2024-02-29"
  * @example getZonedToday("invalid") // ""
  */
 export function getZonedToday(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone)) {
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null) {
         return "";
     }
     try {
-        const today = Temporal.Now.zonedDateTimeISO(ianaTimezone).toPlainDate();
+        const today = frameNowWallClock(frame).toPlainDate();
         return today.toString();
     }
     catch {

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

@@ -5,7 +5,8 @@
  * - Uses Temporal.PlainDate.weekOfYear for ISO week number.
  * - 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 week number (1-53) or null on invalid input
  *
  * @example getZonedWeekOfYear("America/New_York") // 9

package/dist/zoned/get/getZonedWeekOfYear.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 week of year for the specified IANA timeZone.
  *
@@ -7,17 +6,19 @@ import { isValidTimeZone } from "../validate/index.js";
  * - Uses Temporal.PlainDate.weekOfYear for ISO week number.
  * - 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 week number (1-53) or null on invalid input
  *
  * @example getZonedWeekOfYear("America/New_York") // 9
  * @example getZonedWeekOfYear("invalid") // null
  */
 export function getZonedWeekOfYear(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.toPlainDate().weekOfYear ?? null;
     }
     catch {

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

@@ -3,8 +3,11 @@
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
+ * - The year is zero-padded to 4 digits. A year outside 0000–9999 is written with a sign and six
+ *   digits (`+010000`, `-000005`), as Temporal writes it at the head of a date.
  *
- * @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 year string (zero-padded to 4 digits) or "" on invalid input
  *
  * @example getZonedYear("America/New_York") // "2024"

package/dist/zoned/get/getZonedYear.js

@@ -1,24 +1,26 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../validate/index.js";
+import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the current year for the specified IANA timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
  * - Validation is performed on the timezone.
+ * - The year is zero-padded to 4 digits. A year outside 0000–9999 is written with a sign and six
+ *   digits (`+010000`, `-000005`), as Temporal writes it at the head of a date.
  *
- * @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 year string (zero-padded to 4 digits) or "" on invalid input
  *
  * @example getZonedYear("America/New_York") // "2024"
  * @example getZonedYear("invalid") // ""
  */
 export function getZonedYear(ianaTimezone) {
-    if (!isValidTimeZone(ianaTimezone))
+    const frame = zoneFrame(ianaTimezone);
+    if (frame === null)
         return "";
     try {
-        return Temporal.Now.zonedDateTimeISO(ianaTimezone)
-            .year.toString()
-            .padStart(4, "0");
+        return isoYearString(frameNowWallClock(frame).year);
     }
     catch {
         return "";

package/dist/zoned/interval/intervalDifferenceZoned.d.ts

@@ -39,6 +39,15 @@
  * @example intervalDifferenceZoned("invalid", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // []
  */
 export declare function intervalDifferenceZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/zoned/interval/intervalDivideEquallyZoned.d.ts

@@ -7,9 +7,13 @@
  * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds (real
  *   elapsed time, exact at any span length), so a spring-forward day split in half lands exactly
  *   on the DST transition's real midpoint rather than the local-clock midpoint.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
  *   an empty `[start, start)` that holds no instant.
+ * - `start` and `end` may name different time zones. The first `start` and every inner boundary
+ *   are written in `start`'s zone; the last `end` is the `end` argument, in its own zone.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
@@ -19,14 +23,12 @@
  *   unreadable as a set. A mismatch returns `[]`.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - An `n` over `options.maxPieces` returns `[]` before any piece is built.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)
@@ -37,8 +39,24 @@
  * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }, { start: "2024-01-02T00:00:00+00:00[UTC]", end: "2024-01-03T00:00:00+00:00[UTC]" }, { start: "2024-01-03T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
  */
 export declare function intervalDivideEquallyZoned(start: string, end: string, n: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/zoned/interval/intervalDivideEquallyZoned.js

@@ -13,9 +13,13 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds (real
  *   elapsed time, exact at any span length), so a spring-forward day split in half lands exactly
  *   on the DST transition's real midpoint rather than the local-clock midpoint.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
  *   an empty `[start, start)` that holds no instant.
+ * - `start` and `end` may name different time zones. The first `start` and every inner boundary
+ *   are written in `start`'s zone; the last `end` is the `end` argument, in its own zone.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
@@ -25,14 +29,12 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   unreadable as a set. A mismatch returns `[]`.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
+ * - An `n` over `options.maxPieces` returns `[]` before any piece is built.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)